Source/cmSetTargetPropertiesCommand.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 cmSetTargetsPropertiesCommand_h
  13 #define cmSetTargetsPropertiesCommand_h
  14
  15 #include "cmCommand.h"
  16
  17 class cmSetTargetPropertiesCommand : public cmCommand
  18 {
  19 public:
  20   virtual cmCommand* Clone()
  21     {
  22       return new cmSetTargetPropertiesCommand;
  23     }
  24
  25   /**
  26    * This is called when the command is first encountered in
  27    * the input file.
  28    */
  29   virtual bool InitialPass(std::vector<std::string> const& args,
  30                            cmExecutionStatus &status);
  31
  32   /**
  33    * The name of the command as specified in CMakeList.txt.
  34    */
  35   virtual const char* GetName() const { return "set_target_properties";}
  36
  37   /**
  38    * Succinct documentation.
  39    */
  40   virtual const char* GetTerseDocumentation() const
  41     {
  42     return "Targets can have properties that affect how they are built.";
  43     }
  44
  45   /**
  46    *  Used by this command and cmSetPropertiesCommand
  47    */
  48   static bool SetOneTarget(const char *tname,
  49                            std::vector<std::string> &propertyPairs,
  50                            cmMakefile *mf);
  51
  52   /**
  53    * Longer documentation.
  54    */
  55   virtual const char* GetFullDocumentation() const
  56     {
  57       return
  58         "  set_target_properties(target1 target2 ...\n"
  59         "                        PROPERTIES prop1 value1\n"
  60         "                        prop2 value2 ...)\n"
  61         "Set properties on a target. The syntax for the command is to "
  62         "list all the files you want "
  63         "to change, and then provide the values you want to set next.  "
  64         "You can use any prop value pair you want and "
  65         "extract it later with the GET_TARGET_PROPERTY command.\n"
  66         "Properties that affect the name of a target's output file are "
  67         "as follows.  "
  68         "The PREFIX and SUFFIX properties override the default target name "
  69         "prefix (such as \"lib\") and suffix (such as \".so\"). "
  70         "IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties for "
  71         "the import library corresponding to a DLL "
  72         "(for SHARED library targets).  "
  73         "OUTPUT_NAME sets the real name of a target when it is built and "
  74         "can be used to help create two targets of the same name even though "
  75         "CMake requires unique logical target names.  There is also a "
  76         "<CONFIG>_OUTPUT_NAME that can set the output name on a "
  77         "per-configuration basis.  "
  78         "<CONFIG>_POSTFIX sets a postfix for the real name of the target "
  79         "when it is built under the configuration named by <CONFIG> "
  80         "(in upper-case, such as \"DEBUG_POSTFIX\").  The value of "
  81         "this property is initialized when the target is created to the "
  82         "value of the variable CMAKE_<CONFIG>_POSTFIX (except for executable "
  83         "targets because earlier CMake versions which did not use this "
  84         "variable for executables)."
  85         "\n"
  86         "The LINK_FLAGS property can be used to add extra flags to the "
  87         "link step of a target. LINK_FLAGS_<CONFIG> will add to the "
  88         "configuration <CONFIG>, "
  89         "for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO. "
  90         "DEFINE_SYMBOL sets the name of the preprocessor symbol defined when "
  91         "compiling sources in a shared library. "
  92         "If not set here then it is set to target_EXPORTS by default "
  93         "(with some substitutions if the target is not a valid C "
  94         "identifier). This is useful for headers to know whether they are "
  95         "being included from inside their library or outside to properly "
  96         "setup dllexport/dllimport decorations. "
  97         "The COMPILE_FLAGS property sets additional compiler flags used "
  98         "to build sources within the target.  It may also be used to pass "
  99         "additional preprocessor definitions."
 100         "\n"
 101         "The LINKER_LANGUAGE property is used to change the tool "
 102         "used to link an executable or shared library. The default is "
 103         "set the language to match the files in the library. CXX and C "
 104         "are common values for this property."
 105         "\n"
 106         "For shared libraries VERSION and SOVERSION can be used to specify "
 107         "the build version and API version respectively. When building or "
 108         "installing appropriate symlinks are created if the platform "
 109         "supports symlinks and the linker supports so-names. "
 110         "If only one of both is specified the missing is assumed to have "
 111         "the same version number. "
 112         "For executables VERSION can be used to specify the build version. "
 113         "When building or installing appropriate symlinks are created if "
 114         "the platform supports symlinks. "
 115         "For shared libraries and executables on Windows the VERSION "
 116         "attribute is parsed to extract a \"major.minor\" version number. "
 117         "These numbers are used as the image version of the binary. "
 118         "\n"
 119         "There are a few properties used to specify RPATH rules. "
 120         "INSTALL_RPATH is a semicolon-separated list specifying the rpath "
 121         "to use in installed targets (for platforms that support it). "
 122         "INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true will "
 123         "append directories in the linker search path and outside the "
 124         "project to the INSTALL_RPATH. "
 125         "SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic "
 126         "generation of an rpath allowing the target to run from the "
 127         "build tree. "
 128         "BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link "
 129         "the target in the build tree with the INSTALL_RPATH.  This takes "
 130         "precedence over SKIP_BUILD_RPATH and avoids the need for relinking "
 131         "before installation.  INSTALL_NAME_DIR is a string specifying the "
 132         "directory portion of the \"install_name\" field of shared libraries "
 133         "on Mac OSX to use in the installed targets. "
 134         "When the target is created the values of "
 135         "the variables CMAKE_INSTALL_RPATH, "
 136         "CMAKE_INSTALL_RPATH_USE_LINK_PATH, CMAKE_SKIP_BUILD_RPATH, "
 137         "CMAKE_BUILD_WITH_INSTALL_RPATH, and CMAKE_INSTALL_NAME_DIR "
 138         "are used to initialize these properties.\n"
 139         "PROJECT_LABEL can be used to change the name of "
 140         "the target in an IDE like visual studio.  VS_KEYWORD can be set "
 141         "to change the visual studio keyword, for example Qt integration "
 142         "works better if this is set to Qt4VSv1.0.\n"
 143         "VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER and "
 144         "VS_SCC_AUXPATH can be set "
 145         "to add support for source control bindings in a  Visual Studio "
 146         "project file.\n"
 147         "VS_GLOBAL_<variable> can be set to add a Visual Studio "
 148         "project-specific global variable. "
 149         "Qt integration works better if VS_GLOBAL_QtVersion is set to "
 150         "the Qt version FindQt4.cmake found. For example, \"4.7.3\"\n"
 151         "The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the "
 152         "old way to specify CMake scripts to run before and after "
 153         "installing a target.  They are used only when the old "
 154         "INSTALL_TARGETS command is used to install the target.  Use the "
 155         "INSTALL command instead."
 156         "\n"
 157         "The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual "
 158         "studio generators.  If it is set to 1 the target will not be "
 159         "part of the default build when you select \"Build Solution\". "
 160         "This can also be set on a per-configuration basis using "
 161         "EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>."
 162         ;
 163     }
 164
 165   cmTypeMacro(cmSetTargetPropertiesCommand, cmCommand);
 166 };
 167
 168
 169
 170 #endif