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,
+
+    <your-script-name> [-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.