1 /*============================================================================
2 CMake - Cross Platform Makefile Generator
3 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
5 Distributed under the OSI-approved BSD License (the "License");
6 see accompanying file Copyright.txt for details.
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
15 #include "cmCommand.h"
17 /** \class cmTargetLinkLibrariesCommand
18 * \brief Specify a list of libraries to link into executables.
20 * cmTargetLinkLibrariesCommand is used to specify a list of libraries to link
21 * into executable(s) or shared objects. The names of the libraries
22 * should be those defined by the LIBRARY(library) command(s).
24 class cmTargetLinkLibrariesCommand : public cmCommand
28 * This is a virtual constructor for the command.
30 virtual cmCommand* Clone()
32 return new cmTargetLinkLibrariesCommand;
36 * This is called when the command is first encountered in
37 * the CMakeLists.txt file.
39 virtual bool InitialPass(std::vector<std::string> const& args,
40 cmExecutionStatus &status);
43 * The name of the command as specified in CMakeList.txt.
45 virtual const char* GetName() const { return "target_link_libraries";}
48 * Succinct documentation.
50 virtual const char* GetTerseDocumentation() const
53 "Link a target to given libraries.";
59 virtual const char* GetFullDocumentation() const
62 " target_link_libraries(<target> [item1 [item2 [...]]]\n"
63 " [[debug|optimized|general] <item>] ...)\n"
64 "Specify libraries or flags to use when linking a given target. "
65 "The named <target> must have been created in the current directory "
66 "by a command such as add_executable or add_library. "
67 "The remaining arguments specify library names or flags. "
68 "Repeated calls for the same <target> append items in the order called."
70 "If a library name matches that of another target in the project "
71 "a dependency will automatically be added in the build system to make "
72 "sure the library being linked is up-to-date before the target links. "
73 "Item names starting with '-', but not '-l' or '-framework', are "
74 "treated as linker flags."
76 "A \"debug\", \"optimized\", or \"general\" keyword indicates that "
77 "the library immediately following it is to be used only for the "
78 "corresponding build configuration. "
79 "The \"debug\" keyword corresponds to the Debug configuration "
80 "(or to configurations named in the DEBUG_CONFIGURATIONS global "
81 "property if it is set). "
82 "The \"optimized\" keyword corresponds to all other configurations. "
83 "The \"general\" keyword corresponds to all configurations, and is "
84 "purely optional (assumed if omitted). "
85 "Higher granularity may be achieved for per-configuration rules "
86 "by creating and linking to IMPORTED library targets. "
87 "See the IMPORTED mode of the add_library command for more "
90 "Library dependencies are transitive by default. "
91 "When this target is linked into another target then the libraries "
92 "linked to this target will appear on the link line for the other "
94 "See the LINK_INTERFACE_LIBRARIES target property to override the "
95 "set of transitive link dependencies for a target."
97 " target_link_libraries(<target> LINK_INTERFACE_LIBRARIES\n"
98 " [[debug|optimized|general] <lib>] ...)\n"
99 "The LINK_INTERFACE_LIBRARIES mode appends the libraries "
100 "to the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent "
101 "target properties instead of using them for linking. "
102 "Libraries specified as \"debug\" are appended to the "
103 "the LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties "
104 "corresponding to configurations listed in the DEBUG_CONFIGURATIONS "
105 "global property if it is set). "
106 "Libraries specified as \"optimized\" are appended to the "
107 "the LINK_INTERFACE_LIBRARIES property. "
108 "Libraries specified as \"general\" (or without any keyword) are "
109 "treated as if specified for both \"debug\" and \"optimized\"."
111 " target_link_libraries(<target>\n"
112 " <LINK_PRIVATE|LINK_PUBLIC>\n"
113 " [[debug|optimized|general] <lib>] ...\n"
114 " [<LINK_PRIVATE|LINK_PUBLIC>\n"
115 " [[debug|optimized|general] <lib>] ...])\n"
116 "The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both "
117 "the link dependencies and the link interface in one command. "
118 "Libraries and targets following LINK_PUBLIC are linked to, and are "
119 "made part of the LINK_INTERFACE_LIBRARIES. Libraries and targets "
120 "following LINK_PRIVATE are linked to, but are not made part of the "
121 "LINK_INTERFACE_LIBRARIES. "
123 "The library dependency graph is normally acyclic (a DAG), but in the "
124 "case of mutually-dependent STATIC libraries CMake allows the graph "
125 "to contain cycles (strongly connected components). "
126 "When another target links to one of the libraries CMake repeats "
127 "the entire connected component. "
128 "For example, the code\n"
129 " add_library(A STATIC a.c)\n"
130 " add_library(B STATIC b.c)\n"
131 " target_link_libraries(A B)\n"
132 " target_link_libraries(B A)\n"
133 " add_executable(main main.c)\n"
134 " target_link_libraries(main A)\n"
135 "links 'main' to 'A B A B'. "
137 "While one repetition is usually sufficient, pathological object "
138 "file and symbol arrangements can require more. "
139 "One may handle such cases by manually repeating the component in "
140 "the last target_link_libraries call. "
141 "However, if two archives are really so interdependent they should "
142 "probably be combined into a single archive."
147 cmTypeMacro(cmTargetLinkLibrariesCommand, cmCommand);
149 void LinkLibraryTypeSpecifierWarning(int left, int right);
150 static const char* LinkLibraryTypeNames[3];
153 enum ProcessingState {
154 ProcessingLinkLibraries,
155 ProcessingLinkInterface,
156 ProcessingPublicInterface,
157 ProcessingPrivateInterface
160 ProcessingState CurrentProcessingState;
162 void HandleLibrary(const char* lib, cmTarget::LinkLibraryType llt);