Source/cmTargetLinkLibrariesCommand.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 cmTargetLinkLibrariesCommand_h
  13 #define cmTargetLinkLibrariesCommand_h
  14
  15 #include "cmCommand.h"
  16 #include "cmDocumentGeneratorExpressions.h"
  17
  18 /** \class cmTargetLinkLibrariesCommand
  19  * \brief Specify a list of libraries to link into executables.
  20  *
  21  * cmTargetLinkLibrariesCommand is used to specify a list of libraries to link
  22  * into executable(s) or shared objects. The names of the libraries
  23  * should be those defined by the LIBRARY(library) command(s).
  24  */
  25 class cmTargetLinkLibrariesCommand : public cmCommand
  26 {
  27 public:
  28   /**
  29    * This is a virtual constructor for the command.
  30    */
  31   virtual cmCommand* Clone()
  32     {
  33     return new cmTargetLinkLibrariesCommand;
  34     }
  35
  36   /**
  37    * This is called when the command is first encountered in
  38    * the CMakeLists.txt file.
  39    */
  40   virtual bool InitialPass(std::vector<std::string> const& args,
  41                            cmExecutionStatus &status);
  42
  43   /**
  44    * The name of the command as specified in CMakeList.txt.
  45    */
  46   virtual const char* GetName() const { return "target_link_libraries";}
  47
  48   /**
  49    * Succinct documentation.
  50    */
  51   virtual const char* GetTerseDocumentation() const
  52     {
  53     return
  54       "Link a target to given libraries.";
  55     }
  56
  57   /**
  58    * More documentation.
  59    */
  60   virtual const char* GetFullDocumentation() const
  61     {
  62     return
  63       "  target_link_libraries(<target> [item1 [item2 [...]]]\n"
  64       "                        [[debug|optimized|general] <item>] ...)\n"
  65       "Specify libraries or flags to use when linking a given target.  "
  66       "The named <target> must have been created in the current directory "
  67       "by a command such as add_executable or add_library.  "
  68       "The remaining arguments specify library names or flags.  "
  69       "Repeated calls for the same <target> append items in the order called."
  70       "\n"
  71       "If a library name matches that of another target in the project "
  72       "a dependency will automatically be added in the build system to make "
  73       "sure the library being linked is up-to-date before the target links.  "
  74       "Item names starting with '-', but not '-l' or '-framework', are "
  75       "treated as linker flags."
  76       "\n"
  77       "A \"debug\", \"optimized\", or \"general\" keyword indicates that "
  78       "the library immediately following it is to be used only for the "
  79       "corresponding build configuration.  "
  80       "The \"debug\" keyword corresponds to the Debug configuration "
  81       "(or to configurations named in the DEBUG_CONFIGURATIONS global "
  82       "property if it is set).  "
  83       "The \"optimized\" keyword corresponds to all other configurations.  "
  84       "The \"general\" keyword corresponds to all configurations, and is "
  85       "purely optional (assumed if omitted).  "
  86       "Higher granularity may be achieved for per-configuration rules "
  87       "by creating and linking to IMPORTED library targets.  "
  88       "See the IMPORTED mode of the add_library command for more "
  89       "information.  "
  90       "\n"
  91       "Library dependencies are transitive by default with this signature.  "
  92       "When this target is linked into another target then the libraries "
  93       "linked to this target will appear on the link line for the other "
  94       "target too.  "
  95       "This transitive \"link interface\" is stored in the "
  96       "INTERFACE_LINK_LIBRARIES target property when policy CMP0022 is set "
  97       "to NEW and may be overridden by setting the property directly. "
  98       "("
  99       "When CMP0022 is not set to NEW, transitive linking is builtin "
 100       "but may be overridden by the LINK_INTERFACE_LIBRARIES property.  "
 101       "Calls to other signatures of this command may set the property "
 102       "making any libraries linked exclusively by this signature private."
 103       ")"
 104       "\n"
 105       "CMake will also propagate \"usage requirements\" from linked library "
 106       "targets.  "
 107       "Usage requirements affect compilation of sources in the <target>.  "
 108       "They are specified by properties defined on linked targets.  "
 109       "During generation of the build system, CMake integrates "
 110       "usage requirement property values with the corresponding "
 111       "build properties for <target>:\n"
 112       " INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS\n"
 113       " INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES\n"
 114       " INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE\n"
 115       "   or checked for consistency with existing value\n"
 116       "\n"
 117       "If an <item> is a library in a Mac OX framework, the Headers "
 118       "directory of the framework will also be processed as a \"usage "
 119       "requirement\".  This has the same effect as passing the framework "
 120       "directory as an include directory."
 121       "  target_link_libraries(<target>\n"
 122       "                      <PRIVATE|PUBLIC|INTERFACE> <lib> ...\n"
 123       "                      [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])\n"
 124       "The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify "
 125       "both the link dependencies and the link interface in one command.  "
 126       "Libraries and targets following PUBLIC are linked to, and are "
 127       "made part of the link interface.  Libraries and targets "
 128       "following PRIVATE are linked to, but are not made part of the "
 129       "link interface.  Libraries following INTERFACE are appended "
 130       "to the link interface and are not used for linking <target>."
 131       "\n"
 132       "  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES\n"
 133       "                        [[debug|optimized|general] <lib>] ...)\n"
 134       "The LINK_INTERFACE_LIBRARIES mode appends the libraries "
 135       "to the INTERFACE_LINK_LIBRARIES target property instead of using them "
 136       "for linking.  If policy CMP0022 is not NEW, then this mode also "
 137       "appends libraries to the LINK_INTERFACE_LIBRARIES and its "
 138       "per-configuration equivalent.  This signature "
 139       "is for compatibility only. Prefer the INTERFACE mode instead.  "
 140       "Libraries specified as \"debug\" are wrapped in a generator "
 141       "expression to correspond to debug builds.  If policy CMP0022 is not "
 142       "NEW, the libraries are also appended to the "
 143       "LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties "
 144       "corresponding to configurations listed in the DEBUG_CONFIGURATIONS "
 145       "global property if it is set).  "
 146       "Libraries specified as \"optimized\" are appended to the "
 147       "INTERFACE_LINK_LIBRARIES property.  If policy CMP0022 is not NEW, "
 148       "they are also appended to the LINK_INTERFACE_LIBRARIES property.  "
 149       "Libraries specified as \"general\" (or without any keyword) are "
 150       "treated as if specified for both \"debug\" and \"optimized\"."
 151       "\n"
 152       "  target_link_libraries(<target>\n"
 153       "                        <LINK_PRIVATE|LINK_PUBLIC>\n"
 154       "                          [[debug|optimized|general] <lib>] ...\n"
 155       "                        [<LINK_PRIVATE|LINK_PUBLIC>\n"
 156       "                          [[debug|optimized|general] <lib>] ...])\n"
 157       "The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both "
 158       "the link dependencies and the link interface in one command.  This "
 159       "signature is for compatibility only. Prefer the PUBLIC or PRIVATE "
 160       "keywords instead.  "
 161       "Libraries and targets following LINK_PUBLIC are linked to, and are "
 162       "made part of the INTERFACE_LINK_LIBRARIES.  If policy CMP0022 is not "
 163       "NEW, they are also made part of the LINK_INTERFACE_LIBRARIES.  "
 164       "Libraries and targets following LINK_PRIVATE are linked to, but are "
 165       "not made part of the INTERFACE_LINK_LIBRARIES (or "
 166       "LINK_INTERFACE_LIBRARIES)."
 167       "\n"
 168       "The library dependency graph is normally acyclic (a DAG), but in the "
 169       "case of mutually-dependent STATIC libraries CMake allows the graph "
 170       "to contain cycles (strongly connected components).  "
 171       "When another target links to one of the libraries CMake repeats "
 172       "the entire connected component.  "
 173       "For example, the code\n"
 174       "  add_library(A STATIC a.c)\n"
 175       "  add_library(B STATIC b.c)\n"
 176       "  target_link_libraries(A B)\n"
 177       "  target_link_libraries(B A)\n"
 178       "  add_executable(main main.c)\n"
 179       "  target_link_libraries(main A)\n"
 180       "links 'main' to 'A B A B'.  "
 181       "("
 182       "While one repetition is usually sufficient, pathological object "
 183       "file and symbol arrangements can require more.  "
 184       "One may handle such cases by manually repeating the component in "
 185       "the last target_link_libraries call.  "
 186       "However, if two archives are really so interdependent they should "
 187       "probably be combined into a single archive."
 188       ")"
 189       "\n"
 190       "Arguments to target_link_libraries may use \"generator expressions\" "
 191       "with the syntax \"$<...>\".  Note however, that generator expressions "
 192       "will not be used in OLD handling of CMP0003 or CMP0004."
 193       "\n"
 194       CM_DOCUMENT_COMMAND_GENERATOR_EXPRESSIONS
 195       ;
 196     }
 197
 198   cmTypeMacro(cmTargetLinkLibrariesCommand, cmCommand);
 199 private:
 200   void LinkLibraryTypeSpecifierWarning(int left, int right);
 201   static const char* LinkLibraryTypeNames[3];
 202
 203   cmTarget* Target;
 204   enum ProcessingState {
 205     ProcessingLinkLibraries,
 206     ProcessingPlainLinkInterface,
 207     ProcessingKeywordLinkInterface,
 208     ProcessingPlainPublicInterface,
 209     ProcessingKeywordPublicInterface,
 210     ProcessingPlainPrivateInterface,
 211     ProcessingKeywordPrivateInterface
 212   };
 213
 214   ProcessingState CurrentProcessingState;
 215
 216   bool HandleLibrary(const char* lib, cmTarget::LinkLibraryType llt);
 217 };
 218
 219
 220
 221 #endif