# Hooks
If you find that you need Trunk to perform an additional build action that isn't supported directly, then Trunk's
flexible hooks system can be used to launch external processes at various stages in the pipeline.
## Build steps
This is a brief overview of Trunk's build process for the purpose of describing when hooks are executed. Please note
that the exact ordering may change in the future to add new features.
- Step 1 — Read and parse the HTML file.
- Step 2 — Produce a plan of all assets to be built.
- Step 3 — Build all assets in parallel.
- Step 4 — Finalize and write assets to staging directory.
- Step 5 — Write HTML to staging directory.
- Step 6 - Replace `dist` directory contents with staging directory contents.
The hook stages correspond to this as follows:
- `pre_build`: takes place before step 1.
- `build`: takes place at the same time as step 3, executing in parallel with asset builds.
- `post_build`: takes place after step 5 and before step 6.
## Hook execution
Hooks can be declared exclusively in `Trunk.toml`, and consist of a `stage`, `command` and `command_arguments`:
- `stage`: (required) one of `pre_build`, `build` or `post_build`. It specifies when in Trunk's build pipeline the hook
is executed.
- `command`: (required) the name or path to the desired executable.
- `command_arguments`: (optional, defaults to none) any arguments to be passed, in the given order, to the executable.
At the relevant point for each stage, all hooks for that stage are spawned simultaneously. After this, Trunk immediately
waits for all the hooks to exit before proceeding, except in the case of the `build` stage, described further below.
All hooks are executed using the same `stdin` and `stdout` as trunk. The executable is expected to return an error code
of `0` to indicate success. Any other code will be treated as an error and terminate the build process. Additionally,
the following environment variables are provided to the process:
- `TRUNK_PROFILE`: the build profile in use. Currently, either `debug` or `release`.
- `TRUNK_HTML_FILE`: the full path to the HTML file (typically `index.html` in `TRUNK_SOURCE_DIR`) used by trunk.
- `TRUNK_SOURCE_DIR`: the full path to the source directory in use by Trunk. This is always the directory in
which `TRUNK_HTML_FILE` resides.
- `TRUNK_STAGING_DIR`: the full path of the Trunk staging directory.
- `TRUNK_DIST_DIR`: the full path of the Trunk dist directory.
- `TRUNK_PUBLIC_URL`: the configured public URL for Trunk.
## OS-specific overrides
Often times you will want to perform the same build step on different OSes, requiring different commands.
A typical example of this is using the `sh` command on Linux, but `cmd` on Windows.
To accomodate this, you can optionally create OS-specific overrides for each hook.
To do this, specify the default hook, then directly below it create a `[hooks.<os>]` entry where `<os>`
can be one of `windows`, `macos`, or `linux`. Within this entry you must specify only the `command` and
`command_argumnets` keys. You may provide multiple overrides for each hook. i.e.
One for `windows`, one for `macos`, and one for `linux`.