Source/cmCommand.h

   1 /*============================================================================
   2   CMake - Cross Platform Makefile Generator
   3   Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
   4
   5   Distributed under the OSI-approved BSD License (the "License");
   6   see accompanying file Copyright.txt for details.
   7
   8   This software is distributed WITHOUT ANY WARRANTY; without even the
   9   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  10   See the License for more information.
  11 ============================================================================*/
  12 #ifndef cmCommand_h
  13 #define cmCommand_h
  14
  15 #include "cmObject.h"
  16 #include "cmListFileCache.h"
  17 #include "cmMakefile.h"
  18 #include "cmCommandArgumentsHelper.h"
  19
  20 /** \class cmCommand
  21  * \brief Superclass for all commands in CMake.
  22  *
  23  * cmCommand is the base class for all commands in CMake. A command
  24  * manifests as an entry in CMakeLists.txt and produces one or
  25  * more makefile rules. Commands are associated with a particular
  26  * makefile. This base class cmCommand defines the API for commands
  27  * to support such features as enable/disable, inheritance,
  28  * documentation, and construction.
  29  */
  30 class cmCommand : public cmObject
  31 {
  32 public:
  33   cmTypeMacro(cmCommand, cmObject);
  34
  35   /**
  36    * Construct the command. By default it is enabled with no makefile.
  37    */
  38   cmCommand()
  39     {this->Makefile = 0; this->Enabled = true;}
  40
  41   /**
  42    * Need virtual destructor to destroy real command type.
  43    */
  44   virtual ~cmCommand() {}
  45
  46   /**
  47    * Specify the makefile.
  48    */
  49   void SetMakefile(cmMakefile*m)
  50     {this->Makefile = m; }
  51   cmMakefile* GetMakefile() { return this->Makefile; }
  52
  53   /**
  54    * This is called by the cmMakefile when the command is first
  55    * encountered in the CMakeLists.txt file.  It expands the command's
  56    * arguments and then invokes the InitialPass.
  57    */
  58   virtual bool InvokeInitialPass(const std::vector<cmListFileArgument>& args,
  59                                  cmExecutionStatus &status)
  60     {
  61     std::vector<std::string> expandedArguments;
  62     if(!this->Makefile->ExpandArguments(args, expandedArguments))
  63       {
  64       // There was an error expanding arguments.  It was already
  65       // reported, so we can skip this command without error.
  66       return true;
  67       }
  68     return this->InitialPass(expandedArguments,status);
  69     }
  70
  71   /**
  72    * This is called when the command is first encountered in
  73    * the CMakeLists.txt file.
  74    */
  75   virtual bool InitialPass(std::vector<std::string> const& args,
  76                            cmExecutionStatus &) = 0;
  77
  78   /**
  79    * This is called at the end after all the information
  80    * specified by the command is accumulated. Most commands do
  81    * not implement this method.  At this point, reading and
  82    * writing to the cache can be done.
  83    */
  84   virtual void FinalPass() {};
  85
  86   /**
  87    * Does this command have a final pass?  Query after InitialPass.
  88    */
  89   virtual bool HasFinalPass() const { return false; }
  90
  91   /**
  92    * This is a virtual constructor for the command.
  93    */
  94   virtual cmCommand* Clone() = 0;
  95
  96   /**
  97    * This determines if the command is invoked when in script mode.
  98    */
  99   virtual bool IsScriptable() const
 100     {
 101     return false;
 102     }
 103
 104   /**
 105    * This determines if usage of the method is discouraged or not.
 106    * This is currently only used for generating the documentation.
 107    */
 108   virtual bool IsDiscouraged() const
 109     {
 110     return false;
 111     }
 112
 113   /**
 114    * This is used to avoid including this command
 115    * in documentation. This is mainly used by
 116    * cmMacroHelperCommand and cmFunctionHelperCommand
 117    * which cannot provide appropriate documentation.
 118    */
 119   virtual bool ShouldAppearInDocumentation() const
 120     {
 121     return true;
 122     }
 123
 124   /**
 125    * The name of the command as specified in CMakeList.txt.
 126    */
 127   virtual const char* GetName() const = 0;
 128
 129   /**
 130    * Succinct documentation.
 131    */
 132   virtual const char* GetTerseDocumentation() const = 0;
 133
 134   /**
 135    * More documentation.
 136    */
 137   virtual const char* GetFullDocumentation() const = 0;
 138
 139   /**
 140    * Enable the command.
 141    */
 142   void EnabledOn()
 143     {this->Enabled = true;}
 144
 145   /**
 146    * Disable the command.
 147    */
 148   void EnabledOff()
 149     {this->Enabled = false;}
 150
 151   /**
 152    * Query whether the command is enabled.
 153    */
 154   bool GetEnabled() const
 155     {return this->Enabled;}
 156
 157   /**
 158    * Disable or enable the command.
 159    */
 160   void SetEnabled(bool enabled)
 161     {this->Enabled = enabled;}
 162
 163   /**
 164    * Return the last error string.
 165    */
 166   const char* GetError()
 167     {
 168       if(this->Error.length() == 0)
 169         {
 170         this->Error = this->GetName();
 171         this->Error += " unknown error.";
 172         }
 173       return this->Error.c_str();
 174     }
 175
 176   /**
 177    * Set the error message
 178    */
 179   void SetError(const char* e)
 180     {
 181     this->Error = this->GetName();
 182     this->Error += " ";
 183     this->Error += e;
 184     }
 185
 186 protected:
 187   cmMakefile* Makefile;
 188   cmCommandArgumentsHelper Helper;
 189
 190 private:
 191   bool Enabled;
 192   std::string Error;
 193 };
 194
 195 #endif