9 releases
0.5.0-beta.2 | Jul 6, 2024 |
---|---|
0.1.6 | Nov 8, 2023 |
0.1.5 | Oct 12, 2022 |
0.1.4 | Sep 27, 2021 |
0.1.0 | Jul 31, 2020 |
#484 in Web programming
338 downloads per month
55KB
649 lines
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 apack
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 inxargs
style. base directory path is used as a root for building relative paths inside apack
.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
Dependencies
~11–18MB
~387K SLoC