From ba574d53e126b50a724c538f223608faca15551a Mon Sep 17 00:00:00 2001
From: Noah Swerhun <noah@noahsw.xyz>
Date: Sat, 16 Mar 2024 19:28:38 -0500
Subject: [PATCH] added info about cmd_fmt

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/README.md b/README.md
index 6f6ae04..a1212a8 100644
--- a/README.md
+++ b/README.md
@@ -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.