added info about cmd_fmt

This commit is contained in:
Noah Swerhun 2024-03-16 19:28:38 -05:00
parent 62892a0ba7
commit ba574d53e1

View file

@ -322,3 +322,55 @@ compiler_flags = ["-g"]
compiler_flags = ["-O2"]
```
## Advanced Usage
Lets say that your project also has a library in the `lib` folder, with two
files, `lib.c` and `functions.c`. You want to compile these into a
`libexample.a` file so that you can link them to your main executable. Add a new
target called `lib`:
```toml
[targets.lib]
opts.inherit = false
outfile = "libexample.a"
compiler = "gcc"
linker = "ar"
linker_flags = "r"
sources = [
"lib/lib.c",
"lib/functions.c",
]
```
If you try to run this as is, you will see that there is a problem with the link
step. ngen constructs commands according to a certain format to make
configuration easier. The format for the link step is `{linker} {linker_flags}
-o {outfile} {objects} {linker_libs}`. This means that currently, the above
configuration is trying to run `ar r -o libexample.a <object files>`. `ar` does
not take an `-o` flag. We can change this format string to properly produce the
library. Add the following entry to the `lib` target above:
```toml
opts.link_cmd_fmt = "{linker} {linker_flags} {outfile} {objects} {linker_libs}"
```
By removing the `-o` flag, the library should "link" correctly now. But, we
could simplify this configuration slightly by removing some of those unnecessary
format placeholders. Here is an alternate form that should work exactly the same:
```toml
[targets.lib]
opts.inherit = false
opts.link_cmd_fmt = "ar r {outfile} {objects}"
outfile = "libexample.a"
compiler = "gcc"
sources = [
"lib/lib.c",
"lib/functions.c",
]
```
An option `opts.comple_cmd_fmt` also exists. Its default is `{compiler}
{compiler_flags} -MD -MF {depfile} -o {object} -c {source}`. Note that if you
remove the `-MD -MF {depfile}` component, ninja will have no way to discover
what header files your source file depends on.