Source/cmake.h

   1 /*=========================================================================
   2
   3   Program:   CMake - Cross-Platform Makefile Generator
   4   Module:    $RCSfile: cmake.h,v $
   5   Language:  C++
   6   Date:      $Date: 2008-01-17 23:13:55 $
   7   Version:   $Revision: 1.99 $
   8
   9   Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
  10   See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details.
  11
  12      This software is distributed WITHOUT ANY WARRANTY; without even
  13      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14      PURPOSE.  See the above copyright notices for more information.
  15
  16 =========================================================================*/
  17 // This class represents a cmake invocation. It is the top level class when
  18 // running cmake. Most cmake based GUIS should primarily create an instance
  19 // of this class and communicate with it.
  20 //
  21 // The basic process for a GUI is as follows:
  22 //
  23 // 1) Create a cmake instance
  24 // 2) Set the Home & Start directories, generator, and cmake command. this
  25 //    can be done using the Set methods or by using SetArgs and passing in
  26 //    command line arguments.
  27 // 3) Load the cache by calling LoadCache (duh)
  28 // 4) if you are using command line arguments with -D or -C flags then
  29 //    call SetCacheArgs (or if for some other reason you want to modify the
  30 //    cache, do it now.
  31 // 5) Finally call Configure
  32 // 6) Let the user change values and go back to step 5
  33 // 7) call Generate
  34 //
  35 // If your GUI allows the user to change the start & home directories then
  36 // you must at a minimum redo steps 2 through 7.
  37 //
  38
  39
  40 #ifndef cmake_h
  41 #define cmake_h
  42
  43 #include "cmSystemTools.h"
  44 #include "cmPropertyDefinitionMap.h"
  45 #include "cmPropertyMap.h"
  46
  47 class cmGlobalGenerator;
  48 class cmLocalGenerator;
  49 class cmCacheManager;
  50 class cmMakefile;
  51 class cmCommand;
  52 class cmVariableWatch;
  53 class cmFileTimeComparison;
  54 class cmExternalMakefileProjectGenerator;
  55 class cmDocumentationSection;
  56
  57 class cmake
  58 {
  59  public:
  60   typedef std::map<cmStdString, cmCommand*> RegisteredCommandsMap;
  61
  62   ///! construct an instance of cmake
  63   cmake();
  64   ///! destruct an instance of cmake
  65   ~cmake();
  66
  67   ///! construct an instance of cmake
  68   static const char *GetCMakeFilesDirectory() {return "/CMakeFiles";};
  69   static const char *GetCMakeFilesDirectoryPostSlash() {
  70     return "CMakeFiles/";};
  71
  72   //@{
  73   /**
  74    * Set/Get the home directory (or output directory) in the project. The
  75    * home directory is the top directory of the project. It is where
  76    * cmake was run. Remember that CMake processes
  77    * CMakeLists files by recursing up the tree starting at the StartDirectory
  78    * and going up until it reaches the HomeDirectory.
  79    */
  80   void SetHomeDirectory(const char* dir);
  81   const char* GetHomeDirectory() const
  82     {
  83     return this->cmHomeDirectory.c_str();
  84     }
  85   void SetHomeOutputDirectory(const char* lib);
  86   const char* GetHomeOutputDirectory() const
  87     {
  88     return this->HomeOutputDirectory.c_str();
  89     }
  90   //@}
  91
  92   //@{
  93   /**
  94    * Set/Get the start directory (or output directory). The start directory
  95    * is the directory of the CMakeLists.txt file that started the current
  96    * round of processing. Remember that CMake processes CMakeLists files by
  97    * recursing up the tree starting at the StartDirectory and going up until
  98    * it reaches the HomeDirectory.
  99    */
 100   void SetStartDirectory(const char* dir)
 101     {
 102       this->cmStartDirectory = dir;
 103       cmSystemTools::ConvertToUnixSlashes(this->cmStartDirectory);
 104     }
 105   const char* GetStartDirectory() const
 106     {
 107       return this->cmStartDirectory.c_str();
 108     }
 109   void SetStartOutputDirectory(const char* lib)
 110     {
 111       this->StartOutputDirectory = lib;
 112       cmSystemTools::ConvertToUnixSlashes(this->StartOutputDirectory);
 113     }
 114   const char* GetStartOutputDirectory() const
 115     {
 116       return this->StartOutputDirectory.c_str();
 117     }
 118   //@}
 119
 120   /**
 121    * Dump documentation to a file. If 0 is returned, the
 122    * operation failed.
 123    */
 124   int DumpDocumentationToFile(std::ostream&);
 125
 126   /**
 127    * Handle a command line invocation of cmake.
 128    */
 129   int Run(const std::vector<std::string>&args)
 130     { return this->Run(args, false); }
 131   int Run(const std::vector<std::string>&args, bool noconfigure);
 132
 133   /**
 134    * Run the global generator Generate step.
 135    */
 136   int Generate();
 137
 138   /**
 139    * Configure the cmMakefiles. This routine will create a GlobalGenerator if
 140    * one has not already been set. It will then Call Configure on the
 141    * GlobalGenerator. This in turn will read in an process all the CMakeList
 142    * files for the tree. It will not produce any actual Makefiles, or
 143    * workspaces. Generate does that.  */
 144   int Configure();
 145   int ActualConfigure();
 146
 147   /**
 148    * Configure the cmMakefiles. This routine will create a GlobalGenerator if
 149    * one has not already been set. It will then Call Configure on the
 150    * GlobalGenerator. This in turn will read in an process all the CMakeList
 151    * files for the tree. It will not produce any actual Makefiles, or
 152    * workspaces. Generate does that.  */
 153   int LoadCache();
 154   void PreLoadCMakeFiles();
 155
 156   ///! Create a GlobalGenerator
 157   cmGlobalGenerator* CreateGlobalGenerator(const char* name);
 158
 159   ///! Return the global generator assigned to this instance of cmake
 160   cmGlobalGenerator* GetGlobalGenerator()     { return this->GlobalGenerator; }
 161   ///! Return the global generator assigned to this instance of cmake, const
 162   const cmGlobalGenerator* GetGlobalGenerator() const
 163                                               { return this->GlobalGenerator; }
 164
 165   ///! Return the global generator assigned to this instance of cmake
 166   void SetGlobalGenerator(cmGlobalGenerator *);
 167
 168   ///! Get the names of the current registered generators
 169   void GetRegisteredGenerators(std::vector<std::string>& names);
 170
 171   ///! get the cmCachemManager used by this invocation of cmake
 172   cmCacheManager *GetCacheManager() { return this->CacheManager; }
 173
 174   ///! set the cmake command this instance of cmake should use
 175   void SetCMakeCommand(const char* cmd) { this->CMakeCommand = cmd; }
 176
 177   /**
 178    * Given a variable name, return its value (as a string).
 179    */
 180   const char* GetCacheDefinition(const char*) const;
 181   ///! Add an entry into the cache
 182   void AddCacheEntry(const char* key, const char* value,
 183                      const char* helpString,
 184                      int type);
 185   /**
 186    * Execute commands during the build process. Supports options such
 187    * as echo, remove file etc.
 188    */
 189   static int ExecuteCMakeCommand(std::vector<std::string>&);
 190
 191   /**
 192    * Get the system information and write it to the file specified
 193    */
 194   int GetSystemInformation(std::vector<std::string>&);
 195
 196   /**
 197    * Add a command to this cmake instance
 198    */
 199   void AddCommand(cmCommand* );
 200   void RenameCommand(const char* oldName, const char* newName);
 201   void RemoveCommand(const char* name);
 202   void RemoveUnscriptableCommands();
 203
 204   /**
 205    * Get a command by its name
 206    */
 207   cmCommand *GetCommand(const char *name);
 208
 209   /** Get list of all commands */
 210   RegisteredCommandsMap* GetCommands() { return &this->Commands; }
 211
 212   /** Check if a command exists. */
 213   bool CommandExists(const char* name) const;
 214
 215   ///! Parse command line arguments
 216   void SetArgs(const std::vector<std::string>&);
 217
 218   ///! Is this cmake running as a result of a TRY_COMPILE command
 219   bool GetIsInTryCompile() { return this->InTryCompile; }
 220
 221   ///! Is this cmake running as a result of a TRY_COMPILE command
 222   void SetIsInTryCompile(bool i) { this->InTryCompile = i; }
 223
 224   ///! Parse command line arguments that might set cache values
 225   bool SetCacheArgs(const std::vector<std::string>&);
 226
 227   typedef  void (*ProgressCallbackType)
 228     (const char*msg, float progress, void *);
 229   /**
 230    *  Set the function used by GUI's to receive progress updates
 231    *  Function gets passed: message as a const char*, a progress
 232    *  amount ranging from 0 to 1.0 and client data. The progress
 233    *  number provided may be negative in cases where a message is
 234    *  to be displayed without any progress percentage.
 235    */
 236   void SetProgressCallback(ProgressCallbackType f, void* clientData=0);
 237
 238   ///! this is called by generators to update the progress
 239   void UpdateProgress(const char *msg, float prog);
 240
 241
 242   ///! Get the variable watch object
 243   cmVariableWatch* GetVariableWatch() { return this->VariableWatch; }
 244
 245   /** Get the documentation entries for the supported commands.
 246    *  If withCurrentCommands is true, the documentation for the
 247    *  recommended set of commands is included.
 248    *  If withCompatCommands is true, the documentation for discouraged
 249    *  (compatibility) commands is included.
 250    *  You probably don't want to set both to false.
 251    */
 252   void GetCommandDocumentation(std::vector<cmDocumentationEntry>& entries,
 253                                bool withCurrentCommands = true,
 254                                bool withCompatCommands = true) const;
 255   void GetPropertiesDocumentation(std::map<std::string,
 256                                   cmDocumentationSection *>&);
 257   void GetGeneratorDocumentation(std::vector<cmDocumentationEntry>&);
 258
 259   ///! Set/Get a property of this target file
 260   void SetProperty(const char *prop, const char *value);
 261   void AppendProperty(const char *prop, const char *value);
 262   const char *GetProperty(const char *prop);
 263   const char *GetProperty(const char *prop, cmProperty::ScopeType scope);
 264   bool GetPropertyAsBool(const char *prop);
 265
 266   // Get the properties
 267   cmPropertyMap &GetProperties() { return this->Properties; };
 268
 269   ///! Do all the checks before running configure
 270   int DoPreConfigureChecks();
 271
 272   /**
 273    * Set and get the script mode option. In script mode there is no
 274    * generator and no cache. Also, language are not enabled, so
 275    * add_executable and things do not do anything.
 276    */
 277   void SetScriptMode(bool mode) { this->ScriptMode = mode; }
 278   bool GetScriptMode() { return this->ScriptMode; }
 279
 280   ///! Debug the try compile stuff by not delelting the files
 281   bool GetDebugTryCompile(){return this->DebugTryCompile;}
 282   void DebugTryCompileOn(){this->DebugTryCompile = true;}
 283
 284   ///! Get the list of files written by CMake using FILE(WRITE / WRITE_FILE
 285   void AddWrittenFile(const char* file);
 286   bool HasWrittenFile(const char* file);
 287   void CleanupWrittenFiles();
 288
 289   /**
 290    * Generate CMAKE_ROOT and CMAKE_COMMAND cache entries
 291    */
 292   int AddCMakePaths();
 293
 294   /**
 295    * Get the file comparison class
 296    */
 297   cmFileTimeComparison* GetFileComparison() { return this->FileComparison; }
 298
 299   /**
 300    * Get the path to ctest
 301    */
 302   const char* GetCTestCommand();
 303   const char* GetCPackCommand();
 304   const char* GetCMakeCommand() const { return this->CMakeCommand.c_str(); }
 305
 306   // Do we want debug output during the cmake run.
 307   bool GetDebugOutput() { return this->DebugOutput; }
 308   void DebugOutputOn() { this->DebugOutput = true;}
 309
 310   // Define a property
 311   void DefineProperty(const char *name, cmProperty::ScopeType scope,
 312                       const char *ShortDescription,
 313                       const char *FullDescription,
 314                       bool chain = false,
 315                       const char *variableGroup = 0);
 316
 317   // get property definition
 318   cmPropertyDefinition *GetPropertyDefinition
 319   (const char *name, cmProperty::ScopeType scope);
 320
 321   // Is a property defined?
 322   bool IsPropertyDefined(const char *name, cmProperty::ScopeType scope);
 323   bool IsPropertyChained(const char *name, cmProperty::ScopeType scope);
 324
 325   // record accesses of properties and variables
 326   void RecordPropertyAccess(const char *name, cmProperty::ScopeType scope);
 327   void ReportUndefinedPropertyAccesses(const char *filename);
 328
 329   // Define the properties
 330   static void DefineProperties(cmake *cm);
 331
 332 protected:
 333   int HandleDeleteCacheVariables(const char* var);
 334   cmPropertyMap Properties;
 335   std::set<std::pair<cmStdString,cmProperty::ScopeType> > AccessedProperties;
 336
 337   std::map<cmProperty::ScopeType, cmPropertyDefinitionMap>
 338   PropertyDefinitions;
 339
 340   typedef
 341      cmExternalMakefileProjectGenerator* (*CreateExtraGeneratorFunctionType)();
 342   typedef std::map<cmStdString,
 343                 CreateExtraGeneratorFunctionType> RegisteredExtraGeneratorsMap;
 344
 345   typedef cmGlobalGenerator* (*CreateGeneratorFunctionType)();
 346   typedef std::map<cmStdString,
 347                    CreateGeneratorFunctionType> RegisteredGeneratorsMap;
 348   RegisteredCommandsMap Commands;
 349   RegisteredGeneratorsMap Generators;
 350   RegisteredExtraGeneratorsMap ExtraGenerators;
 351   void AddDefaultCommands();
 352   void AddDefaultGenerators();
 353   void AddDefaultExtraGenerators();
 354   void AddExtraGenerator(const char* name,
 355                          CreateExtraGeneratorFunctionType newFunction);
 356
 357   cmGlobalGenerator *GlobalGenerator;
 358   cmCacheManager *CacheManager;
 359   std::string cmHomeDirectory;
 360   std::string HomeOutputDirectory;
 361   std::string cmStartDirectory;
 362   std::string StartOutputDirectory;
 363
 364   std::set<cmStdString> WrittenFiles;
 365
 366   ///! return true if the same cmake was used to make the cache.
 367   bool CacheVersionMatches();
 368   ///! read in a cmake list file to initialize the cache
 369   void ReadListFile(const char *path);
 370
 371   ///! Check if CMAKE_CACHEFILE_DIR is set. If it is not, delete the log file.
 372   ///  If it is set, truncate it to 50kb
 373   void TruncateOutputLog(const char* fname);
 374
 375   /**
 376    * Method called to check build system integrity at build time.
 377    * Returns 1 if CMake should rerun and 0 otherwise.
 378    */
 379   int CheckBuildSystem();
 380
 381   void SetDirectoriesFromFile(const char* arg);
 382
 383   //! Make sure all commands are what they say they are and there is no
 384   //macros.
 385   void CleanupCommandsAndMacros();
 386
 387   void GenerateGraphViz(const char* fileName) const;
 388
 389   static int ExecuteEchoColor(std::vector<std::string>& args);
 390   static int ExecuteLinkScript(std::vector<std::string>& args);
 391   static int VisualStudioLink(std::vector<std::string>& args, int type);
 392   static int VisualStudioLinkIncremental(std::vector<std::string>& args,
 393                                          int type,
 394                                          bool verbose);
 395   static int VisualStudioLinkNonIncremental(std::vector<std::string>& args,
 396                                             int type,
 397                                             bool verbose);
 398   static int ParseVisualStudioLinkCommand(std::vector<std::string>& args,
 399                                           std::vector<cmStdString>& command,
 400                                           std::string& targetName);
 401   static bool RunCommand(const char* comment,
 402                          std::vector<cmStdString>& command,
 403                          bool verbose,
 404                          int* retCodeOut = 0);
 405   cmVariableWatch* VariableWatch;
 406
 407   ///! Find the full path to one of the cmake programs like ctest, cpack, etc.
 408   std::string FindCMakeProgram(const char* name) const;
 409 private:
 410   ProgressCallbackType ProgressCallback;
 411   void* ProgressCallbackClientData;
 412   bool Verbose;
 413   bool InTryCompile;
 414   bool ScriptMode;
 415   bool DebugOutput;
 416   std::string CMakeCommand;
 417   std::string CXXEnvironment;
 418   std::string CCEnvironment;
 419   std::string CheckBuildSystemArgument;
 420   std::string CheckStampFile;
 421   std::string VSSolutionFile;
 422   std::string CTestCommand;
 423   std::string CPackCommand;
 424   bool ClearBuildSystem;
 425   bool DebugTryCompile;
 426   cmFileTimeComparison* FileComparison;
 427   std::string GraphVizFile;
 428
 429   void UpdateConversionPathTable();
 430 };
 431
 432 #define CMAKE_STANDARD_OPTIONS_TABLE \
 433   {"-C <initial-cache>", "Pre-load a script to populate the cache.", \
 434    "When cmake is first run in an empty build tree, it creates a " \
 435    "CMakeCache.txt file and populates it with customizable settings " \
 436    "for the project.  This option may be used to specify a file from " \
 437    "which to load cache entries before the first pass through " \
 438    "the project's cmake listfiles.  The loaded entries take priority " \
 439    "over the project's default values.  The given file should be a CMake " \
 440    "script containing SET commands that use the CACHE option, " \
 441    "not a cache-format file."}, \
 442   {"-D <var>:<type>=<value>", "Create a cmake cache entry.", \
 443    "When cmake is first run in an empty build tree, it creates a " \
 444    "CMakeCache.txt file and populates it with customizable settings " \
 445    "for the project.  This option may be used to specify a setting " \
 446    "that takes priority over the project's default value.  The option " \
 447    "may be repeated for as many cache entries as desired."}, \
 448   {"-U <globbing_expr>", "Remove matching entries from CMake cache.", \
 449    "This option may be used to remove one or more variables from the " \
 450    "CMakeCache.txt file, globbing expressions using * and ? are supported. "\
 451    "The option may be repeated for as many cache entries as desired.\n" \
 452    "Use with care, you can make your CMakeCache.txt non-working."}, \
 453   {"-G <generator-name>", "Specify a makefile generator.", \
 454    "CMake may support multiple native build systems on certain platforms.  " \
 455    "A makefile generator is responsible for generating a particular build " \
 456    "system.  Possible generator names are specified in the Generators " \
 457    "section."}
 458
 459 #define CMAKE_STANDARD_INTRODUCTION \
 460   {0, \
 461    "CMake is a cross-platform build system generator.  Projects " \
 462    "specify their build process with platform-independent CMake listfiles " \
 463    "included in each directory of a source tree with the name " \
 464    "CMakeLists.txt. " \
 465    "Users build a project by using CMake to generate a build system " \
 466    "for a native tool on their platform.", 0}
 467 #endif