cargo-resources

A cargo executable crate for managing resources.

TLDR

Declare files as resources from your Cargo.toml files.

[package.metadata.cargo_resources]
provides = [
    { crate_path = "resources/hello_world.txt", output_path="hello_world.txt" }
]

Collate all the resources declared by a crate's dependencies (i.e. referenced crates), using a cargo command.

cargo resources

Overview

What do we mean by Resources

Resources are all those non-code files/artifacts that you need to help you software build or run as intended. These include:

• static resources (i.e. fixed at compile time)
• dynamic resources (i.e. determined at run-time)

Often Resources are used during the execution of the program itself (possibly including tests, benches etc.), but there are also valid use-cases during build or deployment.

Why don't we just use Rust/Cargo?

Rust and Cargo don't provide much structured help for dealing with resources, especially for the dynamic cases.

By default, Cargo will include any git configured files in the published crate, and Rust provides the include_str! and include_bytes! macros. Which support simple static resource usage for things like test data (e.g. unit-test data-files declared within the crate).

For simple cases an external tool/crate isn't required and a 'resources' folder next to 'src' and usages via include_str! (with a relative path) are sufficient.

For help with dynamic (run/build time) or resources from external crates this crate provides a more structured approach.

Installation

Recommend installation is via cargo install with fixed dependencies:

cargo install cargo-resources --fixed

Configuring Declared Resources

Resources are declared using Cargo metadata, as this is the cargo resources crate, these are declared in a 'section':

[package.metadata.cargo_resources]

Within this 'section' each resource is declared in the provides 'array' as a key/value table:

provides = [
    { crate_path = "resources/hello_world.txt", output_path="hello_world.txt" }
]

The supported information for each resource is:

Normal usage is therefore setting crate_path and output_path, or just crate_path when output_path is identical.

Declaring Resource Usage

By convention a crate does not need to specify resource usage and defaults to collating all resources from the dependencies, to a default resource path.

When this is not the required behaviour, the using crate specifies its requirement in its Cargo.toml:

[package.metadata.cargo_resources]

Within this 'section' the following information can be provided:

The list of required resources

These are specified the 'requires' array:

requires = [
    { resource_name="hello_world.txt" }
]

The supported information for each resource is:

NB. If the required sha is set any change of the upstream resource will require a deliberate update in the using crate.

Collation Options

Collation options are provided as key value pairs within the 'section', For instance:

resource_root = "target/resources"

The supported Options are:

Features

This crate declares the following features: None as yet!

Version History

Troubleshooting

1. It works locally but not from a published crate.

   • Check the resources are included in the published crate (add to include in the cargo.toml if required).

2. Returns an error of : "Unable to canonicalize resource path: ...".

   • A directory/folder in the output path does not exist.