cmTargetLinkLibrariesCommand.h 7.99 KB
Newer Older
1
2
3
/*============================================================================
  CMake - Cross Platform Makefile Generator
  Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
4

5
6
  Distributed under the OSI-approved BSD License (the "License");
  see accompanying file Copyright.txt for details.
7

8
9
10
11
  This software is distributed WITHOUT ANY WARRANTY; without even the
  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  See the License for more information.
============================================================================*/
12
13
14
15
#ifndef cmTargetLinkLibrariesCommand_h
#define cmTargetLinkLibrariesCommand_h

#include "cmCommand.h"
16
#include "cmDocumentGeneratorExpressions.h"
17
18
19
20
21
22

/** \class cmTargetLinkLibrariesCommand
 * \brief Specify a list of libraries to link into executables.
 *
 * cmTargetLinkLibrariesCommand is used to specify a list of libraries to link
 * into executable(s) or shared objects. The names of the libraries
23
 * should be those defined by the LIBRARY(library) command(s).
24
25
26
27
28
29
30
 */
class cmTargetLinkLibrariesCommand : public cmCommand
{
public:
  /**
   * This is a virtual constructor for the command.
   */
31
  virtual cmCommand* Clone()
32
33
34
35
36
37
38
39
    {
    return new cmTargetLinkLibrariesCommand;
    }

  /**
   * This is called when the command is first encountered in
   * the CMakeLists.txt file.
   */
40
41
  virtual bool InitialPass(std::vector<std::string> const& args,
                           cmExecutionStatus &status);
42
43
44
45

  /**
   * The name of the command as specified in CMakeList.txt.
   */
46
  virtual const char* GetName() const { return "target_link_libraries";}
47
48
49
50

