Clarification about modern CMake structure

Question

I am not an expert C or C++ programmer, but I have to write a C and a C++ application for two course projects. To start off on the right foot, I was reading a guide about how to structure the code of a CMake project.

I would like to clarify the meaning and usage of the include directory:

• If the project is a library, is the include directory meant to contain the API functions that the users of the library can include in their code and invoke? If so, what directory should be used for headers containing declarations of internal functions? Should such headers be put together with the source code (which is contained in the src directory)?
• If the project is an application, is the include directory meant to contain the header files of the source code? If so, what is the advantage of separating headers from sources? Is it just a matter of preference of organization?

Thank you for any insight.

Answer 1

If you are writing an application, you can put stuff wherever you want. The user mostly expects you to have a bin subdirectory with your binary executables. Oh, and please support the CMAKE_INSTALL_PREFIX: in-source builds are evil, as far as I'm concerned.

If you are writing a library, the user expects subdirectories include and lib in the install prefix location. For nice unix-y stuff you can include man if you know how to generate troff.

About the include directory. You can put your mylib.h file directly there, but if your library has at all a common name, say format, that may give name clashes, so these day many package organize it as /home/mylibinstallation/include/mylibrary/mylib.h. You would then export MYLIBINC=/home/mylibinstallation/include and the program would `#include "mylibrary/mylib.h". That extra level is also good if you have multiple includes.