Change behavior. (require racket-makefile) and use (make <target>) instead of racket Makefile.rkt <target>

scrbl/racket-makefile.scrbl

@@ -3,7 +3,7 @@
 @(require (for-label racket/base
                      racket/file
                      (only-in racket-makefile
-                              target deps phony default-target
+                              target deps phony default-target make
                               run rm-f rm-rf cleanup
                               $target $deps $<)))
 
@@ -17,6 +17,9 @@ targets, dependencies, timestamp based rebuilding, phony targets, command
 execution, and a few cleanup helpers. The rest of the language is ordinary
 Racket.
 
+A makefile only defines targets. Loading or running the module does not execute
+any recipe automatically. Builds are started explicitly with @racket[make].
+
 @section{Installation}
 
 Install the package from a local checkout with:
@@ -28,7 +31,7 @@ raco pkg install
 For a versioned archive, specify the package name explicitly:
 
 @verbatim{
-raco pkg install --name racket-makefile racket-makefile-0.1.1.zip
+raco pkg install --name racket-makefile racket-makefile-0.1.2.zip
 }
 
 After installation a makefile can start with:
@@ -37,16 +40,74 @@ After installation a makefile can start with:
 #lang racket-makefile
 }
 
-Run a makefile with Racket:
+@section{A first makefile}
 
-@verbatim{
-racket Makefile.rkt
-racket Makefile.rkt clean
-racket Makefile.rkt clean package
+For example:
+
+@racketblock[
+(define CC 'cc)
+(define CFLAGS '(-Wall -O2))
+
+(default-target all)
+(phony all clean)
+
+(target all
+  (deps "hello"))
+
+(target "hello"
+  (deps "hello.c")
+  (run `(,CC ,@CFLAGS -o $target $<)))
+
+(target clean
+  (rm-f "hello")
+  (rm-rf "compiled")
+  (cleanup "scrbl" '("**.html" "**.js" "**.css")))
+]
+
+Loading the file only registers these targets; it does not build @tt{all} or
+any other target.
+
+@section{Executing targets}
+
+@defform[(make name ...)]{
+Builds the supplied targets. A bare identifier is always interpreted as a
+literal target name, so @racket[(make clean)] selects the target named
+@racket['clean] and does not require quoting.
+
+With no arguments, @racket[(make)] builds the target selected by
+@racket[default-target]. If no default target has been specified, the first
+declared target is used.
+
+Multiple targets are allowed and are processed in the supplied order, for
+example @racket[(make clean all)]. Dependencies that are shared by multiple
+selected targets are built only once during that @racket[make] invocation.
 }
 
-With no command-line target, @racket[default-target] is used. If no default is
-specified, the first declared target is used.
+From the command line, load the makefile with @tt{-t} and evaluate a
+@racket[make] form with @tt{-e}:
+
+@verbatim{
+racket -t Makefile.rkt -e "(make)"
+racket -t Makefile.rkt -e "(make all)"
+racket -t Makefile.rkt -e "(make clean)"
+racket -t Makefile.rkt -e "(make clean all)"
+}
+
+Loading a makefile without @tt{-e} executes no target:
+
+@verbatim{
+racket -t Makefile.rkt
+}
+
+In DrRacket, open the makefile and press @bold{Run}. This loads and registers
+the targets. Then execute targets in the Interactions window:
+
+@verbatim{
+> (make)
+> (make clean)
+> (make all)
+> (make clean all)
+}
 
 @section{Targets and dependencies}
 
@@ -77,7 +138,8 @@ when reached as a dependency.
 }
 
 @defform[(default-target name)]{
-Selects the target used when no target is supplied on the command line.
+Selects the target used by @racket[(make)] when no target is supplied. If no
+default target is specified, the first declared target is used.
 }
 
 A non-phony target is rebuilt when its output does not exist or when a
@@ -183,6 +245,9 @@ example, targets can be generated in a loop:
   (deps objects))
 ]
 
+The expression @racket[objects] evaluates to a list of dependencies. Dependency
+lists are recursively flattened by @tt{racket-makefile}.
+
 @section{Package example}
 
 The optional @hyperlink["https://docs.racket-lang.org/package-zipper/index.html"]{@tt{package-zipper}}
@@ -201,3 +266,9 @@ package combines naturally with @tt{racket-makefile}:
 (target package
   (zip-package))
 ]
+
+The package target can then be executed explicitly, for example:
+
+@verbatim{
+racket -t Makefile.rkt -e "(make package)"
+}