Merge pull request #75 from trailofbits/codeql-install-updates

Codeql install updates

Author: elopez

content/docs/static-analysis/codeql/10-advanced.md

@@ -38,6 +38,55 @@ by default.
 If you are using the CodeQL VSCode extension to write and run queries, [it can
 initialize the query pack and create the `qlpack.yml` file automatically](#running-custom-queries-using-the-vscode-extension).
 
+Finally, you have to create a [workspace file](https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces) for the CodeQL CLI to work correctly.
+
+If you know you will write more than one query pack, we recommend creating the following directory structure to make development easier:
+
+```plain
+.
+├── CODEOWNERS
+├── README.md
+├── codeql-workspace.yml
+├── cpp
+│   ├── lib
+│   │   ├── qlpack.yml
+│   │   └── scope
+│   │       └── security
+│   │           └── someLibrary.qll
+│   ├── src
+│   │   ├── qlpack.yml
+│   │   ├── suites
+│   │   │   ├── scope-cpp-code-scanning.qls
+│   │   │   └── scope-cpp-security.qls
+│   │   ├── security
+│   │   │   └── AppSecAnalysis
+│   │   │       ├── AppSecAnalysis.c
+│   │   │       ├── AppSecAnalysis.qhelp
+│   │   │       └── AppSecAnalysis.ql
+│   └── test
+│       ├── qlpack.yml
+│       ├── include
+│       │   ├── libc
+│       │   │   ├── stubs.h
+│       ├── library-tests
+│       │   └── security
+│       │       ├── someLibrary
+│       │       │   ├── someLibrary.c
+│       │       │   ├── someLibrary.expected
+│       │       │   └── someLibrary.ql
+│       └── query-tests
+│           └── security
+│               └── AppSecAnalysis
+│                   ├── AppSecAnalysis.c
+│                   ├── AppSecAnalysis.expected
+│                   └── AppSecAnalysis.qlref
+...
+```
+
+We divide query packs per-language, but also per-type (security, cryptographic, etc.). This also follows the convention used by the GitHub query suites.
+
+For recommendations on how to set up query unit tests, see the [Unit testing custom queries](#unit-testing-custom-queries) section.
+
 ### Adding dependencies
 
 To be able to define a custom query we need to import the CodeQL standard
@@ -199,6 +248,17 @@ dependencies:
 of the version you want, you can use `"*"` which always resolves to the latest
 version.)
 
+### Installing the new packs
+
+Once you have initialized the new query pack, added dependencies and some sample queries, you need to run
+`codeql pack install` in every directory that has a qlpack.yml file (including folders with test).
+
+Then, inform the codeql CLI about your new queries by creating `~/.config/codeql/config` file with the following content:
+
+```plain
+--search-path /full/path/to/your/codeql/root/directory
+```
+
 ## Writing custom queries
 
 {{< hint info >}}
@@ -476,8 +536,12 @@ directory should contain the following three files:
 - `MemcpyCall.expected`: A text file containing the expected output from
   running the query against the source file
 
-The source file must build cleanly without any external dependencies. To test
-the query, run the following command:
+The source file must build cleanly without any external dependencies.
+This requirement is problematic mostly for C/C++ queries: you need to create
+stub files with `extern` declarations for libraries you want to `#include`.
+Check out [our tests](https://github.com/trailofbits/codeql-queries/blob/d994c7ca05dab30fe195555ef6943f9d51ec38df/cpp/test/query-tests/security/CStrnFinder/test.c#L1) for examples.
+
+To test the query, run the following command:
 
 ```sh
 codeql test run -- path/to/test/pack/root/directory