CMake 2.6 Notes: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
(Replace content with link to new CMake community wiki)
 
(48 intermediate revisions by 4 users not shown)
Line 1: Line 1:
__TOC__
{{CMake/Template/Moved}}


This page documents some of the changes and new features available in CMake 2.6.
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/notes/2.6 here].
 
=Exporting and Importing Targets=
 
=Preprocessor Definitions=
 
Preprocessor definitions may now be added to builds with much finer granularity than in previous versions of CMake.  There is a new property called <code>COMPILE_DEFINITIONS</code> that is defined directories, targets, and source files.  For example, the code
 
  add_library(mylib src1.c src2.c)
  add_executable(myexe main1.c)
 
  set_property(
    DIRECTORY
    PROPERTY COMPILE_DEFINITIONS A AV=1
    )
  set_property(
    TARGET mylib
    PROPERTY COMPILE_DEFINITIONS B BV=2
    )
  set_property(
    SOURCE src1.c
    PROPERTY COMPILE_DEFINITIONS C CV=3
    )
 
will build the source files with these definitions:
 
  src1.c:  -DA -DAV=1 -DB -DBV=2 -DC -DCV=3
  src2.c:  -DA -DAV=1 -DB -DBV=2
  main2.c: -DA -DAV=1
 
When the <code>add_definitions</code> command is called with flags like "<code>-DX</code>" the definitions are extracted and added to the current directory's <code>COMPILE_DEFINITIONS</code> property. When a new subdirectory is created with <code>add_subdirectory</code> the current state of the directory-level property is used to initialize the same property in the subdirectory.
 
Note in the above example that the <code>set_property</code> command will actually '''set''' the property and replace any existing value.  The command provides the <code>APPEND</code> option to help add more definitions without removing existing ones.  For example, the code
 
  set_property(
    SOURCE src1.c
    APPEND PROPERTY COMPILE_DEFINITIONS D DV=4
    )
 
will add the definitions "<code>-DD -DDV=4</code>" when building <code>src1.c</code>.
 
Definitions may also be added on a per-configuration basis using the <code>COMPILE_DEFINITIONS_<CONFIG></code> property.  For example, the code
 
  set_property(
    TARGET mylib
    PROPERTY COMPILE_DEFINITIONS_DEBUG MYLIB_DEBUG_MODE
    )
 
will build sources in mylib with <code>-DMYLIB_DEBUG_MODE</code> only when compiling in a <code>Debug</code> configuration.
 
=Linking=
 
CMake 2.6 implements a new approach to generating link lines for targets.
 
Consider these libraries:
 
  /path/to/libfoo.a
  /path/to/libfoo.so
 
Previously if someone wrote
 
  target_link_libraries(myexe /path/to/libfoo.a)
 
CMake would generate this code to link it:
 
  ... -L/path/to -Wl,-Bstatic -lfoo -Wl,-Bdynamic ...
 
This worked most of the time, but some platforms (such as OS X) do not
support the <code>-Bstatic</code> or equivalent flag.  This made it impossible to
link to the static version of a library without creating a symlink in
another directory and using that one instead.
 
Now CMake will generate this code:
 
  ... /path/to/libfoo.a ...
 
This guarantees that the correct library is chosen.  However there are some side-effects.
 
==Missing Linker Search Directories==
 
Projects used to be able to write this (wrong) code and it would work by accident:
 
  add_executable(myexe myexe.c)
  target_link_libraries(myexe /path/to/libA.so B)
 
where "<code>B</code>" is meant to link "<code>/path/to/libB.so</code>".  This code is incorrect
because it asks CMake to link to <code>B</code> but does not provide the proper
linker search path for it.  It used to work by accident because the
<code>-L/path/to</code> would get added as part of the implementation of linking to
A.  The correct code would be
 
  link_directories(/path/to)
  add_executable(myexe myexe.c)
  target_link_libraries(myexe /path/to/libA.so B)
 
or even better
 
  add_executable(myexe myexe.c)
  target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
 
In order to support projects that have this bug, we've added a
compatibility feature that adds the "<code>-L/path/to</code>" paths for all libraries
linked with full paths even though the linker will not need those paths
to find the main libraries.  The compatibility mode is enabled when a
link line contains a non-full-path library (like <code>B</code>) and either
<code>CMAKE_BACKWARDS_COMPATIBILITY</code> is set to 2.4 or lower or
<code>CMAKE_LINK_OLD_PATHS</code> is set to true.
 
If you are trying to build a project and run into this problem, a quick-fix is to run
 
  cmake -DCMAKE_LINK_OLD_PATHS:BOOL=ON .
 
in the top of the build tree.
 
==Linking to System Libraries==
 
System libraries on UNIX-like systems are typically provided in <code>/usr/lib</code> or <code>/lib</code>.  These directories are considered implicit linker search paths because linkers automatically search these locations even without a flag like <code>-L/usr/lib</code>.  Consider the code
 
  find_library(M_LIB m)
  target_link_libraries(myexe ${M_LIB})
 
Typically the <code>find_library</code> command would find the math library
 
  /usr/lib/libm.so
 
In CMake 2.4 and lower this value would be assigned directly to <code>M_LIB</code>.  Then the link line generation would split off the link directory <code>/usr/lib</code> and the library <code>libm.so</code> and produce the
 
  ... -lm ...
 
Note that the <code>-L/usr/lib</code> option is left out because it is an implicit linker search path.  The linker would see <code>-lm</code> and search for the math library.  Typically the linker would find /usr/lib/libm.so too.  However some platforms provide multiple versions of libraries correesponding to different architectures.  For example, on an IRIX machine one might find the libraries
 
  /usr/lib/libm.so        (ELF o32)
  /usr/lib32/libm.so      (ELF n32)
  /usr/lib64/libm.so      (ELF 64)
 
On a Solaris machine one might find
 
  /usr/lib/libm.so          (sparcv8 architecture)
  /usr/lib/sparcv9/libm.so  (sparcv9 architecture)
 
When the linker sees <code>-lm</code> it in fact searches the system path corresponding to the current architecture.  Internally it might use <code>-L/usr/lib/sparcv9</code> instead of <code>-L/usr/lib</code>.
 
In CMake 2.6 the code
 
  target_link_libraries(myexe /usr/lib/libm.so)
 
would generate the link line
 
  ... /usr/lib/libm.so ...
 
no matter what architecture is getting linked.  This might cause the linker to complain if <code>/usr/lib/libm.so</code> does not match the architecture it wants.  This is not a problem with the link line computation.  CMake is linking <code>myexe</code> to the library to which it was told to link.
 
The problem is created because <code>find_library</code> may not know about all the architecture-specific system search paths used by the linker.  In fact when it finds <code>/usr/lib/libm.so</code> it may be finding a library of incorrect architecture.  The solution is for the command to recognize that when it finds a library in a system search path that it should ask the linker to find the correct version of the library at link time.  Consider the original example:
 
  find_library(M_LIB m)
  target_link_libraries(myexe ${M_LIB})
 
In CMake 2.6 the <code>find_library</code> command will set <code>M_LIB</code> to contain just "<code>libm.so</code>" when it finds <code>/usr/lib/libm.so</code>.  The link command will then be
 
  target_link_libraries(myexe libm.so)
 
which will be converted to the link command line
 
  ... -lm ...
 
and the linker will locate the correct version of the library.  If <code>find_library</code> does not find the library in an implicit link directory it will report the full path as usual.  The user might also edit the cache to set <code>M_LIB</code> to a full path.  In both cases the full path given to target_link_libraries will be preserved on the final link line.

Latest revision as of 15:41, 30 April 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.