Simple task/command runner inspired by make with declarative goals and dependencies.

The simplest way to think of this tool is to have a way to have "shortcuts" (aka goals) to some pieces of scripts. This way allows to call them easily without the need to call long shell one-liners instead.

Example Makesurefile:

@goal downloaded
@reached_if [[ -f code.tar.gz ]]
  wget http://domain/code.tar.gz
  
@goal extracted
@depends_on downloaded
  tar xzf code.tar.gz 

@goal built
@depends_on extracted
  npm install
  npm run build

@goal deployed
@depends_on built
  scp -C -r build/* user@domain:~/www

@goal default
@depends_on deployed

Now to run the whole build you just issue ./makesure command in a folder with Makesurefile (default goal will be called).

You can as well call single goal explicitly, example ./makesure built.

Also pay attention to @reached_if directive. This one allows skipping goal if it's already satisfied. This allows to speedup subsequent executions.

By default, all scripts inside goals are executed with bash. If you want to use sh just add @shell sh directive at start of the Makesurefile.

• Zero-install
• Very portable
• Very simple, only bare minimum of truly needed features. You don’t need to learn a whole new programming language to use the tool! Literally it’s goals + dependencies + handful of directives + bash/shell.
• Much saner and simpler make analog.
• A bunch of useful built-in facilities: timing the goal's execution, listing goals in a build file, a means to speed-up repeated builds.
• The syntax of a build file is also a valid bash/shell (though semantics is different). This can to some extent be in use for editing in IDE.

$ ./makesure -h
makesure ver. 0.9.24
Usage: makesure [options...] [-f buildfile] [goals...]
 -f,--file buildfile
                 set buildfile to use (default Makesurefile)
 -l,--list       list all available non-@private goals
 -la,--list-all  list all available goals
 -d,--resolved   list resolved dependencies to reach given goals
 -D "var=val",--define "var=val"
                 override @define values
 -s,--silent     silent mode - only output what goals output
 -t,--timing     display execution times for goals and total
 -x,--tracing    enable tracing in bash/sh via `set -x`
 -v,--version    print version and exit
 -h,--help       print help and exit
 -U,--selfupdate update makesure to latest version

Since makesure is a tiny utility represented by a single file, the recommended installation strategy is to keep it local to a project where it's used (this means in code repository). Not only this eliminates the need for repetitive installation for every dev on a project, but also allows using separate makesure version per project and update only as needed.

wget "https://raw.githubusercontent.com/xonixx/makesure/v0.9.24/makesure" -Omakesure && \
chmod +x makesure && echo "makesure $(./makesure -v) installed"

or

curl "https://raw.githubusercontent.com/xonixx/makesure/v0.9.24/makesure" -o makesure && \
chmod +x makesure && echo "makesure $(./makesure -v) installed"

Updates makesure executable to latest available version in-place:

./makesure -U

makesure will run on any environment with POSIX shell available. Tested and officially supported are:

• Linux
• macOS
• FreeBSD
• Windows (via Git Bash)

• Build file is a text file named Makesurefile.
• Build file uses directives.
• Build file consists of a set of goals.
• A goal is a labeled piece of shell.
• A goal can declare dependencies on other goals. During execution each referenced dependency will run only once despite the number of occurrences in dependency tree. Dependencies will run in proper sequence according to the inferred topological order. Dependency loops will be reported as error.
• Goal bodies are executed in separate shell invocations. It means, you can’t easily pass variables from one goal to another. This is done on purpose to enforce declarative style.
• By default, goals are run with bash. You can change to sh with @shell sh directive specified before all goals.
• For convenience in all shell invocations the current directory is automatically set to the one of Makesurefile. Typically, this is the root of the project. This allows using relative paths without bothering of the way the build is run.
• Goal can declare @reached_if directive (link). This allows skipping goal execution if it's already satisfied.

Only valid: in prelude (meaning before any @goal declaration).

Valid options: timing, tracing, silent

@options timing

Will measure and log each goal execution time + total time.

Example Makesurefile:

@options timing

@goal a
@depends_on b
  echo "Executing goal 'a' ..."
  sleep 1
@goal b
  echo "Executing goal 'b' ..."
  sleep 2

Running:

$ ./makesure a
  goal 'b' ...
Executing goal 'b' ...
  goal 'b' took 2.003 s
  goal 'a' ...
Executing goal 'a' ...
  goal 'a' took 1.003 s
  total time 3.006 s

Small issue exists with this option on macOS. Due to BSD's date not supporting +%N formatting option, the default precision of timings is 1 sec. To make it 1 ms precise (if this is important) just install Gawk (brew install gawk). In this case Gawk built-in gettimeofday function will be used.

@options tracing

Will trace the executed shell script. This activates set -x shell option under the hood.

@options silent

By default makesure logs the goals being executed. Use this option if this is not desired (you only need the output of your own code in goals).

Use this directive to declare global variable (visible to all goals). The variable will be declared as environment variable (via export).

Example:

@define A hello
@define B "${A} world"
@define C 'hello world'

This directive is valid in any place in Makesurefile. However, we recommend:

• place frequently changed variables (like versions) to the top of Makesurefile
• place infrequently changed variables closer to the goals/libs that use them

Variable defined with @define can be overridden with a variable passed in invocation via -D parameter.

Overall the precedence for variables resolution is (higher priority top):

• ./makesure -D VAR=1
• @define VAR 2 in Makesurefile
• VAR=3 ./makesure

The precedence priorities are designed like this on purpose, to prevent accidental override of @define VAR='value' definition in file by the environment variable with the same name. However, sometimes this is the desired behavior. In this case you can use:

@define VAR  "${VAR}"                      # using the same name, or
@define VAR1 "${ENV_VAR}"                  # using different name, or
@define VAR2 "${VAR_NAME:-default_value}"  # if need the default value when not set  

This allows to use environment variables VAR, ENV_VAR, and VAR_NAME to set the value of VAR, VAR1 and VAR2.

Please note, the parser of makesure is somewhat stricter here than shell's one:

@define HW  ${HELLO}world    # makesure won't accept  
@define HW "${HELLO}world"   # OK  

Only valid: in prelude.

Valid options: bash (default), sh

Sets the shell interpreter to be used for execution of goal bodies and @reached_if conditions.

Example:

@shell sh

@goal goal_name [ @private ]

Defines a goal. @private modifier is optional. When goal is private, it won't show in ./makesure -l. To list all goals including private use ./makesure -la.

Lines that go after this declaration line (but before next @goal declaration line) will be treated as a shell script for the body of the goal. Example:

@goal hello
  echo "Hello world" 

Having the above in Makesurefile will produce next output when ran with ./makesure hello

hello world

Indentation in goal body is optional, unlike make, so below is perfectly valid:

@goal hello
echo "Hello world" 

Invoking ./makesure without arguments will attempt to call the goal named default:

@goal default
  echo "I'm default goal"

@goal [ goal_name ] @glob <glob pattern> [ @private ]

This one is easy to illustrate with an example:

@goal process_file @glob '*.txt' 
 echo $ITEM $INDEX $TOTAL

Is equivalent to declaring three goals

@goal [email protected] @private
 echo a.txt 0 2

@goal [email protected] @private
 echo b.txt 1 2
 
@goal process_file
@depends_on [email protected]   
@depends_on [email protected]   

iff

$ ls
a.txt b.txt

For convenience, you can omit name in case of glob goal:

@goal @glob '*.txt'
 echo $ITEM $INDEX $TOTAL

as equivalent for

@goal a.txt @private
 echo a.txt 0 2

@goal b.txt @private
 echo b.txt 1 2
 
@goal '*.txt'
@depends_on a.txt 
@depends_on b.txt 

So essentially one glob goal declaration expands to multiple goal declarations based on files present in project that match the glob pattern. Shell glob expansion mechanism applies.

The useful use case here would be to represent a set of test files as a set of goals. The example could be found in the project's own build file.

Why this may be useful? Imagine in your nodejs application you have test1.js, test2.js, test3.js. Now you can use this Makesurefile

@goal @glob 'test*.js'
  echo "running test file $INDEX out of $TOTAL ..."
  node $ITEM

to be able to run each test individually (./makesure test2.js for example) and all together (./makesure 'test*.js').

In case if you need to glob the files with spaces in their names, please check the naming rules section below.

Make code easier to reuse.