const SFX_HELP: &str = r#"
Compile a self-extracting executable
The request file:
source/sfx-package.zr-sfx
| [sfx]
| # executable to run, required
| run = "target/release/run"
|
| # Embedded icon for the sfx executable (Windows only)
| icon = "res/sfx.ico"
|
| # optional args for 'run'
| args = ["--foo"]
| # optional extra env for 'run'
| env = {
| FOO = "bar",
| }
|
| # rustc target triple, default is the host triple
| # rustc-target = "x86_64-pc-windows-msvc"
| # build a console exe on Windows, default is true (build a GUI exe)
| windows-subsystem = false
|
| # compression to use for 'run', default is "zstd-bcj"
| # compress = "none"
|
| # data the sfx can serve the 'run'
| [[data]]
| # name must be unique and not include ':', default is "", for single data
| name = "payload"
| # compress data on build, default is "zstd"
| compress = "zstd"
| # file to include
| file = "./data.tar"
|
| [sign]
| # optional, code sign the sfx exe
| tool = "signtool sign /v /f $PFX /tr http://timestamp.sectigo.com /td SHA256 /fd SHA256 $SIGN_TARGET"
| # only sign the sfx exe, default 'false' signs the 'run' exe too
| # sfx-only = true
Compiles and signs a 'sfx-package.exe' with custom icon on Windows, or a 'sfx-package' on Unix.
Run:
When sfx runs it extracts the 'run' executable to a temp dir and runs it.
The optional 'env' variables override the system env. The SFX_ARGS and SFX_DATA var is always set.
The SFX_ARGS is set to the sfx command line args, '\n' separated. The first arg is the path to the sfx exe.
On build, also searches for "$run.exe" if "$run" is not found and has no extension.
Data:
To read data the 'run' exe must spawn another instance of the sfx with the "SFX_GET_DATA" set
to the entry name. It will serve the data to stdout. The data may be decompressed on demand.
File Paths:
Paths are relative to the Cargo workspace root, you can also use .zr-rp to select files in the
resource target dir.
This request file:
source/sfx-package.zr-sfxf.zr-rp
| [[data]]
| file = "${ZR_TARGET_DD}/res.txt"
Compiles a 'sfx-package' that includes the 'res.txt' copied to the target dir by `cargo zng res`.
Compress:
The sfx exe includes a zstd decompressor that is used to extract the 'run' exe.
The decompressor code can be used to read data too. The 'compress' field values are:
- "none" — No compression on build. Data is served as is.
- "zstd" — Compress on build unless file extension is ".zst". Decompress on demand while reading.
- "zstd-[filter]" — Transform data to improve compression, unless file extension is ".zst". Reverses
transform on demand while reading.
Sfx is optimized for small number of large data entries. Use a container format to
package many small entries.
Filter:
Currently only BCJ (Branch/Call/Jump) filters are supported, identified by CPU instruction set:
- "zstd-bcj-[set]" where [set] is: "x86", "arm", "arm64", "arm-thumb", "ppc", "sparc", "ia64", "riscv".
- "zstd-bcj" — Select filter from 'rustc-target' arch, or zstd unfiltered for no matches.
The target file must be a binary (exe or lib) or a container (like tar) with only binary entries. The filters
are non-destructive but if the wrong filter is selected it will have negative impact on the compression level.
Signing:
Code signing must be applied to both the run exe and sfx exe, to facilitate this you can set the 'sign.tool'.
The sign-tool command will run twice, with $SIGN_TARGET set to "./run.exe" and "package.exe".
In the example above The $PFX var is an example of how to set the the private key.
Keep the private key file outside the repository and set an env var to it. In CI use
secure variables.
Icon:
On Windows the sfx executable icon can be set with 'icon' field. Note that this requires the build
to run on a Windows machine with MSVC Toolkit installed. Cross-compilation from other systems will not work.
"#;