👋🏻 AFAICT we don't currently explain how to "wrap invocations of build commands with codeql database trace-command".

The section above uses codeql database create with --command='<build command>. Are these equivalent? (I notice that the trace-command help describes it as a plumbing command).

I wonder whether it should be more like:

Alternatively, we may be missing a section on how to use codeql database trace-command.

Yes, codeql database init followed by codeql database trace-command <command> followed by codeql database finalize should be equivalent to codeql database create --comand=<command>. The latter is the recommended way to create the DB if you have a single command. The former is the recommended way to create a DB if the build requires multiple commands (and you can't wrap them in a script to make them into a single command) and you can add codeql database trace-command in front of each one. The new indirect tracing option addresses the case where:

1. You have multiple build commands.
2. You cannot wrap them with codeql database trace-command.

Thanks for the extra information. It sounds as if we could do with a short overview giving the options for tracing the build for compiled languages. Possibly this would be better as part of a follow up PR, but I'll leave @ethanpalm to make the call on this.

One of the considerations we're trying to balance is to provide indirect tracing as an option for people who need it without directing people toward it unintentionally. This came up in naming and avoiding calling indirect build tracing an advanced option. It feels to me like indirect build tracing would be better introduced as a troubleshooting option rather than one of several options for tracing the build of compiled languages in general.

Perhaps a line at the beginning of Creating databases for compiled languages, after For compiled languages, CodeQL needs to invoke the required build system to generate a database, therefore the build method must be available to the CLI. explaining to see below about indirect build tracing if it is relevant to the specific use case. I think this could help direct people who need to use indirect build tracing to the procedure but won't cause people to think they should use indirect build tracing when they don't need to.

After a bit more thinking, I am going to open a separate issue for how we introduce this information because I think there are a few different approaches we can take.

I agree with @felicitymay's suggestion about providing a short guide on the options for compiled languages. There are many possibilities, but to me the high level options are:

• Do you use a well-known build system recognised by the CodeQL autobuilders? Use codeql database create (without a --command argument) to autobuild the code.
• Do you know the build command line? Use codeql database create ... --command "<build command>"
  • A variation of this is if you have multiple build command lines, in which case you would use trace-command multiple times. I don't think we need to mention that just yet.
• If neither of the above are suitable, for example if you are using preconfigured build steps from your CI system that do not expose the build command, then use indirect build tracing. Examples of such build steps are the VSBuild and MSBuild tasks in Azure DevOps.

Notably, indirect tracing is not a viable troubleshooting option. Aside from autobuild failing, there's no way to try out a build without it if you don't know the build command.

I agree with @felicitymay's suggestion about providing a short guide on the options for compiled languages. There are many possibilities, but to me the high level options are:

• Do you use a well-known build system recognised by the CodeQL autobuilders? Use codeql database create (without a --command argument) to autobuild the code.
• Do you know the build command line? Use codeql database create ... --command "<build command>"
  • A variation of this is if you have multiple build command lines, in which case you would use trace-command multiple times. I don't think we need to mention that just yet.
• If neither of the above are suitable, for example if you are using preconfigured build steps from your CI system that do not expose the build command, then use indirect build tracing. Examples of such build steps are the VSBuild and MSBuild tasks in Azure DevOps.

Notably, indirect tracing is not a viable troubleshooting option. Aside from autobuild failing, there's no way to try out a build without it if you don't know the build command.

This is a good explanation.

Optional: link to the docs on analyzing and uploading?

This comment is from the original and I overlooked line 288 in my earlier review. I think a copy/paste operation went slightly awry here. Based on --language I suspect this ought to be:

However, we don't mention omitting the --language option anywhere else in this article, so I wonder if we really want to introduce it here.

I agree with Felicity here - I think we want to keep the example limited to talking about indirect tracing so I would propose that we do not need to mention --language at all and can just remove the rest of this comment after "In this example, the CodeQL CLI has been downloaded and placed on the PATH.".

Documenting exactly how codeql database init behaves belongs in the documentation for that command, I think.