CMake 2.6 introduced support for exporting targets from one project and
importing them into another. The main feature allowing this
functionality is the notion of an IMPORTED target. Here we present
imported targets and then show how CMake files may be generated by a
project to export its targets for use by other projects.
Imported targets are used to convert files outside the project on disk
into logical targets inside a CMake project. They are created using the
IMPORTED option to add_executable and add_library commands. No
build files are generated for imported targets. They are useful simply
for convenient, flexible reference to outside executables and libraries.
Consider the following example which creates and uses an IMPORTED
Line #1 creates a new CMake target called "generator". Line #2 tells
CMake the location of the file on disk to import. Line #3 references
the target in a custom command. The generated build system will contain
a command line such as
The generated build system will link myexe to foo.lib when it is
built in the release configuration and foo_d.lib when built in the
In some cases, such as when using the result of a find_library command
to create an imported target, the type of the library (static or shared)
is not known. As of CMake 2.6.2 one may specify this explicitly:
In this case CMake does not know the library type, so it just puts the
library on the link line as-is. Therefore on Windows there is no special
treatment for a shared library. The runtime library (foo.dll) need not
be found. The import library (foo.lib) is specified by the
IMPORTED_LOCATION property, not the IMPORTED_IMPLIB property.
Imported targets on their own are useful, but they still require the
project that imports targets to know the locations of the target files
on disk. The real power of this feature is when the project providing
the target files also provides a file to help import them.
Exporting from an Installation Tree
The install(TARGETS) and install(EXPORT) commands work together to
install a target and a file to help import it. For example, the code
Line #1 loads the target import script. The script may import any
number of targets. Their locations are computed relative to the script
location so the install tree may be moved around. The importing project
need only find the import script (see the packaging section of this
document for how this might be done). Line #2 references the generator
executable in a custom command. The resulting build system will run the
executable from its installed location.
and the executable will be linked to the library foo exported and
installed by the original project.
Any number of target installations may be associated with the same
export name. The export names are considered global so any directory may
contribute a target installation. Only one call to the install(EXPORT)
command is needed to install an import file that references all targets.
Both of the examples above may be combined into a single export, even if
they are in different subdirectories of the project:
Typically projects are built and installed before being used by an
outside project. However in some cases it is desirable to export targets
directly from a build tree. The targets may then be used by an outside
project that references the build tree with no installation involved.
The export command is used to generate a file exporting targets from a
project build tree. For example, the code
This file may be loaded by an outside project that is aware of the
project build tree in order to use the executable to generate a source
An example application of this feature is for building a generator
executable on a host platform when cross compiling. The project
containing the generator executable may be built on the host platform
and then the project that is being cross-compiled for another platform
may load it.
This page was initially populated by conversion from its original location in another wiki.