# Cacheing

Nearly all caching happens in `$(pwd)/.trblcache` by default (hereafter `$CACHE`),
here's a reminder of the process `trblcache` uses when building documentation:

0. Scan: find all source files under the input folders whose extension has
   a registered comment form (`c`, `h`, `cpp`, `hpp`, `lua`, `py`, `sql`,
   `md`, `dot`, plus any `-f` additions).
0. Extract: run each file through an AWK program that emits chunk files
   into `$CACHE/chunks/`.
0. Render: for each chunk, strip directives, run the renderer, and append
   output to `$CACHE/namespace/<namespace>/index.html`.
0. Assemble: write `main.layout`, `nav.partial`, `global.meta`, and CSS
   into `$CACHE/namespace/`.
0. Build: apply the layout/template tokens to each namespace page and
   write the final site to `-o <dest>` (default `$CACHE/built`).

Of these, only chunk extraction can be cached. Cacheing works by first
creating a file under `$CACHE/last_processed/<path>` when a file is processed,
and then on subsequent processing, ignore files if their `$CACHE/last_processed/<path>`
file timestamp is newer than the `<path>` timestamp. If your filesystem does
not support file timestamps, `trbldoc` will never assume the cache is invalid,
and will serve stale data. If you are on such a system, always run with `-C` to
force `trbldoc` to generate new chunks.

## Notes

### No cached chunks
The rendered chunks, generally, cannot be cached. If the user provided their
own tooling (i.e. bash scripts) for `trbldoc`, `trbldoc` cannot check for updates
to the scripts in order to invalidate the cached rendered chunk. Checking
file last updated times won't work, if a script invokes another script or relies
on any system environment the user's updates won't take. Example:

```
project
| src/
| | file1.c - last updated 1d ago
| tools/
| | checker.sh - last updated 1d ago
| | graph.sh - last updated 30s ago
```

file1.c

```c
...
/* tools/checker.sh tools/graph.sh
strict graph { 
  a -- b
  a -- b
  b -- a [color=blue]
}
*/
...
```

checker.sh

```sh
#!/bin/sh

if [ -z "$(command $1 -V)" ]; then
    echo "Could not find $1"
    exit -1
fi

exec $1
```

graph.sh

```sh
#!/bin/sh

exec dot
```

It would be impossible for `trbldoc` to determine that `tools/checker.sh` uses
`tools/graph.sh` without forcing it to run in a hermetically sealed sandbox that
carefully controls what environment, filesystem, and other programs may be run.
Such heavy sandboxing is against the vision of `trbldoc` as a simple, single-file
documentation generator.