.\"
.\"     aegis - project change supervisor
.\"     Copyright (C) 1993, 1994, 1998, 2002, 2004-2008, 2010, 2012 Peter Miller
.\"
.\"     This program is free software; you can redistribute it and/or modify
.\"     it under the terms of the GNU General Public License as published by
.\"     the Free Software Foundation; either version 3 of the License, or
.\"     (at your option) any later version.
.\"
.\"     This program is distributed in the hope that it will be useful,
.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"     GNU General Public License for more details.
.\"
.\"     You should have received a copy of the GNU General Public License
.\"     along with this program. If not, see
.\"     <http://www.gnu.org/licenses/>.
.\"
.bp
.nh 2 "Using Cake"
.LP
This section describes how to use
.I cake
as the dependency maintenance tool.
The
.I cake
package was published in the
.I comp.sources.unix
USENET newsgroup
volume 12,
around February 1988,
and is thus easily accessible from the many archives around the internet.
.PP
It does not have a search path of any form,
not even something like
.I VPATH .
It does, however, have facilities for dynamic include file
dependencies.
.nh 3 "Invoking Cake"
.LP
The
.I build_command
field of the
configuration
file is used to invoke the relevant build command.
In this case, it is set as follows
.E(
build_command =
  "cake \-f ${s Cakefile} \e
   \-DPROJECT=$p \-DCHANGE=$c \e
   \-DVERSION=$v";
.E)
.LP
This command tells
.I cake
where to find the rules.
The \f(CW${s Cakefile}\fR expands to a path into the baseline
during development
if the file is not in the change.
Look in
.I aesub (5)
for more information about command substitutions.
.LP
The rules which follow will all remove their targets before constructing
them, which qualifies them for the next entry in the
configuration
file:
.E(
link_integration_directory = true;
.E)
.LP
The links must be removed first, otherwise the baseline would
be corrupted by integration builds.
.LP
Another field to be set in this file is
.E(
development_directory_style =
{
    source_file_symlink = true;
};
.E)
which tells Aegis to maintain symbolic links between the development directory
and the baseline.
This also requires that rules remove their targets before
constructing them,
to ensure that rules do not attempt to write their results onto
the read\[hy]only versions in the baseline.
.nh 3 "The Rules File"
.LP
The file containing the rules is called
.I Cakefile
and is given to cake on the command line.
.LP
The following items are preamble to the rest of the file;
they ask Aegis for the source files of the project and change
so that cake can determine what needs to be compiled and linked.
.E(
#define project_files \e
  [[aelpf \-p PROJECT \e
    \-c CHANGE]];
#define change_files \e
  [[aelcf \-p PROJECT \e
   \-c CHANGE]];
#define source_files \e
  project_files change_files

#define CC     gcc
#define CFLAGS \-O
.E)
.LP
This example parallels the one from chapter 3,
and thus has a single executable
to be linked from all the object files
.E(
#define object_files \e
  [[sub \-i X.c %.o source_files]] \e
  [[sub \-i X.y %.o source_files]] \e
  [[sub \-i X.l %.o source_files]]
.E)
.LP
Constructing the program is straightforward
.E(
example: object_files
  rm \-f example
  CC \-o example object_files
.E)
.LP
This rule says that to construct the example program,
you need the object files determined earlier,
and them link them together.
Object files which were up to date in the baseline are used wherever possible,
but files which were out of date are constructed in the current directory
and those will be linked.
.nh 3 "The Rule for C"
.LP
Next we need to tell cake how to manage C sources.
On the surface, this is a simple rule:
.E(
%.o: %.c
  CC CFLAGS \-c %.c
.E)
paralleling that found in most makes,
however it needs to delete the target first,
and to avoid deleting the \fI.o\fP file
whenever cake thinks it is transitive.
.E(
%.o!: %.c
  rm \-f %.o
  CC CFLAGS \-c %.c
.E)
The \fI\-f\fP option to the \fIrm\fP command is because
the file does not always exist.
.LP
Unfortunately this rule omits finding the include file dependencies.
The cake package includes a program called
.I ccincl
which is used to find them.
The rule now becomes
.E(
%.o!: %.c* [[ccincl %.c]]
  rm \-f %.o
  CC CFLAGS \-c %.c
.E)
This rule is a little quirky about include files which do not yet exist,
but must be constructed by some other rule.
You may want to use \fIgcc \-MM\fP instead,
which is almost as quirky when used with cake.
Another alternative, used by the author with far more success,
is to use the \fIc_incl\fP program from the \fIcook\fP package,
mentioned in an earlier section.
The \fIgcc \-MM\fP understands C include semantics perfectly,
the \fIc_incl\fP command caches its results and thus goes faster,
so you will need to figure which you most want.
.nh 4 "Include Directives"
.LP
Unlike
.I cook
described in an earlier section,
using \fIcake\fP as described here
allows you to continue using the
.E(
#include "\fIfilename\fP"
.E)
form of the include directive.
This is because the development directory appears,
to the compiler,
to be a complete copy of the baseline.
.nh 3 "The Rule for Yacc"
.LP
Having explained the complexities of the rules in the above section about C,
the rule for yacc will be given without delay:
.E(
#define YACC yacc
#define YFLAGS

%.c! %.h!: %.y  if exist %.y
  rm \-f %.c %.h y.tab.c y.tab.h
  YACC YFLAGS \-d %.y
  mv y.tab.c %.c
  mv y.tab.h %.h
.E)
.LP
This rule could be jazzed up to cope with the listing file,
too,
if that was desired,
but this is sufficient to work with the example.
.LP
Cake's ability to cope with transitive dependencies will
pick up the generated \fI.c\fP file and construct the necessary \fI.o\fP file.
.nh 3 "The Rule for Lex"
.LP
The rule for lex is vary similar to the rule for yacc.
.E(
#define LEX lex
#define LFLAGS

%.c!: %.l  if exist %.l
  rm \-f %.c
  LEX LFLAGS %.l
  mv lex.yy.c %.c
.E)
.LP
Cake's ability to cope with transitive dependencies will
pick up the generated \fI.c\fP file and construct the necessary \fI.o\fP file.
.nh 3 "Rules for Documents"
.LP
You can format documents,
such as user guides and manual entries with Aegis and cake,
and the rules are similar
to the ones above.
.E(
%.ps!: %.ms* [[soincl %.ms]]
  rm \-f %.ps
  groff \-s \-p \-t \-ms %.ms > %.ps
.E)
.LP
This rule says to run the document through groff,
with the
.I soelim (1)
and
.I pic (1)
and
.I tbl (1)
filters,
use the
.I ms (7)
macro package,
to produce PostScript output.
.LP
This suffers from many of the problems
with include files which need to be generated,
as does the C rule, above.
You may want to use \fIc_incl \-r\fP from the \fIcook\fP package,
rather than the \fIsoincl\fP supplied by the \fIcake\fP package.
.LP
Manual entries may be handled in a similar way
.E(
%.cat!: %.man* [[soincl %.man]]
  rm \-f %.cat
  groff \-Tascii \-s \-t \-man %.man \e
    > %.cat
.E)
.\" vim: set ts=8 sw=4 et :