# web-static-pack-packer
web-static-pack-packer is the "builder" (1st stage) part of the
[web-static-pack](https://github.com/peku33/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](https://crates.io/crates/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
| | <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](https://crates.io/crates/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:
```rust
// 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