diff --git a/CHEATSHEET.md b/CHEATSHEET.md new file mode 100644 index 0000000..3024935 --- /dev/null +++ b/CHEATSHEET.md @@ -0,0 +1,106 @@ +# CHEATSHEET FOR STUDIOUS POTATO MAKE + +## Boilerplate + +Add this at the top of your build script. + + #!/usr/bin/env sh + exec guile -s "$0" "$@" + !# + + (use-modules (studious-potato)) + (initialize) + +Add this at the bottom of your build script + + (build) + +The rules go in between `initialize` and `build` + +## MAKEVARS + +A hash table called `%makevars` has string keys. + + ($ key [transformer]) + Look up `key` in the `%makevars` hash table and return the result. + If transformer is provided, apply it to each + space-separated token in the result. + ($$ key) + Returns a procedure that looks up `key` in the `%makevars` hash table. + (?= key val) + Assign `val` to `key` in the `%makevars` hash table. If `val` is a procedure, + assign its output to `key` the first time that `key` is referenced. + (:= key val) + Assign `val` to `key` in the `%makevars` hash table. If `val` is a procedure, + evaluate it and assign its output to `key` immediately. + +## RULES + +The target rule is for when the target, and the prerequisites, if any, +have filenames or phony names. + + (: target-name '(prereq-name-1 prereq-name-2 ...) + recipe-1 + recipe-2 + ...) + + `target-name` is a string which is either a filename to be created + or an phony name like "all" or "clean". + + recipe as a string + + (: "foo.o" '("foo.c") + "cc -c foo.o") + + recipe as a procedure + + (: "clean-foo" '() + (delete-file "foo.o") + + recipe as a procedure that returns #f to indicate failure + + (: "recent" '() + (if condition + #t + #f)) + + recipe as procedure returning string + + (: "foo.o" '("foo.c") + (lambda () + (format #f "cc ~A -c foo.c" some-flags)) + + recipe using recipe helper procedures + + (: "foo.c" '("foo.c") + (~ ($ CC) ($ CFLAGS) "-c" $<)) + +The suffix rule is a generic rule to convert one file type to another. +Note that the prerequisites is *not* a list. + + (-> ".c" ".o" + (~ ($ CC) ($ CFLAGS) ".c" $<)) + +# RECIPE HELPER + + Concatenate elements with `~`. `~` inserts spaces between the elements. + Elements can be + - strings, characters, or numbers + - procedures that return strings + - `makevar` hash-table references + - special variables + + (~ "string" (lambda () "string") ($ KEY) $@ ) + + Three versions of `~` with special effects + (~- ...) ignores any errors + (~@ ...) doesn't print recipe to console + (~+ ...) runs even when `--no-execute` was chosen + + Recipes can contain the following special variables + + $@ the target + $* the target w/o a filename suffix + $^ the prerequisites, as a single string + $< the first prerequisite + $? the prerequisites that are files newer than the target file