Source/cmExecuteProcessCommand.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 cmExecuteProcessCommand_h
  13 #define cmExecuteProcessCommand_h
  14
  15 #include "cmCommand.h"
  16
  17 /** \class cmExecuteProcessCommand
  18  * \brief Command that adds a target to the build system.
  19  *
  20  * cmExecuteProcessCommand is a CMake language interface to the KWSys
  21  * Process Execution implementation.
  22  */
  23 class cmExecuteProcessCommand : public cmCommand
  24 {
  25 public:
  26   /**
  27    * This is a virtual constructor for the command.
  28    */
  29   virtual cmCommand* Clone()
  30     {
  31     return new cmExecuteProcessCommand;
  32     }
  33
  34   /**
  35    * This is called when the command is first encountered in
  36    * the CMakeLists.txt file.
  37    */
  38   virtual bool InitialPass(std::vector<std::string> const& args,
  39                            cmExecutionStatus &status);
  40
  41   /**
  42    * The name of the command as specified in CMakeList.txt.
  43    */
  44   virtual const char* GetName() const
  45     {return "execute_process";}
  46
  47   /**
  48    * This determines if the command is invoked when in script mode.
  49    */
  50   virtual bool IsScriptable() const { return true; }
  51
  52   /**
  53    * Succinct documentation.
  54    */
  55   virtual const char* GetTerseDocumentation() const
  56     {
  57     return "Execute one or more child processes.";
  58     }
  59
  60   /**
  61    * More documentation.
  62    */
  63   virtual const char* GetFullDocumentation() const
  64     {
  65     return
  66       "  execute_process(COMMAND <cmd1> [args1...]]\n"
  67       "                  [COMMAND <cmd2> [args2...] [...]]\n"
  68       "                  [WORKING_DIRECTORY <directory>]\n"
  69       "                  [TIMEOUT <seconds>]\n"
  70       "                  [RESULT_VARIABLE <variable>]\n"
  71       "                  [OUTPUT_VARIABLE <variable>]\n"
  72       "                  [ERROR_VARIABLE <variable>]\n"
  73       "                  [INPUT_FILE <file>]\n"
  74       "                  [OUTPUT_FILE <file>]\n"
  75       "                  [ERROR_FILE <file>]\n"
  76       "                  [OUTPUT_QUIET]\n"
  77       "                  [ERROR_QUIET]\n"
  78       "                  [OUTPUT_STRIP_TRAILING_WHITESPACE]\n"
  79       "                  [ERROR_STRIP_TRAILING_WHITESPACE])\n"
  80       "Runs the given sequence of one or more commands with the standard "
  81       "output of each process piped to the standard input of the next.  "
  82       "A single standard error pipe is used for all processes.  "
  83       "If WORKING_DIRECTORY is given the named directory will be set as "
  84       "the current working directory of the child processes.  "
  85       "If TIMEOUT is given the child processes will be terminated if they "
  86       "do not finish in the specified number of seconds "
  87       "(fractions are allowed).  "
  88       "If RESULT_VARIABLE is given the variable will be set to contain "
  89       "the result of running the processes.  This will be an integer return "
  90       "code from the last child or a string describing an error condition.  "
  91       "If OUTPUT_VARIABLE or ERROR_VARIABLE are given the variable named "
  92       "will be set with the contents of the standard output and standard "
  93       "error pipes respectively.  If the same variable is named for both "
  94       "pipes their output will be merged in the order produced.  "
  95       "If INPUT_FILE, OUTPUT_FILE, or ERROR_FILE is given the file named "
  96       "will be attached to the standard input of the first process, "
  97       "standard output of the last process, or standard error of all "
  98       "processes respectively.  "
  99       "If OUTPUT_QUIET or ERROR_QUIET is given then the standard output "
 100       "or standard error results will be quietly ignored.  "
 101       "If more than one OUTPUT_* or ERROR_* option is given for the same "
 102       "pipe the precedence is not specified.  "
 103       "If no OUTPUT_* or ERROR_* options are given the output will be shared "
 104       "with the corresponding pipes of the CMake process itself.\n"
 105       "The execute_process command is a newer more powerful version of "
 106       "exec_program, but the old command has been kept for compatibility."
 107       ;
 108     }
 109
 110   cmTypeMacro(cmExecuteProcessCommand, cmCommand);
 111 };
 112
 113 #endif