Packaging Difftastic - Difftastic Manual
Description: The manual for difftastic, the structural diff tool

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Packaging Difftastic

This page contains recommendations for people creating a difftastic package.

Note that the difftastic author only provides the source code and the prebuilt binaries on GitHub. Packages have been created by other people – thank you!

## Packaging The Binary

Difftastic can be built with `cargo`. The compiled binary will be at `target/release/difft` when using the following command.

    $ cargo build --release

C library dependencies are built with the `cc` crate, which has various environment variables to configure the C toolchain (e.g. `CFLAGS`).

### Reproducible Builds

Difftastic’s build script (the `build.rs` file) uses Rayon to build C libraries in parallel, which can lead to minor ordering changes in the final binary.

You can avoid this by disabling Rayon parallelism.

    $ RAYON_NUM_THREADS=1 cargo build --release

### MIME Database

Difftastic depends on tree_magic_mini, which accesses the MIME database on the current system. The MIME database is used to recognise file types, so difftastic does not try to compoare binary files as text.

This means that the difftastic package should depend on a MIME database package, if available.

Difftastic respects the XDG base specification to find the MIME database files. These files are typically at `/usr/share/mime/`, `/usr/local/share/mime/` or `/opt/homebrew/share/mime/`.

## Man Page

As of difftastic 0.58, a man page is available. See the file `difft.1`.

This file is generated from `difft.1.md`, but the generated `difft.1` is included in the repository for convenience.

## The Manual

Please consider including the difftastic manual with your package. These are HTML files that can be generated with `mdbook`. The following command generates HTML at `manual/book/`.

    $ cd manual
    $ mdbook build

`manual/book.toml` also references a script `replace_version_placeholder.sh` that replaces occurrences of `DFT_VERSION_HERE` in the manual. For packaging, it may be easier to remove the configuration from `book.toml` and replace the text directly.

    -[preprocessor.replace-version-placeholder]
    -command = "./replace_version_placeholder.sh"

    $ export CURRENTVERSION="7.8.9"
    $ sed -i "s/DFT_VERSION_HERE/$CURRENTVERSION/g" -i src/introduction.md

## Testing

If your packaging tool supports testing, consider running the difftastic unit tests.

    # Run the normal tests.
    $ cargo test

    # Run the tests that depend on the
    # MIME database being present.
    $ cargo test -- --ignored