![logo](assets/wordmark.png)
# crustex
A simple, rust-based, latex meta-build system. crustex is in very early development.

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:

```bash
cargo install crustex
```

or you can build from source
```bash
git clone https://github.com/tboudreaux/crustex.git
cd crustex
cargo build --release
cargo install --path .
```

# Usage
crustex has three main jobs

1. Keyed naming of template git repositories
2. Initialization of a crustex project from either a template repository or from a default template
3. 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:

```bash
crustex template register <key> <git-url>
```

you can list all registered templates with

```bash
crustex template list
```

You can unregister a template with

```bash
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.
```bash
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:

```bash
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:

```bash
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:
```toml
[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:

```bash
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.