@liquid-labs/bash-rollup
v1.0.0-alpha.6
Published
Rolls up sourced/imported bash scripts into a single script.
Downloads
20
Readme
bash-rollup
Rolls up sourced/imported bash scripts into a single script.
Installation
npm i -g @liquid-labs/bash-rollup
Usage
TLDR:
bash-rollup index.sh output.sh
Command spec
bash-rollup [--help|-h] [--source-only] [--no-chmod] <source index> <out file> [<search directory 1>...n]
Command options
--no-chmod
: suppresses the "make output executable if shebang ('#!') present" behavior.--no-implicit-search
: keepsimport
from looking in the current package'ssrc
directory for target files.--no-recur
: turns off recursion; only source and import statements in the index file are processed.--source-only
: onlysource
statements are processed and import statements are passed through unprocessed into the final script.
Example
Given files:
#!/usr/bin/env bash
# file: main.sh
import strict
source lib.sh
hello-rollup
and
# file: lib.sh
hello-rollup() {
echo "Hello rollup world!"
}
Then running bash-rollup main.sh hello-rollup.sh
generates file hello-rollup.sh
:
#!/usr/bin/env bash
# file: main.sh
set -o errexit # exit on errors; set -e
set -o nounset # exit on use of uninitialized variable
set -o pipefail # exit if any part of a pipeline fails (rather than just on failure of final piece)
# file lib.sh
hello-rollup() {
echo "Hello rollup world!"
}
hello-rollup
Rollup behavior
Starting with the specified "index" bash file, bash-rollup will process source
and import
statements recursively, effectively inlining the target files as they are found. We use the terms 'include', 'included', etc. when referring to
target files included via either source
or import
and 'sourced' and 'imported' when speaking specifically about one method or the other.
Non-static source statements containing a variable are left in place. E.g. 'source "${HOME}/script.sh"' remains untouched and an informational note is emitted during processing. In instances where you can include/bundle the included script, this can be used as a workaround to force multiple inclusions of the same file until the 'always inline' flag is implemented (see below). Note that since import
is by definition a compile-time action, it is not possible to use a variable when specifying an import target.
Currently, bash-rollup will traverse symlinks by default. This will likely change before final release.
import
statements
In addition to standard bash source
statements, bash rollup supports an import
statement as well. 'import ' or 'import .' statements will search up to 3 levels deep of any explicit search paths given as optional trailing arguments to the bash-rollup invocation. This can be useful for including libraries from within the same project. './src' is implicitly included as a search directory unless the --no-implicit-search
option is specified.
More standard the NPM 'devDependencies' of the current package where bash-rollup is being executed will be searched. This allows developers to include separate library packages (like @liquid-labs/bash-toolkit). If a file matching dist/*/<name>.<type>.sh
is found, it's included. Multiple matching files will generate an error.
The 'type' convention in import target file names is generally something like 'func' or 'inline', but is not currently standardized. Import statements may specify just the name like files
or the name and content type like files.funcs
. Future versions may specify recognized types and special handling.
Differences from runtime source
bash-rollup source
statements are generally functionally equivalent to runtime
sourcing with three important caveats.
First, you must use source foo.sh
and cannot currently use the . foo.sh
convention. Or rather, if you use '. foo.sh' then it will not be processed by bash-rollup, but you should not rely on this. Use the 'bash-rollup-ignore' flag instead. The release version will support '.' inclusion.
Second, since the target file is being processed externally, and not directly by bash, it's possible to use include statements in places where you normally couldn't. Such as:
SCRIPT=$(cat <<'EOF'
source ./a-perl-script.pl # import also works!
EOF
)
The above has the effect of embedding the Perl file in the output script.
Third, the included files are tracked and will not be included multiple times. This may break the expectation of some scripts, though there is a partial workaround discussed next. The final version will support a 'always inline' flag.
Source flags
source
statements can be flagged by including a comment immediately after the source target which contains a single processing flag. E.g., source ./lib.sh # bash-rollup-no-recur
. Note, these flags don't really make sense with import
statements and therefore cannot be used with them.
- bash-rollup-ignore : will cause bash-rollup to skip processing the source and leave it as is.
- bash-rollup-no-recur : will cause the file to be included without itself being processed. This is useful for slupring in literal files that may contain
source
andimport
trigger statements.
Post-rollup processing
After processing the file, the original index file starts with a shebang (#!
),
then it assumed to be an executable and 'chmod a+x' is applied to the output file
unless the --no-chmod
flag is present.
Contributions and bounties
This project may offer bounties on some issues. Refer to Contributions and Bounties for general terms and conditions. Non-bounty contributions are also welcome. You may also refer to open, non-bountied issues and make an offer.
To use the bounty system, you must have:
- An active Venmo account.
- Correct, publicly viewable contact information in your github profile (email, twitter, etc.).
- Search for available bounty tasks in this project or all Liquid Labs bounty tasks.
- Reply to the issue requesting assignment.
- Fork the repo.
- Implement the task.
- Submit a pull request with the completed work.
- Implement any feedback.
- Once pull request is accepted and merged, you will be messaged and asked to make a request for payment via Venmo.