Source/cmake.h

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