cmake -H to generate build files for CMake project?

user_12591388 0
Viewed 136

I recently observed that the CMake Tools Extension in VS Code runs this command to generate the build file for a project I'm working on:

/usr/bin/cmake --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug -H/home/tirthankar/projects/physicc/Light/Editor -B/home/tirthankar/projects/physicc/Light/build -G Ninja

The part I am confused about is the -H/home/tirthankar/projects/physicc/Light/Editor part. I searched the CMake Docs for this behavior, but all I could find for the -H was this:

CMake Docs saying that -H is for printing the help docs to the terminal

So the question is, what does -H do in CMake? Is it a standard feature? Is it a deprecated feature? Did the CMake Tools Extension make a mistake?

For reference, here is the entire output:

[kit] Successfully loaded 3 kits from /home/tirthankar/.local/share/CMakeTools/cmake-tools-kits.json
[main] Configuring folder: Light 
[proc] Executing command: /usr/bin/cmake --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug -H/home/tirthankar/projects/physicc/Light/Editor -B/home/tirthankar/projects/physicc/Light/build -G Ninja
[cmake] Not searching for unused variables given on the command line.
[cmake] -- The C compiler identification is GNU 10.3.0
[cmake] -- The CXX compiler identification is GNU 10.3.0
[cmake] -- Check for working C compiler: /usr/bin/cc
[cmake] -- Check for working C compiler: /usr/bin/cc -- works
[cmake] -- Detecting C compiler ABI info
[cmake] -- Detecting C compiler ABI info - done
[cmake] -- Detecting C compile features
[cmake] -- Detecting C compile features - done
[cmake] -- Check for working CXX compiler: /usr/bin/c++
[cmake] -- Check for working CXX compiler: /usr/bin/c++ -- works
[cmake] -- Detecting CXX compiler ABI info
[cmake] -- Detecting CXX compiler ABI info - done
[cmake] -- Detecting CXX compile features
[cmake] -- Detecting CXX compile features - done
[cmake] -- Found OpenGL: /usr/lib/x86_64-linux-gnu/libOpenGL.so   
[cmake] -- Looking for pthread.h
[cmake] -- Looking for pthread.h - found
[cmake] -- Performing Test CMAKE_HAVE_LIBC_PTHREAD
[cmake] -- Performing Test CMAKE_HAVE_LIBC_PTHREAD - Failed
[cmake] -- Looking for pthread_create in pthreads
[cmake] -- Looking for pthread_create in pthreads - not found
[cmake] -- Looking for pthread_create in pthread
[cmake] -- Looking for pthread_create in pthread - found
[cmake] -- Found Threads: TRUE  
[cmake] -- Using X11 for window creation
[cmake] -- Found X11: /usr/include   
[cmake] -- Looking for XOpenDisplay in /usr/lib/x86_64-linux-gnu/libX11.so;/usr/lib/x86_64-linux-gnu/libXext.so
[cmake] -- Looking for XOpenDisplay in /usr/lib/x86_64-linux-gnu/libX11.so;/usr/lib/x86_64-linux-gnu/libXext.so - found
[cmake] -- Looking for gethostbyname
[cmake] -- Looking for gethostbyname - found
[cmake] -- Looking for connect
[cmake] -- Looking for connect - found
[cmake] -- Looking for remove
[cmake] -- Looking for remove - found
[cmake] -- Looking for shmat
[cmake] -- Looking for shmat - found
[cmake] -- Looking for IceConnectionNumber in ICE
[cmake] -- Looking for IceConnectionNumber in ICE - found
[cmake] -- Build spdlog: 1.8.5
[cmake] -- Build type: Debug
[cmake] -- Configuring done
[cmake] -- Generating done
[cmake] -- Build files have been written to: /home/tirthankar/projects/physicc/Light/build

Edit: I opened an issue on the CMake Tools GitHub page.

visual-studio-code cmake
2 Answers

The -H option is used for printing the help documentation for CMake.

-H has never been a standard or documented CMake flag for generating a project. You should not use it and you should disregard any "resources" that encourage you to use undocumented flags. If a Visual Studio Code extension is using it, you should open an issue with the authors of the extension.

The documented equivalent is -S, which sets the source directory. By default, it is the current directory. It was introduced in CMake 3.13. See the latest documentation here: https://cmake.org/cmake/help/latest/manual/cmake.1.html#generate-a-project-buildsystem

There might be subtle behavioral differences between -H and -S. Do not use undocumented/internal flags.

user_21379960

-H is indeed the flag for displaying the help docs, as @Alex Reinking, but there is another undocumented meaning.

While looking for good resources for learning CMake, I stumbled across CGold, which also mentions the -H flag as a way to supply the path to the source.

Add -H<path-to-source-tree> to set directory with CMakeLists.txt. This internal option is not documented but widely used by community. There must be no spaces between -H and <path-to-source-tree> (otherwise option will be interpreted as synonym to --help). Always must be used with -B option.

Here are some specific pointers to projects which use (or recommend using) the -H flag to point to the source directory.

In fact, as CGold suggests, there was a patch submitted a long time ago which aimed to actually document the internal -H flag.

However, it should be noted that one of the developers replied with

These are undocumented because they are internal options that are not meant for public use.

So, we should not use those flags, and stick to the functionally equivalent (as pointed out by @Alex Reinking) -S flag if we need to pass in the source directory.

user_125913880
Related