From 0c6c4a190c5dad3a8d17e43c6e773e9cbd9dd14d Mon Sep 17 00:00:00 2001 From: Jacob Hrbek Date: Mon, 29 Aug 2022 09:44:00 +0200 Subject: [PATCH] Initial commit to the New Readme Signed-off-by: Jacob Hrbek --- README.org | 227 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 README.org diff --git a/README.org b/README.org new file mode 100644 index 0000000..238c4ca --- /dev/null +++ b/README.org @@ -0,0 +1,227 @@ +#+TITLE: The Project Manager + +ADD INTRODUCTION BANNER + +Library inspired by =make= utility in IEEE Std 1003.1-2017 (POSIX) that aims to make the task of mataintaing, updating and regeneration programs more functional while enabling you to write project management tasks and build scripts in GNU Guile! + +** Hello World! +#+BEGIN_SRC scheme-mode +#!/usr/bin/env sh +exec guile -s "$0" "$@" +!# + +(use-modules (potato make)) +(initialize) + +;; Rule that outputs a simple hello world when called +(: "hello" '() + (lambda () + (display "Hello from The Project Manager!\n"))) + +(execute) +#+END_SRC + + $ GUILE_LOAD_PATH=path/to/this/project path/to/this/project/examples/hello.scm hello + Hello from The Project Manager! + “hello”: PASS + “hello”: COMPLETE + The recipe “hello” finished successfully. + +-------- + + +** Command-Line Arguments + +This boilerplate loads the library functions and it parses the +command-line arguments. The command-line arguments are the following, + + [-hvqVeEbknB] [var=value...] [target_name...] + -h, --help + displays help + -v, --version + displays the version number of this script + -V [0,1,2,3], --verbosity=[0,1,2,3] + choose the verbosity of the output + -e, --environment + environment variables are converted to makevars + -E, --elevate-environment + environment variables are converted to makevars + and will override makevars set in the script + -b, --builtins + adds some default makevars and suffix rules + --ignore-errors [NOT IMPLEMENTED YET] + keep building even if a command fails + -k, --continue-on-error [NOT IMPLEMENTED YET] + keep building some targets even if a command fails + -n, --no-execute [NOT IMPLEMENTED YET] + print rules, but only execute rules marked as + 'always execute' + -a, --ascii + use ASCII-only output and no colors + -W, --warn [NOT IMPLEMENTED YET] + enable warning messages + + [var=value...] + set the value of makevars + [target_name...] + Set one or more targets to be executed. If no target + is specified, the first target found will be executed. + +## MAKEVARS + +A hash table called `%makevars` has string keys. These procedures +are syntax that add quotation marks around `key`, so you call them without the quotes on +`key`. The returned value of `$` is a string, or an empty string on failure. +You define makevars in the script, in the environment, or on the command line. + + ($ KEY) -> "VAL" + + ($ key [transformer]) + Look up `key` in the `%makevars` hash table and return the + result as a string. If `key` is not found, return an empty + string. If a string-to-string transformer procedure is + provided, apply it to each space-separated token in the + result. + + (?= 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. + +```scheme +(: 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 to be evaluated by the system + +```scheme +(: "foo.o" '("foo.c") + "cc -c foo.o") +``` + +Recipe as a procedure + +```scheme +(: "clean-foo" '() + (lambda () + (delete-file "foo.o"))) + +``` + +Recipe as a procedure that returns #f to indicate failure + +```scheme +(: "recent" '() + (lambda () + (if condition + #t + #f)))) +``` + +Recipe as a procedure returning a string to be evaluated by the +system + +```scheme +(: "foo.o" '("foo.c") + (lambda () + (format #f "cc ~A -c foo.c" some-flags)) +``` + +Recipe using recipe helper procedures, which create a string to +be evaluated by the system + +```scheme +(: "foo.c" '("foo.c") + (~ ($ CC) ($ CFLAGS) "-c" $<)) +``` + +Recipe as a boolean to indicate pass or failure without doing any +processing. For example, the rule below tells Potato Make that +the file "foo.c" exists without actually testing for it. + +```scheme +(: "foo.c" '() #t) +``` + +If there is no recipe at all, it is shorthand for the recipe #t, +indicating a recipe that always passes. This is used +in prerequisite-only target rules, such as below, which passes +so long as the prerequisites pass. These two rules are the same. + +```scheme +(: "all" '("foo.exe")) +(: "all" '("foo.exe") #t) +``` + +Lastly, if the recipe is #f, this target will always fail. + +```scheme +(: "fail" '() #f) +``` + +The *suffix rule* is a generic rule to convert one source file to a +target file, based on the filename extensions. + +```scheme +(-> ".c" ".o" + (~ ($ CC) ($ CFLAGS) "-c" $< "-o" $@)) +``` + +## Recipe Helpers + + Concatenate elements with `~`. `~` inserts spaces between the + elements. + + Elements can be + - strings + - procedures that return strings + - `%makevar` hash-table references + - automatic variables + - anything whose string representation as created by + (format #f "~A" ...) make sense + + Any procedures are applied lazily, when the rule is executed. + + (~ "string" (lambda () "string") ($ KEY) $@ 100 ) + + Three versions of `~` with special effects + (~- ...) ignores any errors + (~@ ...) doesn't print recipe to console + (~+ ...) runs even when `--no-execute` was chosen + +## Automatic Variables + + Recipes can contain the following automatic variables + + $@ the target + $* the target w/o a filename suffix + $< the first prerequisite + $^ the prerequisites, as a single space-separated string + $$^ the prerequisites, as a scheme list of strings + $? the prerequisites that are files newer than the target file + as a single space-separated string + $$? the prerequisites that are files newer than the target file + as a scheme list of strings + +## POSIX Makefile Parser + + Recipes can contain the following parser function + + (parse ...) reads a standard Makefile and creates + rules based on its contents.