Learning CMake 4: finding things

Usually, you will not work just with the things you are creating: your libraries, your executables, your include files. Sometimes, you will need to look for third-party libraries, programs you need to execute during your build or configuration files. During this post, we will learn how this can be solved.

Finding executables

Imagine you need to run a Python script to generate some files that will be needed during your build. You can do it using a custom command. But the first thing you need is to know where the Python executable is located. How? All you have to do is run the find_program CMake macro:

find_program(
    PYTHON_EXECUTABLE
    NAMES
        python python3 python36
    DOC "Python executable location"
)

The previous code will look for the Python executable and will store the result in the PYTHON_EXECUTABLE CMake variable. Using NAMES, we can specify different possible names for the executable we are looking for. DOC will add documentation to the CMake cache about the PYTHON_EXECUTABLE CMake variable. Then, you will be able to use this path for multiple purposes (like execute_process, for instance).

Whay will happen if find_program was not able to find the executable? The PYTHON_EXECUTABLE variable will be set to PYTHON_EXECUTABLE-NOTFOUND: this will help you to decide if you prefer to run an error or continue the execution of CMake. For instance:

find_program(
    PYTHON_EXECUTABLE
    NAMES
        python python3 python36
    DOC "Python executable location"
)

if(PYTHON_EXECUTABLE)
    message(FATAL_ERROR "It was not possible to find the Python executable")
endif()

Where will CMake search the desired executable?

Depending on the system, it will try to get the path to the executable in some predefined paths. You can also specify some extra paths using the HINTS and PATHS parameters. The official documentation can help you to clarify the extra paths where the executable will be searched and the order.

Ok, now we know how to look for executables, now,

How to look for libraries?

It is pretty similar: you will use the find_library macro. The mosf of the parameters are the same: NAMES, PATHS, HINTS, DOC...

Let's imagine we are looking for a library called "awesome".

find_library(
    AWESOME_LIBRARY
    NAMES
        awesome
    DOC "My awesome third party library"
)

Depending on the operating system, the extension or the prefix will be different. If your system is supported by CMake, all this information will be set automatically but you can specify the path suffix (or paths) for your library using PATH_SUFFIXES.

When you are searching a library, you can specify the full name (using the extension). Doing this, you will be always looking for a static or shared library (depending on the extension).

It is important to say that CMake will get the first library found whose name matches the desired name: it will not check if the library is static or dynamic. Why is this important? If the value of BUILD_SHARED_LIBS is TRUE, CMake could find a static library instead of a dynamic one.

There are some special cases that can make your libraries difficult to find, but we will try to cover them in the future.

Finding files

Nothing special. Finding files is the easiest case:

find_file(
    MY_FILE
    NAMES
        file.xml
)

The parameters are the same than the ones explaines for find_executable and find_library.

Recap

During this post, we learnt how to find files, libraries and executables. This will help you to integrate third-party elements in your build.

Using this tools, CMake provides an easier way to do third-party integrations. This will be coverede in future posts.