https://github.com/cryptocode/stitch
Append resources to your executables
https://github.com/cryptocode/stitch
zig zig-library zig-package
Last synced: 11 months ago
JSON representation
Append resources to your executables
- Host: GitHub
- URL: https://github.com/cryptocode/stitch
- Owner: cryptocode
- License: mit
- Created: 2023-03-26T17:04:23.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-04T11:13:38.000Z (12 months ago)
- Last Synced: 2025-04-09T22:53:23.889Z (11 months ago)
- Topics: zig, zig-library, zig-package
- Language: Zig
- Homepage:
- Size: 34.2 KB
- Stars: 10
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Stitch is a tool and library for Zig and C for adding and retrieving resources to and from executables.
Why not just use `@embedFile` / `#embed`? Stitch serves a different purpose, namely to let build systems, and *users* of your software, create self-contained executables.
For example, instead of requiring users to install an interpreter and execute `mylisp fib.lisp`, they can simply run `./fib` or `fib.exe`
Resoures can be anything, such as scripts, images, text, templates config files and other executables.
## Some use cases
* Self extracting tools, like an installer
* Create executables for scripts written in your interpreted programming language
* Include a sample config file, which is extracted on first run. The user can then edit this.
* An image in your own format that's able to display itself when executed
## Building the project
To build with Zig 0.13, use the `zig-` tag/release.
To build with Zig 0.14 or master, use the main branch (last tested with Zig version `0.14.0-dev.3470+711b0fef5`)
`zig build` will put a `bin` and `lib` directory in your output folder (e.g. zig-out)
* bin/stitch is a standalone tool for attaching resources to executables. This can also be done programmatically using the library
* lib/libstitch is a library for reading attached resources from the current executable, and for adding resources to executables (like the standalone tool)
## Using the tool
This example adds two scripts to a Lisp interpreter that supports, through the stitch library, reading embedded scripts:
```bash
stitch ./mylisp std.lisp fib.lisp --output fib
./fib 8
21
```
Resources can be named explicitly
```bash
stitch ./mylisp std=std.lisp fibonacci=fib.lisp --output fib
```
If a name is not given, the filename (without path) is used. The stitch library supports finding resources by name or index.
The `--output` flag is optional. By default, resources are added to the original executable (first argument)
## Stitching programmatically
Let's say you want your interpreted programming language to support producing binaries.
An easy way to do this is to create an interpreter executable that reads scripts attached to itself using stitch.
You can provide interpreter binaries for all the OS'es you wanna support, or have the Zig build file do this if your user is building the interpreter.
In the example below, a Lisp interpreter uses the stitch library to support creating self-contained executables:
```bash
./mylisp --create-exe sql-client.lisp --output sql-client
```
The resulting binary can now be executed:
```
./sql-client
```
You can make the `mylisp` binary understand stitch attachments and then make a copy of it and stitch it with the scripts. Alternatively, you can have separate interpreter binaries specifically for reading stitched scripts.
## Using the library from C
Include the `stitch.h` header and link to the library. Here's an example, using the included C test program:
```bash
zig build-exe c-api/test/c-test.c -Lzig-out/lib -lstitch -Ic-api/include
./c-test
```
## Binary layout
The binary layout specification can be used by other tools that wants to parse files produced by Stitch, without using the Stitch library.
[Specification](spec/README.md)