--source-root as "Recommended" for C/C++

[yashi]

I think having --source-root as "Recommended" is helpful for users of modern C/C++ projects. Because if a project is using CMake or Meson, we usually move to builddir/ and run make or ninja. CMake has cmake --build builddir, but with Meson you must move to builddir/ first and meson compile.

So natually, we do

cmake -B builddir
or
meson setup builddir
cd builddir
codeql database create mydb --command ninja --language=c

But this doesn't work because source-root is not builddir but ...
Instead of the above, the following command line works in the builddir:

codeql database create mydb --command ninja --language=c --source-root ..

It'd be nice if we can enhance the document.

Thanks

[ginsbach]

Note that this is not the intended use of the --source-root option. Rather than calling codeql database create from within the build directory with --source-root .., we recommend calling it from the top-level directory with one of the following:

• --command "cd builddir ; ninja" or
• --working-dir builddir

It'd be nice if we can enhance the document.

Thank you for the suggestion. Can you specify where exactly in the documentation you would like the use of these command line arguments highlighted further? Are you referring to the CLI help page (codeql database create --help) or the online documentation?

[yashi]

Wow. Thank you for your correction!

In that case I'd personally use --command "ninja -C builddir". So that I don't need to use neither --source-root nor --working-dir.

Can you specify where exactly in the documentation you would like the use of these command line arguments highlighted further? Are you referring to the CLI help page (codeql database create --help) or the online documentation?

I was thinking about: https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis. Because I assume this is the first document users read when they start using CodeQL CLI.

I see that it has (emphasis mine):

CodeQL databases are created by running the following command from the checkout root of your project

But it wasn't strong enough to keep me runnng ninja from the checkout root of my project. It might be better to add "must" or "should" to the line?

Down below, we have:

If your codebase has a build command or script that invokes the build process, we recommend that you specify it as well:

  codeql database create <database> --command <build> \
        --language=<language-identifier>

Then, can we have something like

If your build system creates a dedicated build directory, we recommend that you specify --workking-dir as well:

  codeql database create <database> --command <build> \
        --working-dir builddir --language=<language-identifier>

Or as an example under the Specifying build commands section in addition to make:

• C/C++ project built using make or ninja:

codeql database create cpp-database --language=c-cpp --command=make

codeql database create cpp-database --language=c-cpp --command=ninja --working-dir builddir

WDYT?

[aibaars]

Your suggestions make sense. However, depending on what the build system really does it may be required to use either --working-dir builddir or --source-root builddir. The working directory simply changes the work directory before running the build command. The source root is used to make file paths relative before including them into the SARIF output or the other analysis result format. All results with file paths that are outside the source root are dropped, and for the ones inside the source root folder, CodeQL makes the path relative by stripping off the source root prefix.

For buildsystems that make a copy of the source tree in the builddir before compiling things, the right flag to use would be --source-root builddir. In this case the compiler will see the source files in the builddir and CodeQL should strip off the builddir path to produce results that correctly align with the source files in their original location.

There are also build systems that do not copy the source files, but simply like to do their work in the builddir. In this case the --working-dir is the right flag (or -C or similar flag of the build command itself).

Since it really depends on how each build system works, I am little reluctant to include examples that only sometimes work when people copy/paste them.

[yashi]

Either way is fine by me. I've already learned from both @ginsbach's and your comments. Even without documentation update, this discussion might be found by search engines and helpful to others like me.

Thank you both for your time!