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 muc

Answer 1

I found a good usage example of exactly this today: adding Doxygen documentation.

I use CMake (and Ninja) to build my personal C++ projects. I decided on a whim to add some Doxygen documentation to one of my pretty much complete but undocumented efforts. I also thought it would be neat to add it to the other projects as well just as soon as I work out how to make it as generic as possible.

To begin with, I generated a standard Doxygen template and renamed it.

cd my_projects/projectx
doxygen -g Doxyfile
mv Doxyfile Doxyfile.in

Note the .in extension. Probably not necessary but conventional, if I understand correctly.

Next, I added the following code block in my CMakeLists.txt file, just before defining my targets (not sure if that's important but CMake is sometimes fussy about the sequence of certain commands).

FIND_PACKAGE(Doxygen)
IF("${DOXYGEN_FOUND}" MATCHES "^YES$")
    CONFIGURE_FILE( ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
                    ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
                    @ONLY)
    ADD_CUSTOM_TARGET(  doc ALL
                        COMMAND ${DOXYGEN_EXECUTABLE}
                        ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
                        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                        COMMENT "Doxygenating..."
                        VERBATIM)
ENDIF()

This creates a new target called doc. Specifying ALL adds it to the default "all" target, but that's optional. Specifying @ONLY ensures that any "${variable}" type variables will not be expanded by CONFIGURE_FILE, only "@variable@" types. Somewhat confusingly (to me at least), CMAKE_CURRENT_SOURCE_DIR appears to refer to the project directory and CMAKE_CURRENT_BINARY_DIR to the build directory.

Finally, and this is where PROJECT_NAME et al come in, I edited Doxyfile.in.

This is the beginning of my new Doxyfile.in:

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "@PROJECT_NAME@"
PROJECT_NUMBER         = @PROJECT_VERSION_TWEAK@
PROJECT_BRIEF          =
PROJECT_LOGO           = @CMAKE_CURRENT_SOURCE_DIR@/res/doc_logo-200x55.png
OUTPUT_DIRECTORY       = @CMAKE_CURRENT_SOURCE_DIR@/doc

You get the idea, I think. Once this is fully genericised (is that a word?) I can copy it to my other projects and as long as I tag up my code, I will have nice documentation everywhere.

Notice PROJECT_BRIEF isn't specified. I haven't finished with this and there still a few blanks for me to think about. For instance PROJECT_VERSION_TWEAK doesn't actually contain anything yet. I will have to find a way to get my build number in there.