diff --git a/assets/wordmark.png b/assets/wordmark.png new file mode 100644 index 0000000..331113a Binary files /dev/null and b/assets/wordmark.png differ diff --git a/assets/wordmark.svg b/assets/wordmark.svg new file mode 100644 index 0000000..9a77461 --- /dev/null +++ b/assets/wordmark.svg @@ -0,0 +1,101 @@ + + + +CSUTEX diff --git a/readme.md b/readme.md index 8bddf84..620e6ca 100644 --- a/readme.md +++ b/readme.md @@ -1,12 +1,116 @@ +![logo](assets/wordmark.png) # crustex A simple, rust-based, latex meta-build system. crustex is in very early development. -## Commands -- init -- setup -- compile -- clean -- version -- publish -- describe -- clear \ No newline at end of file +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 +``` + +you can list all registered templates with + +```bash +crustex template list +``` + +You can unregister a template with + +```bash +crustex template remove +``` + +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 +``` + +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 [--template, -t or --url, -u ] +``` + +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 +``` + +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. \ No newline at end of file