# Fac file format

$docnav

To configure this build system, you create one or more files ending
with `.fac`.  These files specify the rules to build your project,
and must be added to your git repository.  For most moderately complex
projects, you will have just one `.fac` file in git, which will
itself specify specify rules needed to create one or more additional
`.fac` files, which will contain the rules for doing the actual
build.  Each `.fac` file consists of:

1. Comments beginning with `"# "` (a pound sign followed by a space).

2. Rules beginning with `"| "` (a pipe character followed by a
   space).  The remainder of the line is the actual command to perform
   the build.  Following this line (possibly separated by blank lines
   and comments) are one or more of the following directives.  The
   order of these directives has no effect, so long as the follow the
   `"| "` line to which they apply.

2. Rules beginning with `"* "` (an asterisk followed by a space).
   This rule is identical to a pipe rule, but will rerun the command
   if there are changes to the contents of any directories the rule
   calls `readdir(3)` on (or technically `getdents(2)`).  You need to
   use this rule if you use a wildcard or glob and what the command to
   be rerun if new files are added.  This behavior is no longer the
   default (i.e. the pipe behavior) because it causes many rebuilds
   when `python3` is run, since it always reads the current directory
   when the first module is imported.

2. Optional rules beginning with `"? "` are identical to rules
   beginning with a pipe, with the sole difference being that optional
   rules are only built if they are needed to build another target, or
   if they are explicitly requested, e.g. by invoking `fac
   optional-output-filename`.  Optional rules enable you to specify a
   large number of rules and only have what is needed built.  Optional
   rules should always specify at least one output file, or they will
   never be built.
   <p>
   Optional rules can be helpful for rules (often autogenerated) that
   might be slow or require dependencies that not all users will
   have.  They can be convenient for scripts that define a whole slew
   of rules in a facfile, and which don't want to determine which of
   these are needed for the actual build.  Or for something like
   documentation, which only some users will want to actually build.
   </p>

3. Output specifications beginning with `"> "` followed by the name of
   the file that is output.  There is no escaping performed, and only
   newlines and null characters are disallowed in the file name.
   There is little need to specify the output for rules, since fac
   can determine this automatically.  The only reason to specify
   output is so that on the very first build a user can request that
   we build only the specified rule.

4. Input specifications beginning with `"< "` followed by the name of
   the file that is required.  You only need specify inputs when they
   are generated files.  Even then, you need only specify the inputs
   if you wish to have the build succeed on the first attempt.

5. Dependency output specifications beginning with `"M "` followed by
   the name of the deps file that is generated by the command.  This
   is designed for compilers which have the ability to track
   dependencies and output a `Makefile` fragment documenting those
   dependencies.  This is implemented for two reasons.  Firstly, by
   relying on the compiler for dependency tracking, fac can run more
   quickly than if it tracks file accesses itself.  Secondly, it makes
   fac more useful on platforms (currently Windows and Mac OS) where
   it is unable to track dependencies.  *This feature is only
   available in the version of fac implemented in rust.*

6. There are two ways to specify "cache" files.  A cache file is a
   file that may be either read or written by a given command, but
   doesn't affect the output and not itself an output.  One nice
   example is the ".pyc" files sometimes generated when you run a
   python program.  One python command may produce a .pyc file, and
   another may read it (if they both use the same module), but that
   does not mean that there is a dependency between those two
   commands.  You can specify a cache suffix (such as `.pyc`) using a
   `"c "` line, or you can specify a cache prefix (such as
   `~/.ccache`) using a capitalized `"C "` line.  The latter can be
   helpful if you find that your software is being rebuilt needlessly
   due to some cache file being modified.