Source/cmTryRunCommand.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 cmTryRunCommand_h
  13 #define cmTryRunCommand_h
  14
  15 #include "cmCoreTryCompile.h"
  16
  17 /** \class cmTryRunCommand
  18  * \brief Specifies where to install some files
  19  *
  20  * cmTryRunCommand is used to test if soucre code can be compiled
  21  */
  22 class cmTryRunCommand : public cmCoreTryCompile
  23 {
  24 public:
  25   /**
  26    * This is a virtual constructor for the command.
  27    */
  28   virtual cmCommand* Clone()
  29     {
  30     return new cmTryRunCommand;
  31     }
  32
  33   /**
  34    * This is called when the command is first encountered in
  35    * the CMakeLists.txt file.
  36    */
  37   virtual bool InitialPass(std::vector<std::string> const& args,
  38                            cmExecutionStatus &status);
  39
  40   /**
  41    * The name of the command as specified in CMakeList.txt.
  42    */
  43   virtual const char* GetName() const { return "try_run";}
  44
  45   /**
  46    * Succinct documentation.
  47    */
  48   virtual const char* GetTerseDocumentation() const
  49     {
  50     return "Try compiling and then running some code.";
  51     }
  52
  53   /**
  54    * More documentation.
  55    */
  56   virtual const char* GetFullDocumentation() const
  57     {
  58     return
  59       "  try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR\n"
  60       "          bindir srcfile [CMAKE_FLAGS <Flags>]\n"
  61       "          [COMPILE_DEFINITIONS <flags>]\n"
  62       "          [COMPILE_OUTPUT_VARIABLE comp]\n"
  63       "          [RUN_OUTPUT_VARIABLE run]\n"
  64       "          [OUTPUT_VARIABLE var]\n"
  65       "          [ARGS <arg1> <arg2>...])\n"
  66       "Try compiling a srcfile.  Return TRUE or FALSE for success or failure "
  67       "in COMPILE_RESULT_VAR.  Then if the compile succeeded, run the "
  68       "executable and return its exit code in RUN_RESULT_VAR. "
  69       "If the executable was built, but failed to run, then RUN_RESULT_VAR "
  70       "will be set to FAILED_TO_RUN. "
  71       "COMPILE_OUTPUT_VARIABLE specifies the variable where the output from "
  72       "the compile step goes. RUN_OUTPUT_VARIABLE specifies the variable "
  73       "where the output from the running executable goes.\n"
  74       "For compatibility reasons OUTPUT_VARIABLE is still supported, which "
  75       "gives you the output from the compile and run step combined.\n"
  76       "Cross compiling issues\n"
  77       "When cross compiling, the executable compiled in the first step "
  78       "usually cannot be run on the build host. try_run() checks the "
  79       "CMAKE_CROSSCOMPILING variable to detect whether CMake is in "
  80       "crosscompiling mode. If that's the case, it will still try to compile "
  81       "the executable, but it will not try to run the executable. Instead it "
  82       "will create cache variables which must be filled by the user or by "
  83       "presetting them in some CMake script file to the values the "
  84       "executable would have produced if it had been run on its actual "
  85       "target platform. These variables are RUN_RESULT_VAR (explanation see "
  86       "above) and if RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) was used, an "
  87       "additional cache variable "
  88       "RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT."
  89       "This is intended to hold stdout and stderr from the executable.\n"
  90       "In order to make cross compiling your project easier, use try_run "
  91       "only if really required. If you use try_run, use RUN_OUTPUT_VARIABLE "
  92       "(or OUTPUT_VARIABLE) only if really required. Using them will require "
  93       "that when crosscompiling, the cache variables will have to be set "
  94       "manually to the output of the executable. You can also \"guard\" the "
  95       "calls to try_run with if(CMAKE_CROSSCOMPILING) and provide an "
  96       "easy-to-preset alternative for this case.\n"
  97       "Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build "
  98       "configuration."
  99       ;
 100     }
 101
 102   cmTypeMacro(cmTryRunCommand, cmCoreTryCompile);
 103 private:
 104   void RunExecutable(const std::string& runArgs,
 105                      std::string* runOutputContents);
 106   void DoNotRunExecutable(const std::string& runArgs,
 107                           const std::string& srcFile,
 108                           std::string* runOutputContents);
 109
 110   std::string CompileResultVariable;
 111   std::string RunResultVariable;
 112   std::string OutputVariable;
 113   std::string RunOutputVariable;
 114   std::string CompileOutputVariable;
 115 };
 116
 117
 118 #endif