# Integrating `cargo-parcel` into a crate

Short instructions are provided in the [template
README](../templates/README.md). There is also a cargo plugin, which
automates the process for you, dropping the required files in place:

```
$ cargo install cargo-parcel
$ cargo parcel init
```

For details, read on.

You can have a look at the
[`templates/hello-world`](../templates/hello-world/) directory for a
simple example project with the `cargo-parcel` boilerplate applied. It
essentially boils down to these steps:

- Create a new crate in your project root. If you happen to use a
  cargo workspace, you will likely *not* want to add this crate to
  your workspace. In alignment with the `xtask` pattern, using the
  `parcel` directory below your crate root is suggested, but any
  subdirectory, also a nested one, should work fine.

  ```sh
  cargo new parcel
  ```
- Make the newly created crate implement a `parcel` cargo subcommand,
  by creating `.cargo/config` below your crate root, with the
  following contents:

  ```toml
  [alias]
  parcel = "run --manifest-path ./parcel/Cargo.toml --"
  ```

  You want to add `.cargo/config` to version control, so that users
  can access the new subcommand as well.

- Replace `src/main.rs` in the new crate with this boilerplate:

  ```rust
  fn main() {
      cargo_parcel::main();
  }
  ```

Now you can use `cargo parcel install` as an extended substitute for
`cargo install`. Here is some example output from running the included
`hello-world` example:

```
~/src/hello-world$ cargo parcel install --dest-dir /tmp/foo --verbose
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `parcel/target/debug/parcel install --dest-dir /tmp/foo --verbose`
Pre-install: running cargo build (default), passing prefix /home/user/.local
* cargo build --release
   Compiling hello-world v0.0.1 (/home/user/src/crates/cargo-parcel/examples/hello-world)
    Finished release [optimized] target(s) in 0.14s
Pre-install: stripping binaries
* strip target/parcel/stripped/hello-world
Pre-install: running pandoc for man page hello-world.1.md
* pandoc -s -M section=1 -t man -o target/parcel/man/hello-world.1 hello-world.1.md
/tmp/foo/home/user/.local/bin/hello-world copied from target/parcel/stripped/hello-world (stripped cargo binary)
/tmp/foo/home/user/.local/share/man/man1/hello-world.1 copied from target/parcel/man/hello-world.1 (man page, rendered from hello-world.1.md)
```

### Using the installation prefix

The above instructions are sufficient for application crates that do
not need the installation prefix compiled into them. However, if the
installed Rust binaries need to access some resources installed along
with them, such as external translation files, having the expected
installation location compiled into the binary is required, or at
least desirable in most cases, as it spares users to specify that
location themselves.

To make use of this feature in your code, just refer to the
`PARCEL_INSTALL_PREFIX` environment variable using the `env` or
`option_env` functions from the Rust standard library. If you chose
`env` however, that will require `PARCEL_INSTALL_PREFIX` to be defined
when building the project; when calling cargo-parcel commands, such as
`cargo parcel install`, this will be taken care of, but it will break
regular `cargo build`, unless `PARCEL_INSTALL_PREFIX` is set
manually. Hence it is recommended to use `option_env!` and to provide
fallback behavior in case the environment variable is not
defined.

Take a look at
[`templates/hello-world-i18n`](../templates/hello-world-i18n/) for an
example, and don't forget to include the code in `build.rs` that lets
cargo trigger a rebuild, should the value of the environment variable
have been changed.