mirror of
https://github.com/github/codeql.git
synced 2025-12-18 09:43:15 +01:00
ede6bd8ffe
This adds: * a base `README.md` file to `codegen` * module docstrings for the modules in `generators` * help strings on all command line flags Moreover some unneeded command line flags (`--namespace`, `--include-dir` and `--trap-affix`) have been dropped.
38 lines
2.1 KiB
Markdown
38 lines
2.1 KiB
Markdown
# Code generation suite
|
|
|
|
This directory contains the code generation suite used by the Swift extractor and the QL library. This suite will use
|
|
the abstract class specification of [`schema.yml`](schema.yml) to generate:
|
|
|
|
* [the `dbscheme` file](../ql/lib/swift.dbscheme) (see [`dbschemegen.py`](generators/dbschemegen.py))
|
|
* [the QL generated code](../ql/lib/codeql/swift/generated) and when
|
|
appropriate [the corresponding stubs](../ql/lib/codeql/swift/elements) (see [`qlgen.py`](generators/qlgen.py))
|
|
* C++ tags and trap entries (see [`trapgen.py`](generators/trapgen.py))
|
|
* C++ structured classes (see [`cppgen.py`](generators/cppgen.py))
|
|
|
|
## Usage
|
|
|
|
By default `bazel run //swift/codegen` will update all checked-in generated files (`dbscheme` and QL sources). You can
|
|
append `--` followed by other options to tweak the behaviour, which is mainly intended for debugging.
|
|
See `bazel run //swift/codegen -- --help` for a list of all options. In particular `--generate` can be used with a comma
|
|
separated list to select what to generate (choosing among `dbscheme`, `ql`, `trap` and `cpp`).
|
|
|
|
C++ code is generated during build (see [`swift/extractor/trap/BUILD.bazel`](../extractor/trap/BUILD.bazel)). After a
|
|
build you can browse the generated code in `bazel-bin/swift/extractor/trap/generated`.
|
|
|
|
## Implementation notes
|
|
|
|
The suite uses [mustache templating](https://mustache.github.io/) for generation. Templates are
|
|
in [the `templates` directory](templates), prefixed with the generation target they are used for.
|
|
|
|
Rather than passing dictionaries to the templating engine, python dataclasses are used as defined
|
|
in [the `lib` directory](lib). For each of the four generation targets the entry point for the implementation is
|
|
specified as the `generate` function in the modules within [the `generators` directory](generators).
|
|
|
|
Finally, [`codegen.py`](codegen.py) is the driver script gluing everything together and specifying the command line
|
|
options.
|
|
|
|
Unit tests are in [the `test` directory](test) and can be run via `bazel test //swift/codegen/test`.
|
|
|
|
For more details about each specific generation target, please refer to the module docstrings
|
|
in [the `generators` directory](generators).
|