#lang scribble/doc
@(require "base.ss")

@title{@bold{Sake}: a build tool}

by  Noel Welsh  (@tt{noel at GMail})

Sake is a tool that automates building your Scheme projects.

@table-of-contents[]

@section{Introduction}

Sake is a tool that automates building your Scheme projects,
whether that involves compiling files, building PLaneT
packages, or any other task you can code in Scheme.  Sake,
like similar tools such as Make, allows dependencies between
tasks, so if, for example, you can tell Sake you run your
tests before packaging your project.  Sake will ensure all
tasks are run in the correct order, and no task is run more
than once.

There are three components you'll interact with when using
Sake: a build file, describing the tasks and actions that
make up your build process, Sake's library of actions, and
the @tt{sake} executable which will run your build file.
These are explained in the following sections.


@section{Build files}

@defmodule[(planet schematics/sake)]

A build file, by default called @filepath{build.ss}, is a
file that tells Sake the steps that make up your build
process.  Each step is called a task.  A task has a name, an
action, and dependencies on other tasks.  A task is defined
using the @scheme[define-task] form.

@defform[(define-task name (dependency ...) expr ...)]{
Defines and provides a task with the given name.  The
@scheme[dependency] evaluate to other tasks that must
successfully run before this task can be run.  The
@scheme[expr] are arbitrary Scheme code the will be run when
this task is run.}

For example, here is the @scheme[test] task from the Sake @filepath{build.ss}:

@schemeblock[
(define-task test
  (compile)
  (action:test "all-sake-tests.ss" 'all-sake-tests))
]

This creates a task called @scheme[test], which depends on
the previously defined @scheme[compile] task.  The action of
the @scheme[test] task is to run the Sake tests, using the
Sake @scheme[action:test] action.

@subsection{Writing build files}

To write a build file you must require the Sake library,
which you can require with the line @scheme[(require (planet
schematics/sake))].

By default Sake will look for a task called @scheme[default]
in your build file, so you probably want to have one of
these.

@subsection{Running build files}

@defmodule[(planet schematics/sake/sake)]

The most convenient way to run build files is with the
@tt{sake} executable described below.  If you want to run a
build file programmatically you can use the @scheme[sake] function.

@defproc[(sake [build-file-path (or/c path? string?)] [task symbol?]) any]{

Run the @scheme[task] in the build file at
@scheme[build-file-path].  Currently this will have slightly
funny behaviour, as it will attempt to run the command line
program when the file is required.  This will be fixed in a
later release.}


@section{The Sake API}

@defmodule[(planet schematics/sake)]

Although you can use arbitrary Scheme code as a task's
action there are some tasks that come up frequently enough
that they are provided by Sake.  Since Sake is very new, a
very significant contribution to Sake at this stage is to
write or suggest new actions for future versions of Sake.

@defproc[(action:test [module-path (or/c path? string?)] [binding symbol?]) #t]{

Run the tests defined in the file @scheme[module-path] that
are provided by the binding @scheme[binding].  The tests run
in the SchemeUnit text UI.  If any tests fail the action
fails, stopping execution.}

@defproc[(action:compile [module-path (or/c path? string?)]) #t]{

Compile the file specified by @scheme[module-path], and all
files it depends upon.  Note this will compile files outside
of the current directory.  It is equivalent to @tt{mzc} in
this respect.}

@defproc[(action:planet-archive [path (or/c path? string?)]) string?]{

Packages the directory given by @scheme[path] into a PLaneT
archive.  The name of the archive is derived from the
directory name.  If the directory is called @filepath{foo}
the archive will be called @filepath{foo.plt}.  The archive
name is returned by this action.}

@defproc[(action:planet-install [owner string?] [filestr (or/c path? string?)] [major natural-number/c] [minor natural-number/c]) pkg?]{

Installs (also known as file injection) the given PLaneT
archive into the local PLaneT cache.}

@defproc[(action:planet-remove [owner string?] [package string?] [major natural-number/c] [minor natural-number/c]) any]{

Removes the specified package from the PLaneT cache.}


@section{The @tt{sake} executable}

Sake installs an executable with the name @tt{sake}, which
resides in the same place as the @tt{mzscheme} and other
executables.  Running @tt{sake} with no arguments with run
the @tt{default} task in @filepath{build.ss} in the current
directory.  The build-file and task may be specified on the
command line, in that order.  If only one argument is given
it is interpreted as the task.

@index-section[]