  /**
   * Succinct documentation.
   */
51
  virtual const char* GetTerseDocumentation() const
52
    {
53
    return
54
      "Link a target to given libraries.";
55
    }
56

57
58
59
  /**
   * More documentation.
   */
60
  virtual const char* GetFullDocumentation() const
61
62
    {
    return
63
64
65
      "  target_link_libraries(<target> [item1 [item2 [...]]]\n"
      "                        [[debug|optimized|general] <item>] ...)\n"
      "Specify libraries or flags to use when linking a given target.  "
66
67
      "The named <target> must have been created in the current directory "
      "by a command such as add_executable or add_library.  "
68
69
      "The remaining arguments specify library names or flags.  "
      "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
74
75
      "sure the library being linked is up-to-date before the target links.  "
      "Item names starting with '-', but not '-l' or '-framework', are "
      "treated as linker flags."
76
77
78
79
      "\n"
      "A \"debug\", \"optimized\", or \"general\" keyword indicates that "
      "the library immediately following it is to be used only for the "
      "corresponding build configuration.  "
80
81
82
      "The \"debug\" keyword corresponds to the Debug configuration "
      "(or to configurations named in the DEBUG_CONFIGURATIONS global "
      "property if it is set).  "
83
84
85
86
87
88
89
90
91
92
93
94
95
      "The \"optimized\" keyword corresponds to all other configurations.  "
      "The \"general\" keyword corresponds to all configurations, and is "
      "purely optional (assumed if omitted).  "
      "Higher granularity may be achieved for per-configuration rules "
      "by creating and linking to IMPORTED library targets.  "
      "See the IMPORTED mode of the add_library command for more "
      "information.  "
      "\n"
      "Library dependencies are transitive by default.  "
      "When this target is linked into another target then the libraries "
      "linked to this target will appear on the link line for the other "
      "target too.  "
      "See the LINK_INTERFACE_LIBRARIES target property to override the "
96
97
98
      "set of transitive link dependencies for a target.  "
      "Calls to other signatures of this command may set the property "
      "making any libraries linked exclusively by this signature private."
99
      "\n"
100
101
102
103
104
105
106
107
108
109
110
      "CMake will also propagate \"usage requirements\" from linked library "
      "targets.  "
      "Usage requirements affect compilation of sources in the <target>.  "
      "They are specified by properties defined on linked targets.  "
      "During generation of the build system, CMake integrates "
      "usage requirement property values with the corresponding "
      "build properties for <target>:\n"
      " INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS\n"
      " INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES\n"
      " INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE\n"
      "   or checked for consistency with existing value\n"
111
      "\n"
112
113
114
      "  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES\n"
      "                        [[debug|optimized|general] <lib>] ...)\n"
      "The LINK_INTERFACE_LIBRARIES mode appends the libraries "
115
      "to the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent "
116
117
      "target properties instead of using them for linking.  "
      "Libraries specified as \"debug\" are appended to the "
118
      "LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties "
119
120
      "corresponding to configurations listed in the DEBUG_CONFIGURATIONS "
      "global property if it is set).  "
121
      "Libraries specified as \"optimized\" are appended to the "
122
      "LINK_INTERFACE_LIBRARIES property.  "
123
      "Libraries specified as \"general\" (or without any keyword) are "
124
      "treated as if specified for both \"debug\" and \"optimized\"."
125
      "\n"
126
127
128
129
130
      "  target_link_libraries(<target>\n"
      "                        <LINK_PRIVATE|LINK_PUBLIC>\n"
      "                          [[debug|optimized|general] <lib>] ...\n"
      "                        [<LINK_PRIVATE|LINK_PUBLIC>\n"
      "                          [[debug|optimized|general] <lib>] ...])\n"
131
132
      "The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both "
      "the link dependencies and the link interface in one command.  "
133
134
135
136
137
      "Libraries and targets following LINK_PUBLIC are linked to, and are "
      "made part of the LINK_INTERFACE_LIBRARIES. Libraries and targets "
      "following LINK_PRIVATE are linked to, but are not made part of the "
      "LINK_INTERFACE_LIBRARIES.  "
      "\n"
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
      "The library dependency graph is normally acyclic (a DAG), but in the "
      "case of mutually-dependent STATIC libraries CMake allows the graph "
      "to contain cycles (strongly connected components).  "
      "When another target links to one of the libraries CMake repeats "
      "the entire connected component.  "
      "For example, the code\n"
      "  add_library(A STATIC a.c)\n"
      "  add_library(B STATIC b.c)\n"
      "  target_link_libraries(A B)\n"
      "  target_link_libraries(B A)\n"
      "  add_executable(main main.c)\n"
      "  target_link_libraries(main A)\n"
      "links 'main' to 'A B A B'.  "
      "("
      "While one repetition is usually sufficient, pathological object "
      "file and symbol arrangements can require more.  "
      "One may handle such cases by manually repeating the component in "
      "the last target_link_libraries call.  "
      "However, if two archives are really so interdependent they should "
      "probably be combined into a single archive."
      ")"
159
160
161
162
163
164
      "\n"
      "Arguments to target_link_libraries may use \"generator expressions\" "
      "with the syntax \"$<...>\".  Note however, that generator expressions "
      "will not be used in OLD handling of CMP0003 or CMP0004."
      "\n"
      CM_DOCUMENT_COMMAND_GENERATOR_EXPRESSIONS
165
      ;
166
    }
167

168
  cmTypeMacro(cmTargetLinkLibrariesCommand, cmCommand);
169
private:
170
171
  void LinkLibraryTypeSpecifierWarning(int left, int right);
  static const char* LinkLibraryTypeNames[3];
172
173

  cmTarget* Target;
174
175
176
177
178
179
180
181
  enum ProcessingState {
    ProcessingLinkLibraries,
    ProcessingLinkInterface,
    ProcessingPublicInterface,
    ProcessingPrivateInterface
  };

  ProcessingState CurrentProcessingState;
182
183

  void HandleLibrary(const char* lib, cmTarget::LinkLibraryType llt);
184
185
186
187
188
};



#endif