Are CMAKE_SOURCE_DIR and PROJECT_SOURCE_DIR the same in CMake?

This page contains a good summary of variables CMake already defines for us. I feel that some variables are the same. Take the example of CMAKE_SOURCE_DIR and PROJECT_SOURCE_DIR for example. They are the same, referring to the folder where the top level CMakeLists.txt is defined. So my question is: are there subtle difference between them? Thanks.

There is a difference between these variables. [CMAKE_SOURCE_DIR][0] does indeed refer to the folder where the top-level CMakeLists.txt is defined. However, [PROJECT_SOURCE_DIR][1] refers to the folder of the CMakeLists.txt containing the most recent project() command.

For example, say you have a top-level project called Outer and this contains a subdirectory with its own project called Inner. Outer's CMakeLists.txt has:

project(Outer)
add_subdirectory(Inner)

and Inner's:

project(Inner)

Then in both of these CMakeLists files, CMAKE_SOURCE_DIR will refer to Outer's source dir. But while PROJECT_SOURCE_DIR for Outer is also this same dir, this is not the case for Inner. Inner's PROJECT_SOURCE_DIR is the subdirectory containing its CMakeLists.txt.

This difference applies to all PROJECT_<var> vs CMAKE_<var> variables.

[0]: http://www.cmake.org/cmake/help/v3.3/variable/CMAKE_SOURCE_DIR.html "CMake v3.3 documentation for "CMAKE_SOURCE_DIR" variable" [1]: http://www.cmake.org/cmake/help/v3.3/variable/PROJECT_SOURCE_DIR.html "CMake v3.3 documentation for "PROJECT_SOURCE_DIR" variable"

Following Fraser's excellent answer.

CMAKE_CURRENT_SOURCE_DIR is the build directory being processed.

Let's say you have a directory called Inner1 containing a CMakeLists.txt file without calling project inside of it. Then PROJECT_SOURCE_DIR is not set with Inner1's dir path, but the CMAKE_CURRENT_SOURCE_DIR is set when being processed.

You may also find CMAKE_CURRENT_LIST_DIR interesting and the definition of listfile useful.