The motivation for crustex is my general exaustion with writting makefiles for latex projects. I am aware of tools such as latexmk; however, I wanted to create a tool that is more extensible while also exploring some rust programming and meta-build system design.

Installation

To install crustex, you will need to have rust and cargo installed. Once you have rust and cargo installed, you can install crustex by running the following command:

cargo install crustex

or you can build from source

git clone https://github.com/tboudreaux/crustex.git
cd crustex
cargo build --release
cargo install --path .

Usage

crustex has three main jobs

Keyed naming of template git repositories
Initialization of a crustex project from either a template repository or from a default template
Building of latex projects using a meta-build system

Templates

crustex uses git repositories as templates for initializing new projects. You can specify a template as a git url when initializing a new project or you can register a template with a key name for later use.

To register a template, use the following command:

crustex template register <key> <git-url>

you can list all registered templates with

crustex template list

You can unregister a template with

crustex template remove <key>

templates are stored in a configuration file located at ~/.config/crustex/templates.toml

Initializing a new project

The most basic use of crustex is to initialize a new latex project from a template.

crustex init my-new-project -d <directory>

if no directory is specified, crustex will create the project in a new directory named after the project.

To initialize a new project from a template, use the following command:

crustex init <project-name> [--template, -t <key> or --url, -u <git-url>]

if you do not specify a template, crustex will use the default template that contains a basic latex project structure and a crustex.toml file.

Building

crustex is heavily influenced by meson, and as such it tries to enforce a strict seperation between source and build files. The first step to build a custex project is to setup a build directory. This is done with the setup command:

crustex setup crustex.toml

This will read the crustex.toml file and create a built directory following the structure specified in the file.

An example crustex.toml file is shown below:

[config]
main_file = "test_project.tex"
job_name = "test_project"
build_dir = "build"
results_dir = "."

[compile]
latex_compiler = "pdflatex"
bibtex_compiler = "bibtex"
compiler_flags = ["-interaction=nonstopmode", "-halt-on-error"]
stages = ["latex", "bibtex", "latex", "latex"]

so in this case a directory build will be created. The crustex.toml file is copied to the build directory. Note that at this point no further changes to the crustex.toml file will be reflected in the build directory unless you run the setup command again (with the "--overwrite" flag if the build directory already exists) or run the reconfigure command.

Once the build directory is setup, you can compile the project with the compile command:

crustex compile <build-directory>

This will read the crustex.toml file in the build directory, and then scan the current directory for the main_file specified. The main file is then parsed and tokenized to construct a dependency graph for the project. If any files are missing, crustex will report an error and exit. If all files are present, crustex will check if the output file is more recent than all the input files. If it is, crustex will report that the project is up to date and exit. If the output file is not up to date, crustex will execute the stages specified in the crustex.toml file in order.

Unlike more robust build systems, there is no support for incremental builds. Generally this is because latex does not lend itself well to incremental builds due to the nature of the compilation process.