375 lines
13 KiB
Racket
375 lines
13 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual
|
|
(for-label scheme/base
|
|
scheme/contract
|
|
scheme/unit
|
|
make
|
|
make/make-unit
|
|
make/make-sig
|
|
make/collection
|
|
make/collection-sig
|
|
make/collection-unit
|
|
dynext/file-sig
|
|
compiler/sig))
|
|
|
|
@(define mzc-manual @other-manual['(lib "scribblings/mzc/mzc.scrbl")])
|
|
|
|
@title{@bold{Make}: Dependency Manager}
|
|
|
|
The @schememodname[make] library provides a Scheme version of the
|
|
standard Unix @exec{make} utility. Its syntax is intended to imitate
|
|
regular Unix make, but in Scheme.
|
|
|
|
@table-of-contents[]
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "overview"]{Overview}
|
|
|
|
@margin-note{If you want to build Scheme modules with automatic
|
|
dependency tracking, just use @exec{mzc} as described in
|
|
@|mzc-manual|.}
|
|
|
|
If you are already familiar with @exec{make}, skip to the precise
|
|
details of the @schememodname[make] library in @secref["make"]. This
|
|
section contains a brief overview of @exec{make} for everyone
|
|
else. The idea is to explain how to generate some project you have
|
|
from a collection of source files that go through several stages of
|
|
processing.
|
|
|
|
For example, let's say that you are writing some project that has
|
|
three input files (that you create and maintain) called
|
|
@filepath{a.input}, @filepath{b.input}, and
|
|
@filepath{c.input}. Further, there are two stages of processing: first
|
|
you run a particular tool @exec{make-output} that takes an input file
|
|
and produces and output file, and second you combine the input files
|
|
into a single file using @filepath{output}. Using @exec{make}, you
|
|
might write this:
|
|
|
|
@verbatim[#:indent 2]{
|
|
a.output: a.input
|
|
make-output a.input a.output
|
|
b.output: b.input
|
|
make-output b.input b.output
|
|
c.output: c.input
|
|
make-output c.input c.output
|
|
total: a.output b.output c.output
|
|
combine a.output b.output c.output
|
|
}
|
|
|
|
Once you've put those above lines in a file called
|
|
@filepath{Makefile} you can issue the command:
|
|
|
|
@commandline{make total}
|
|
|
|
that builds your entire project. The @filepath{Makefile} consists of
|
|
several lines that tell @exec{make} how to create each piece. The
|
|
first two lines say that @filepath{a.output} depends on
|
|
@filepath{a.input} and the command for making @filepath{a.output} from
|
|
@filepath{a.input} is
|
|
|
|
@commandline{make-output a.input a.output}
|
|
|
|
The point of using @exec{make} is that it looks at the file creation
|
|
dates of the various files and only re-builds what is necessary.
|
|
|
|
The @exec{make} utility builds things with shell programs. If, on the
|
|
other hand, you want to build similar things with various Scheme
|
|
programs, you can use the @schememodname[make] library.
|
|
|
|
Here's the equivalent Scheme program:
|
|
|
|
@schemeblock[
|
|
(require make)
|
|
|
|
(define (make-output in out)
|
|
....)
|
|
|
|
(define (combine-total . args)
|
|
....)
|
|
|
|
(make
|
|
(("a.output" ("a.input") (make-output "a.output" "a.input"))
|
|
("b.output" ("b.input") (make-output "b.output" "b.input"))
|
|
("c.output" ("c.input") (make-output "c.output" "c.input"))
|
|
("total" ("a.output" "b.output" "c.output")
|
|
(combine-total "a.output" "b.output" "c.output"))))
|
|
]
|
|
|
|
If you were to fill in the ellipses above with calls to
|
|
@scheme[system], you'd have the exact same thing as the original
|
|
@filepath{Makefile}. In addition, if you use @scheme[make/proc]], you
|
|
can abstract over the various make lines (for example, the
|
|
@filepath{a.output}, @filepath{b.output}, and @filepath{c.output}
|
|
lines are similar, and it would be good to write a program to generate
|
|
those lines).
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "make"]{Make from Dependencies}
|
|
|
|
@defmodule[make]
|
|
|
|
@defform[(make ((target-expr (depend-expr ...)
|
|
command-expr ...)
|
|
...)
|
|
argv-expr)]{
|
|
|
|
Expands to
|
|
|
|
@schemeblock[
|
|
(make/proc
|
|
(list (list target-expr (list depend-expr ...)
|
|
(lambda () command-expr ...)) ...)
|
|
argv-expr)
|
|
]}
|
|
|
|
@defproc[(make/proc [spec (listof
|
|
(cons/c (or/c path-string? (listof path-string?))
|
|
(cons/c (listof path-string?)
|
|
(or/c null?
|
|
(list/c (-> any))))))]
|
|
[argv (or/c string? (vectorof string?))]) void?]
|
|
|
|
Performs a make according to @scheme[spec] and using @scheme[argv] as
|
|
command-line arguments selecting one or more targets.
|
|
|
|
Each element of the @scheme[spec] list is a target. A target element
|
|
that starts with a list of strings is the same as multiple elements,
|
|
one for each string. The second element of each target is a list of
|
|
dependencies, and the third element (if any) of a target is the
|
|
optional command thunk.
|
|
|
|
To make a target, @scheme[make/proc] is first called recursively on
|
|
each of the target's dependencies. If a target is not in @scheme[spec]
|
|
and it exists as a file, then the target is considered made. If a
|
|
target's modification date is older than any of its dependencies'
|
|
modification dates, the corresponding command thunk is called. If the
|
|
dependency has no command thunk then no action is taken; such a target
|
|
is useful for triggering the make of other targets (i.e., the
|
|
dependencies).
|
|
|
|
While running a command thunk, @scheme[make/proc] catches exceptions
|
|
and wraps them in an @scheme[exn:fail:make] structure, the raises the
|
|
resulting structure.}
|
|
|
|
@defstruct[(exn:fail:make exn:fail) ([target (or/c path-string? (listof path-string?))]
|
|
[orig-exn any/c])]{
|
|
|
|
The @scheme[target] field is a list of list of strings naming the
|
|
target(s), and the @scheme[orig-exn] field is the original raised
|
|
value.}
|
|
|
|
|
|
@defboolparam[make-print-checking on?]{
|
|
|
|
A parameter that controls whether @scheme[make/proc] prints a message
|
|
when making a target. The default is @scheme[#t].}
|
|
|
|
|
|
@defboolparam[make-print-dep-no-line on?]{
|
|
|
|
A parameter that controls whether @scheme[make/proc] prints
|
|
``checking...'' lines for dependencies that have no target in the
|
|
given k@scheme[_spec]. The default is @scheme[#f].}
|
|
|
|
|
|
@defboolparam[make-print-reasons on?]{
|
|
|
|
A parameter that controls whether @scheme[make/proc] prints the reason
|
|
that a command thunk is called. The default is @scheme[#t].}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@subsection[#:tag "make-signature"]{Signature}
|
|
|
|
@defmodule[make/make-sig]
|
|
|
|
@defsignature[make^ ()]{
|
|
|
|
Includes all of the names provided by @schememodname[make].}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@subsection[#:tag "make-unit"]{Unit}
|
|
|
|
@defmodule[make/make-unit]
|
|
|
|
@defthing[make@ unit?]{
|
|
|
|
A unit that imports nothing and exports @scheme[make^].}
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "setup-extension"]{Building Native-Code Extensions}
|
|
|
|
@defmodule[make/setup-extension]
|
|
|
|
The @schememodname[make/setup-extension] library helps compile C code
|
|
via Setup PLT's ``pre-install'' phase (triggered by a
|
|
@schemeidfont{pre-install-collection} item in @filepath{info.ss}; see
|
|
also @secref[#:doc '(lib "scribblings/setup-plt/setup-plt.scrbl")
|
|
"setup-info"]).
|
|
|
|
The @scheme[pre-install] function takes a number of arguments that
|
|
describe how the C code is compiled---mainly the libraries that it
|
|
depends on. It then drives a C compiler via the
|
|
@schememodname[dynext/compile] and @schememodname[dynext/link]
|
|
functions.
|
|
|
|
Many issues can complicate C compilation, and the @scheme[pre-install]
|
|
function helps with a few:
|
|
|
|
@itemize[
|
|
|
|
@item{finding non-standard libraries and header files,}
|
|
|
|
@item{taming to some degree the differing conventions of Unix and
|
|
Windows, }
|
|
|
|
@item{setting up suitable dependencies on PLT Scheme headers, and}
|
|
|
|
@item{using a pre-compiled binary when a @filepath{precompiled}
|
|
directory is present.}
|
|
|
|
]
|
|
|
|
Many extension installers will have to sort out addition platform
|
|
issues manually, however. For example, an old @filepath{readline}
|
|
installer used to pick whether to link to @filepath{libcurses} or
|
|
@filepath{libncurses} heuristically by inspecting
|
|
@filepath{/usr/lib}. More generally, the ``last chance'' argument to
|
|
@scheme[pre-install] allows an installer to patch compiler and linker
|
|
options (see @schememodname[dynext/compile] and
|
|
@schememodname[dynext/link]) before the C code is compiled or linked.
|
|
|
|
@defproc[(pre-install
|
|
[plthome-dir path-string?]
|
|
[collection-dir path-string?]
|
|
[c-file path-string?]
|
|
[default-lib-dir path-string?]
|
|
[include-subdirs (listof path-string?)]
|
|
[find-unix-libs (listof string?)]
|
|
[find-windows-libs (listof string?)]
|
|
[unix-libs (listof string?)]
|
|
[windows-libs (listof string?)]
|
|
[extra-depends (listof path-string?)]
|
|
[last-chance-k ((-> any) . > . any)]
|
|
[3m-too? any/c #f])
|
|
void?]{
|
|
|
|
The arguments are as follows:
|
|
|
|
@itemize[
|
|
|
|
@item{@scheme[plthome-dir] --- the directory provided to a `pre-installer'
|
|
function.}
|
|
|
|
@item{@scheme[collection-dir] --- a directory to use as the current directory
|
|
while building.}
|
|
|
|
@item{@scheme[c-file] --- the name of the source file (relative to
|
|
@scheme[collection-dir]). The output file will be the same, except
|
|
with a @filepath{.c} suffix replaced with @scheme[(system-type
|
|
'so-suffix)], and the path changed to @scheme[(build-path
|
|
"compiled" "native" (system-library-subpath))].
|
|
|
|
If @scheme[(build-path "precompiled" "native"
|
|
(system-library-subpath) (path-replace-suffix c-file (system-type
|
|
'so-suffix)))] exists, then @scheme[c-file] is not used at all,
|
|
and the file in the @filepath{precompiled} directory is simply
|
|
copied.}
|
|
|
|
@item{@scheme[default-lib-dir] --- a default directory for finding
|
|
supporting libraries, often a subdirectory of
|
|
@filepath{collection-dir}. The user can supplement this path by
|
|
setting the @indexed-envvar{PLT_EXTENSION_LIB_PATHS} environment
|
|
variable, which applies to all extensions manged by
|
|
@scheme[pre-install].}
|
|
|
|
@item{@scheme[include-subdirs] --- a list of relative paths in which
|
|
@tt{#include} files will be found; the path will be determined
|
|
through a search, in case it's not in a standard place like
|
|
@filepath{/usr/include}.
|
|
|
|
For example, the list used to be @scheme['("openssl")] for the
|
|
@filepath{openssl} collection, because the source uses
|
|
@tt{#include <openssl/ssl.h>} and @tt{#include <openssl/err.h>}.}
|
|
|
|
@item{@scheme[find-unix-libs] --- like @scheme[include-subdirs], but
|
|
a list of library bases. Leave off the @filepath{lib} prefix and
|
|
any suffix (such as @filepath{.a} or @filepath{.so}). For
|
|
@filepath{openssl}, the list used to be @scheme['("ssl"
|
|
"crypto")]. Each name will essentially get a @tt{-l} prefix for
|
|
the linker command line.}
|
|
|
|
@item{@scheme[find-windows-libs] --- like @scheme[find-unix-libs],
|
|
but for Windows. The library name will be suffixed with
|
|
@filepath{.lib} and supplied directly to the linker.}
|
|
|
|
@item{@scheme[unix-libs] --- like @scheme[find-unix-libs], except
|
|
that the installer makes no attempt to find the libraries in a
|
|
non-standard place. For example, the @filepath{readline} installer
|
|
used to supply @scheme['("curses")].}
|
|
|
|
@item{@scheme[windows-libs] --- like @scheme[unix-libs], but for
|
|
Windows. For example, the @filepath{openssl} installer used to
|
|
supply @scheme['("wsock32")].}
|
|
|
|
@item{@scheme[extra-depends] --- a list of relative paths to treat as
|
|
dependencies for compiling `file.c'. Often this list will include
|
|
`file.c' with the ".c" suffix replaced by ".ss" or ".scm". For
|
|
example, the "openssl" installer supplies '("mzssl.ss") to ensure
|
|
that the stub module "mzssl.ss" is never used when the true
|
|
extension can be built.}
|
|
|
|
@item{@scheme[last-chance-k] --- a procedure of one argument, which
|
|
is a thunk. This procedure should invoke the thunk to make the
|
|
file, but it may add parameterizations before the final build. For
|
|
example, the @filepath{readline} installer used to add an
|
|
AIX-specific compile flag in this step when compiling under AIX.}
|
|
|
|
@item{@scheme[3m-too?]--- a boolean. If true, when the 3m variant is
|
|
installed, use the equivalent to @exec{mzc --xform} to transform
|
|
the source file and then compile and link for 3m. Otherwise, the
|
|
extension is built only for CGC when the CGC variant is installed.}
|
|
|
|
]}
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "collection"]{Making Collections}
|
|
|
|
@defmodule[make/collection]
|
|
|
|
@defproc[(make-collection [collection-name any/c]
|
|
[collection-files (listof path-string?)]
|
|
[argv (or/c string? (vectorof string?))])
|
|
void?]{
|
|
|
|
Builds bytecode files for each file in @scheme[collection-files],
|
|
writing each to a @filepath{compiled} subdirectory and automatically
|
|
managing dependencies. Supply @scheme['#("zo")] as @scheme[argv] to
|
|
compile all files. The @scheme[collection-name] argument is used only
|
|
for printing status information.
|
|
|
|
Compilation is performed as with @exec{mzc --make} (see
|
|
@|mzc-manual|).}
|
|
|
|
@subsection{Signature}
|
|
|
|
@defmodule[make/collection-sig]
|
|
|
|
@defsignature[make:collection^ ()]{
|
|
|
|
Provides @schemeidfont{make-collection}.}
|
|
|
|
@subsection{Unit}
|
|
|
|
@defmodule[make/collection-unit]
|
|
|
|
@defthing[make:collection@ unit?]{
|
|
|
|
Imports @scheme[make^], @scheme[dynext:file^], and @scheme[compiler^],
|
|
and exports @scheme[make:collection^].}
|