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

Packaging ecosystems tend to have specific ways to accomplish common packaging tasks, likely including some of what’s required to package Engage. This page is written to be broadly informative, so if the ecosystem in question has a more specific way to do something, that should take precedence over the guidance here.

This page uses a convention where $SOURCE refers to the project root and $PACKAGE refers to the location containing the files that will be copied to the user’s filesystem root when the resulting package is installed (or equivalent).

Supported platforms

Engage is continuously built and tested on x86_64-unknown-linux-gnu. Other CPU architectures and libc implementations should work. Other Unix-like platforms may work. Windows won’t work.

Packaging the book

The book is built with mdBook. Running the command mdbook build in $SOURCE will build the book and write it to the directory $SOURCE/public. This must then be moved into the package at the appropriate location, such as $PACKAGE/usr/share/doc/engage (renaming public to engage).

Packaging Engage

The environment variable ENGAGE_BOOK_PATH should be set when building Engage. If omitted, the output of the command engage --help will indicate that the environment variable was not set at build time. The value of the environment variable should be the absolute path of where the book will be installed on a user’s system, such as /usr/share/doc/engage (note the lack of $PACKAGE). The path must not contain a trailing slash. The path may be relative, though this will degrade the user experience, as it may not be clear what the path is relative to and it cannot be linked to via a file: URI.

Engage is built with Cargo. Running the command cargo build --release --package engage in $SOURCE will build Engage with optimizations and write it to the executable $SOURCE/target/release/engage. The exact path is different under certain circumstances, such as cross compilation. Appending the arguments --message-format json to the build command will cause the exact path to be printed out. The executable must then be moved into the package at the appropriate location, such as $PACKAGE/usr/bin/engage.

Packaging the shell completions

The shell completions are built with an xtask, which is in turn built with Cargo. If the directory $SOURCE/.cargo is retained, the “xtask command” will be cargo xtask completions; if not, the “xtask command” will be cargo run --package xtask -- completions. The xtask command should be run in the $SOURCE directory. Running the xtask command with the option --help appended will enumerate the command line values for the supported shells. Running the xtask command with one of those values appended will write the completions for that shell to stdout. This must then be used to write each shell’s completions into the package at the appropriate location. Completions for shells unsupported by the platform may be ignored.

Running checks in the package

This section may be skipped if it is undesirable or not possible to run these checks as part of building the package.

To run the relevant checks, run the command cargo test --release --package engage in $SOURCE with the environment variable ENGAGE_BOOK_PATH set to the same value as when building Engage. This command should be run after Engage has been built, but before the executable has been moved. The book and shell completions are not necessary for this command to succeed.

There are other checks, but they aren’t important in a packaging context, so they may be ignored.

Post-installation checks

Now that the package is complete, it can be checked by building it, installing it, and ensuring that:

  1. Executables from Engage’s Cargo workspace other than engage, such as xtask, were not accidentally included in the package.
  2. The command engage --help runs at all.
  3. The line containing “Book” in the output of the command engage --help either:
    • Includes a file: URI that points to the index.html of the installed book.
    • Is a path that points to the index.html of the installed book.
  4. Shell completions for the commands and options for the executable engage work. Shell completions for values are not currently expected to work (see #17).