what is the proper use of the CMake "project" directive

Question

I have a large-ish codebase which builds several dozen libaries and several executables.

The codebase is broken down hierarchically and libraries are build at pretty much every level.

I've gone through and placed a CMakeLists.txt file at each directory to build each library.

In each CMakeLists.txt I have used the "project( xxx )" directive. This has defined for me PROJECT_NAME, PROJECT_SOURCE_DIR and PROJECT_BINARY_DIR variables which I make judicious use of.

However, one of the team is unhappy with this approach as he can't find any real world examples of anyone else having done this. He often cites the KitWare examples as not using this approach and therefore neither should we.

The alternative approach he is advocating is to set these variables up in each makefile which seems much like what "project" gives you.

I really can't see his point and am making little headway in convincing him otherwise. Can anyone shed any light on the downsides of using the project directive in this way.

I throw myself on your collective wisdom?

Answer 1

Firstly, it enables you to use <projectName>_BINARY_DIR and <projectName>_SOURCE_DIR, but that's not the main advantage. If you give CMake a project name then it will generate build targets for each of the sub-projects in their own directories. This means that whether you're using GNU Make, Eclipse CDT, XCode, or any of the other supported generators you can build sub-projects individually. For instance with GNU Make each sub-project has its own full build system from it's own directory.

You can access the current project name through PROJECT_NAME, and the root project name by CMAKE_PROJECT_NAME.

Edit: I've just realised the below will be standard CMake behaviour for any of its build targets whether they're projects or not. I'll keep it here for general information but it is not pertinent to the answer:

Assume I have a C++ library, and I can generate three binary executables; Main and tests/test1, and examples/ex1. I can either run make in the directory I called CMake from with the ALL target, run make ex1, or I can change directory to examples/ and build the examples with make from that directory. This will build all of the dependent projects and libraries even if they're somewhere else in the directory structure but won't build Main or tests/test1 or any libraries that they depend on that examples/ex1 doesn't. If I then run make from the main directory, it won't rebuild any of the libraries that examples/ex1 depends on unless their source has changed.