Source/cmSetTargetPropertiesCommand.h

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