web-static-pack-packer

web-static-pack-packer is the "builder" (1st stage) part of the web-static-pack project. See project page for a general idea how two parts cooperate.

The goal of the packer part is to collect your directories / files / memory slices, precalculate things like ETag, compressed versions (gzip, brotli) and store them as a single file (called pack). Your target application will include (ex. with https://docs.rs/include_bytes_aligned/latest/include_bytes_aligned/ ) and "load" / "parse" pack during runtime using web-static-pack (the loader part) and (possibly) serve it with a web server of your choice.

This crate is usually used in build script / CI / build.rs stage, not in your target application. It's used to create a pack from list of files (like your GUI app / images / other assets) to be later loaded by your app and served with a web server.

This crate can be used in two ways:

• As a standalone application, installed with cargo install, this is the preferred way if you are using build scripts, CI pipeline etc.
• As a library, imported to your project, this is a way to go if you want to use it in build.rs of your target application or go with some really custom approach

Using as a standalone application

Install (or update to matching version)

• Either install it with $ cargo install web-static-pack-packer and use shell command $ web-static-pack-packer [PARAMS]...
• Or clone repo, go into packer directory, $ cargo run --release -- [PARAMS].... (please note -- which marks end of arguments for cargo run and beginning of arguments for the application).

For the purpose of this example, the first option is assumed, with web-static-pack-packer command available.

Create a pack

web-static-pack-packer provides up to date documentation with $ web-static-pack-packer --help. Application is built around subcommands to cover basic scenarios:

• directory-single [OPTIONS] <INPUT_DIRECTORY_PATH> <OUTPUT_FILE_PATH> will create a pack from a single directory. This is the most common scenario, for example when you have a web application built into ./gui/build directory and you want to have it served with your app.
• files-cmd [OPTIONS] <OUTPUT_FILE_PATH> <INPUT_BASE_DIRECTORY_PATH> [INPUT_FILE_PATHS]... lets you specify all files from command line in xargs style. base directory path is used as a root for building relative paths inside a pack.
• files-stdin [OPTIONS] <INPUT_BASE_DIRECTORY_PATH> <OUTPUT_FILE_PATH> lets you provide list of files from stdin.

Examples

Let's say you have a vcard-personal-portfolio directory containing your web project (available in tests/data/ in repository). Directory structure looks like:

vcard-personal-portfolio
|   index.html
|   index.txt
+---assets
|   +---css
|   |       style.css
|   +---images
|   |       <some files>.png
|   \---js
|           script.js
\---website-demo-image
        desktop.png
        mobile.png

By running:

$ web-static-pack-packer \
    directory-single \
    ./vcard-personal-portfolio \
    ./vcard-personal-portfolio.pack

a new file vcard-personal-portfolio.pack will be created, containing all files, so that GET /index.html or GET /assets/css/tyle.css or GET /website-demo-image/mobile.png will be correctly resolved.

In the next step, the vcard-personal-portfolio.pack should be used by web-static-pack (the loader part) to serve it from your app.

Using as a library

When using as a library, you are most likely willing to create a loadable (by the loader) pack, by using [pack::Builder].

You will need to add [file_pack_path::FilePackPath] (file + path) objects to the builder, which you can obtain by:

• Manually constructing the object from [common::pack_path::PackPath] and [common::file::File] (obtained from fs [file::build_from_path] or memory slice [file::build_from_content]).
• Reading single file with [file_pack_path::FilePackPath::build_from_path].
• Automatic search through fs with [directory::search].

When all files are added to the builder, you will need to finalize it and either write to fs (to have it included in your target application) with [pack::store_file] or (mostly for test purposes) serialize to memory with [pack::store_memory].

Examples

This example will do exactly the same as one for application scenario:

// start with empty pack builder
let mut pack = Builder::new();

// add files with directory search and default options
pack.file_pack_paths_add(search(
    &PathBuf::from("vcard-personal-portfolio"),
    &SearchOptions::default(),
    &BuildFromPathOptions::default(),
)?)?;

// finalize the builder, obtain pack
let pack = pack.finalize();

// store (serialize `pack` to the fs) to be included in the target app
store_file(&pack, &PathBuf::from("vcard-personal-portfolio.pack"))?;

For more examples browse through modules of this crate.

License: MIT