c++compilationcmakeshared-libraries

How to create a shared library with cmake?


I have written a library that I used to compile using a self-written Makefile, but now I want to switch to cmake. The tree looks like this (I removed all the irrelevant files):

.
├── include
│   ├── animation.h
│   ├── buffers.h
│   ├── ...
│   ├── vertex.h
│   └── world.h
└── src
    ├── animation.cpp
    ├── buffers.cpp
    ├── ...
    ├── vertex.cpp
    └── world.cpp

So what I am trying to do is just to compile the source into a shared library and then install it with the header files.

Most examples that I have found compile executables with some shared libraries but never just a plain shared library. It would also be helpful if someone could just tell me a very simple library that uses cmake, so I can use this as an example.


Solution

  • Always specify the minimum required version of cmake

    cmake_minimum_required(VERSION 3.9)
    

    You should declare a project. cmake says it is mandatory and it will define convenient variables PROJECT_NAME, PROJECT_VERSION and PROJECT_DESCRIPTION (this latter variable necessitate cmake 3.9):

    project(mylib VERSION 1.0.1 DESCRIPTION "mylib description")
    

    Declare a new library target. Please avoid the use of file(GLOB ...). This feature does not provide attended mastery of the compilation process. If you are lazy, copy-paste output of ls -1 sources/*.cpp :

    add_library(mylib SHARED
        sources/animation.cpp
        sources/buffers.cpp
        [...]
    )
    

    Set VERSION property (optional but it is a good practice):

    set_target_properties(mylib PROPERTIES VERSION ${PROJECT_VERSION})
    

    You can also set SOVERSION to the major number of VERSION. So libmylib.so.1 will be a symlink to libmylib.so.1.0.0.

    set_target_properties(mylib PROPERTIES SOVERSION ${PROJECT_VERSION_MAJOR})
    

    Declare public API of your library. This API will be installed for the third-party application. It is a good practice to isolate it in your project tree (like placing it include/ directory). Notice that, private headers should not be installed and I strongly suggest to place them with the source files.

    set_target_properties(mylib PROPERTIES PUBLIC_HEADER include/mylib.h)
    

    If you work with subdirectories, it is not very convenient to include relative paths like "../include/mylib.h". So, pass a top directory in included directories:

    target_include_directories(mylib PRIVATE .)
    

    or

    target_include_directories(mylib PRIVATE include)
    target_include_directories(mylib PRIVATE src)
    

    Create an install rule for your library. I suggest to use variables CMAKE_INSTALL_*DIR defined in GNUInstallDirs:

    include(GNUInstallDirs)
    

    And declare files to install:

    install(TARGETS mylib
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
    

    You may also export a pkg-config file. This file allows a third-party application to easily import your library:

    Create a template file named mylib.pc.in (see pc(5) manpage for more information):

    prefix=@CMAKE_INSTALL_PREFIX@
    exec_prefix=@CMAKE_INSTALL_PREFIX@
    libdir=${exec_prefix}/@CMAKE_INSTALL_LIBDIR@
    includedir=${prefix}/@CMAKE_INSTALL_INCLUDEDIR@
    
    Name: @PROJECT_NAME@
    Description: @PROJECT_DESCRIPTION@
    Version: @PROJECT_VERSION@
    
    Requires:
    Libs: -L${libdir} -lmylib
    Cflags: -I${includedir}
    

    In your CMakeLists.txt, add a rule to expand @ macros (@ONLY ask to cmake to not expand variables of the form ${VAR}):

    configure_file(mylib.pc.in mylib.pc @ONLY)
    

    And finally, install generated file:

    install(FILES ${CMAKE_BINARY_DIR}/mylib.pc DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/pkgconfig)
    

    You may also use cmake EXPORT feature. However, this feature is only compatible with cmake and I find it difficult to use.

    Finally the entire CMakeLists.txt should looks like:

    cmake_minimum_required(VERSION 3.9)
    project(mylib VERSION 1.0.1 DESCRIPTION "mylib description")
    include(GNUInstallDirs)
    add_library(mylib SHARED src/mylib.c)
    set_target_properties(mylib PROPERTIES
        VERSION ${PROJECT_VERSION}
        SOVERSION ${PROJECT_VERSION_MAJOR}
        PUBLIC_HEADER api/mylib.h)
    configure_file(mylib.pc.in mylib.pc @ONLY)
    target_include_directories(mylib PRIVATE .)
    install(TARGETS mylib
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
    install(FILES ${CMAKE_BINARY_DIR}/mylib.pc
        DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/pkgconfig)
    

    EDIT

    As mentioned in comments, to comply with standards you should be able to generate a static library as well as a shared library. The process is bit more complex and does not match with the initial question. But it worths to mention that it is greatly explained here.