zshbuild
A helper tool for building large ZSH projects from source
Installation
Zulu
Withzulu install zshbuild
zplug
Withzplug 'molovo/zshbuild' \
as:command, \
use:zshbuild
Manual Installation
git clone https://github.com/molovo/zshbuild
cd zshbuild
chmod u+x zshbuild
cp zshbuild /usr/local/bin
Usage
At it's simplest, zshbuild needs to be passed a file to write to (--out
) and a list of files to include as the source. zshbuild will search all files/globs passed to it, and concatenate them to the output file specified.
zshbuild --out my_app src/**/*.zsh lib/**/*.zsh
Options
zshbuild
can be passed a number of options to change the way the compiled script is built.
--out <file>
The path to the output file to be built.
zshbuild --out my_app src/**/*.zsh
--sourcemap [<file>]
When using the --sourcemap
option, zshbuild
will generate a sourcemap, mapping lines in the output executable to the correct file and line in the source. This can be used with tools like crash
to ensure the location of functions in its output are displayed with the filename/line number in the source, rather than in the output executable.
By default, the generated sourcemap will be written to <output>.map
.
# Writes sourcemap to my_app.map
zshbuild --sourcemap --out my_app src/**/*.zsh
To change the location of the sourcemap, you can pass a filename to the --sourcemap
option.
# Writes sourcemap to my_source_map
zshbuild --sourcemap my_source_map --out my_app src/**/*.zsh
--strip-blank
Strips blank lines from the compiled executable.
zshbuild --strip-blank --out my_app src/**/*.zsh
--strip-comments
Strips comments from the compiled executable.
zshbuild --strip-comments --out my_app src/**/*.zsh
--prepend <text>
Specifies text to be prepended to the start of the compiled executable
zshbuild --prepend '#!/usr/bin/env zsh' --out my_app src/**/*.zsh
--append <text>
Specifies text to be appended to the end of the compiled executable
zshbuild --append '_my_app "$@"' --out my_app src/**/*.zsh
Configuring zshbuild for your project
If your project is built with the same options each time, you can place a file called .build.yml
in the root of your project, and settings will be read from this rather than having to specify the options. Here is an example .build.yml
.
prepend: '#!/usr/bin/env zsh'
append: '_my_app \"$@\"' # Double quotes must be escaped
include:
- src/**/*.zsh
- lib/**/*.zsh
strip_comments: true
strip_blank: true
out: my_app
sourcemap: my_app.zshbuildmap
Once you have written your config file, you can build your project by running zshbuild
without any arguments. If you need to override one of the config values for a single run, you can do so by passing the corresponding option to zshbuild
.
Contributing
All contributions are welcome, and encouraged. Please read our contribution guidelines and code of conduct for more information.
License
Copyright (c) 2017 James Dinsdale hi@molovo.co (molovo.co)
zshbuild is licensed under The MIT License (MIT)