diff --git a/scripts/README.md b/scripts/README.md index 6a8f165..0085c67 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -2,8 +2,38 @@ You can add custom scripts to this directory and declare them to be run at build time in the `scripts:` section of `recipe.yml`. Custom scripts can be run at either the `pre:` execution phase right after the custom repositories are added, or at the `post:` phase after all of the automatic build steps. -Your scripts will be given exactly one argument when they are executed, which specifies its precise execution phase (`pre` or `post`). The primary purpose of this argument is to streamline the reuse of scripts for multiple stages. +Your scripts will be given exactly one argument when they are executed, which specifies its precise execution phase (`pre` or `post`). The primary purpose of this argument is to streamline the reuse of scripts for multiple stages. This behaviour is mirrored both in manually declared scripts and scripts ran by `autorun.sh`. ## `autorun.sh` -`autorun.sh` is enabled by default and automatically runs all scripts in the folders `scripts/pre/` and `scripts/post/` at the correct execution phases. Manually listed scripts can be combined with `autorun.sh`. +`autorun.sh` is a script that automatically runs all scripts in the folders `scripts/pre/` and `scripts/post/` at the correct execution phases. It is enabled by default, but you can disable it by removing it from `recipe.yml`. Manually listed scripts can be combined with `autorun.sh`. + +There are a few rules, which aim to simplify your script management: + +- `autorun.sh` will only execute scripts at the FIRST level within the directory, which + means that anything stored in e.g. `scripts/pre/deeperfolder/` will NOT execute. + This is intentional, so that you can store libraries and helper scripts + within subdirectories. +- You script directories and the scripts within them can be symlinks, to allow + easy reuse of scripts. For example, if you want the same scripts to execute + during both the `pre` and `post` stages, you could simply symlink individual + scripts or the entire `pre` and `post` directories to each other. However, + remember to only use RELATIVE symlinks, to ensure that the links work + properly. For example, `ln -s ../pre/foo.sh scripts/post/foo.sh`. +- All scripts execute in a numerically and alphabetically sorted order, which + allows you to easily control the execution order of your scripts. If it's + important that they execute in a specific order, then you should give them + appropriate names. For example, `05-foo.s` would always execute before + another script named `99-bar.sh`. It's recommended to use zero-padded, + numerical prefixes when you want to specify the execution order. +- The manually listed scripts in `recipe.yml` should + be stored directly within `scripts/`, or in a custom subdirectory that + doesn't match any of the execution phases. For example, you could + set the `pre:` section of `recipe.yml` to execute both `autorun.sh` + and `fizzwidget/something.sh`, and then place a bunch of auto-executed + scripts under `scripts/pre/` for the autorunner. This makes it very simple + to reuse common scripts between multiple different `recipe.yml` files, + while also having some scripts be specific to different `recipe.yml`s. +- You can safely specify `autorun.sh` as a script in `recipe.yml`, + even if the special directories don't exist or don't contain any + scripts. It will gracefully skip the processing if there's nothing to do. diff --git a/scripts/autorun.sh b/scripts/autorun.sh index 499ed35..3b9b1c2 100644 --- a/scripts/autorun.sh +++ b/scripts/autorun.sh @@ -9,57 +9,6 @@ set -oue pipefail # This script simplifies your "recipe.yml" management whenever you simply want # to "run everything automatically" based on whatever script files exist on disk. # -# Set any or all of your "recipe.yml" script categories to "autorun.sh", and -# enjoy the magic! The autorunner will then automatically look up all ".sh" -# script files within the corresponding "scripts/