tex/manual/BuildSystem.tex

%%____________________________________________________________________ 
%% File: BuildSystem.tex
%%____________________________________________________________________ 
%%  
%% Author: Shaun ASHBY <Shaun.Ashby@cern.ch>
%% Update: 2005-11-02 17:07:01+0100
%% Revision: $Id: BuildSystem.tex,v 1.6 2007/02/27 16:16:01 sashby Exp $ 
%%
%% Copyright: 2005 (C) Shaun ASHBY
%%
%%--------------------------------------------------------------------
\chapter{The SCRAM Build System}\label{ch:buildsystem}

The primary function of the \scram\ build system is to allow efficient,
ordered compilation of source code of different types (\eg \texttt{C},
\texttt{C++}, \texttt{FORTRAN}) into libraries, binary executables or
other build products and to make it possible to easily extend the
supported product types, as dictated by changing project requirements,
and manage external and internal dependencies between software units
in a transparent and uniform way.

\ni In previous versions of \scram, much of the build system functionality
was hard-coded in parts of the \scram\ source tree making it difficult
to make changes to adapt to changing software development patterns.
Any such change often meant a new release of \scram\ and the
subsequent delays entailed by a release sequence. In addition, the
actual algorithm for determining what build actions should be
activated for each software unit was not optimum with many
configuration documents needlessly being parsed multiple times,
greatly adding to project build times. This fundamental problem
stemmed from the fact there was never a clear separation between
parsing of configuration documents and the creation of a
\texttt{Makefile}- the two were run on the fly.  Supporting the
building a project for a new architecture, particularly where the
syntax of the \texttt{Makefile} is very different (\eg
\texttt{WIN32}), was also practically impossible within the old
design.

\ni In \scram~\scramvx, a new approach is taken by separating the
collection of build metadata from the generation of the
\texttt{Makefile} and compilation of the software units.  Metadata in
this context refers to all information needed to build all products.
This includes package-level dependency requirements and all
information needed to use external tools (\eg libraries to link
against, compilation flags, pre-processor macros, library directories,
header file locations and runtime requirements).
Having parsed all necessary project documents, and the metadata
obtained and processed as required, data elements are substituted 
into text templates to create the project \texttt{Makefile}. The data
elements include directory names, library names and names of
build targets all of which must be generated by \scram.
Of course, the text templates can be written so that the output is in
some other format than that for a \texttt{Makefile}.

\section{BuildFiles and Build System Control}

The \buildfile\ is the configuration document for the build system. For
each software unit, a \buildfile\ defines the external dependencies, the
internal dependencies (\ie the other software units that are used by
this one) and the interface. This interface supplies the product
provided by this software unit and the external/internal dependencies
required by it to any other software unit that requires it.
A software unit can be thought of as a product entity which is self-contained
and can be used either in linking to satisfy the dependencies of
a build product, or can be used to participate in some way on the
build process (for example, an executable used to process a source
file template to generate soucre files in a particular package).
Most of the time, a software unit is synonymous with a package (and
hence a shared library). 

\subsection{The Markup Syntax}
\index{\buildfile}\index{SCRAM!build files}

Differing from other configuration documents in which the document
class defines the parse type, \scram\ knows about build files only 
from their name, which must be \buildfile.xml\footnote{\textit{note the uppercase letters!}.}.
A \buildfile\ only has a significance in a project area. The 
valid tags that can be used in a \buildfile\ are listed below.
\index{\buildfile!valid basic markup tags}

\begin{description}

\item[\lbkt\texttt{use} name=\textit{"unit"}$/$\rbkt]\mbox{}\\
  Specify that there is a dependency on an external tool or a
  local/external package \texttt{unit} (\eg a library, or everything the package
  exports). External tools and packages are treated in the same way.
  The interface to \textit{unit} must be defined via the
  \lbkt\texttt{export}\rbkt\tagend{export} tag.

\item[\lbkt\texttt{export}\rbkt\tagend{export}]\mbox{}\\
  A software unit can be declared and exported to be used inside the
  project or externally by another \scram\ project using the current
  project as an external tool. The interface is defined by listing
  the libraries (this can include those corresponding to a subset of a
  subsystem) that are to be exported when the package (or subsystem)
  is used. Typically, a package will export its' library, all 
  dependencies and specific compiler flags.

\item[\lbkt\texttt{lib} name=\textit{"libname"} {[}\texttt{position}=\textit{"first"}{]}$/$\rbkt]\mbox{}\\
  Add a library to the list of libraries passed to the linker. The
  optional \texttt{position} argument will move the library to the
  front of the list of libraries as received by the linker (this
  bypasses the automatic library ordering as determined by depth-first
  sorting of the package metadata).
  
\item[\lbkt\texttt{group} name=\textit{"groupname"}$/$\rbkt]\mbox{}\\
  Specify that all dependencies defined within the group
  \textit{groupname} should be used by the current software unit.

\item[\lbkt\texttt{include\_path} path=\textit{"path"}$/$\rbkt]\mbox{}\\
  Add the path \textit{path} to the global \texttt{INCLUDE} path
  passed to the compiler. The include paths of individual
  tools/packages will be ordered according to their dependency order
  when added to the project or package \texttt{INCLUDE}.

\item[\lbkt\texttt{libtype} type=\textit{"type"}$/$\rbkt]\mbox{}\\
  Specify the type of library that should be built. 
  This option overrides the project defaults but is currently unused
  since libraries are \texttt{shared} only.

\item[\lbkt\texttt{flags} \texttt{NAME}="definition"$/$\rbkt]\mbox{}\\
  Extra compiler flags can be added either in a tool description or in
  a package. These flags will be added to the global compiler flags
  and propageted to the build product defined in the \buildfile\ where
  the declaration was made.
\end{description}

\ni There are also tags for the supported build products:
\index{\buildfile!valid product markup tags}
\begin{description}

\item[\lbkt\texttt{bin} file=\textit{"filename"} {[}name=\textit{"name"}{]}\rbkt\tagend{bin}]\mbox{}\\
  Specify an executable to build. The name of the executable can be
  changed using the optional \textit{name} argument, otherwise the
  name will be the same as \textit{filename}, less the file ending
  (typically `.cpp'). More than one file can be compiled and linked to
  make the executable. The file list can be specified like "main.cpp,
  *.cc", "*.cpp" or "main.cpp, file.cc" (\ie file globs are
  supported in a minimal way). 
  
  All dependencies are contained between the opening and closing tags:
  these dependencies are specific \textit{only} to this binary
  executable. Dependencies or other metadata listed outside the
  individual product tag will be passed to all products defined in the
  \buildfile.
  
\item[\lbkt\texttt{module} file=\textit{"filename"} {[}name=\textit{"name"}{]}\rbkt\tagend{module}]\mbox{}\\
  Specify a plug-in module to build. The name of the module can be
  changed using the optional \textit{name} argument. How the plug-in
  is defined can be customised within the project. By default (\ie
  when using initial templates provided with \scram, copied to a
  project \texttt{config} directory), a plug-in module is just a shared
  library with all dependencies fully resolved when it is loaded (in
  fact, there is not much difference between a plug-in module and a
  shared library built by default in package \texttt{src} directories).
  
\item[\lbkt\texttt{library} file=\textit{"filename"} {[}name=\textit{"name"}{]}\rbkt\tagend{library}]\mbox{}\\
  Define an additional library to build (in addition to the library
  built automatically from the contents of \texttt{src} in the parent
  package directory). This is usually used to build libraries for unit tests.

\item[\lbkt\texttt{application} file=\textit{"filename"} {[}name=\textit{"name"}{]}\rbkt\tagend{application}]\mbox{}\\
  Define an application. How one defines an application is
  project-specific: it could be that an application differs from a
  binary executable in only the compiler flags or the storage
  location when released. This product type could also be used to
  inject custom rules into the build system.

\item[\lbkt\texttt{plugin} file=\textit{"filename"} {[}name=\textit{"name"}{]}\rbkt\tagend{plugin}]\mbox{}\\
  Specify a plugin module to build. This type of product is for a
  specific kind of plugin where certain actions must be performed to
  register the plugin to a manager. Templates for this product type
  can be implemented to handle any such actions without developers
  having to remember what those actions are. Otherwise, this product
  is the same as a \texttt{module}.

\item[\lbkt\texttt{unittest} file=\textit{"filename"} {[}name=\textit{"name"}{]}\rbkt\tagend{unittest}]\mbox{}\\
  Specify a unit test executable to build. Customisations are handled
  inside the generic build templates. Otherwise, this is basically a
  \texttt{bin} product.

% Not yet advertised: <<FIXME
%\item[\lbkt\texttt{skip}\rbkt\tagend{skip}]\mbox{}\\
%  Indicate that a directory should be skipped. Comments can be entered
%  between the tags which will be printed to STDOUT during building.
%  \textit{Work in progress!!}.
%
\end{description}


\subsection{The Project BuildFile}\label{sec:projectbuildfile}
\index{\buildfile!project}

Global behaviour is controlled by the project \buildfile\ which is
located in the \texttt{config} directory in all \scram-managed
projects. This file is parsed first, before all others. The
storage areas for build products are defined in this \buildfile. More
importantly, instructions on what actions to perform throughout the
source code tree occur here using \texttt{classpath} directives.
The directives indicate which templates to apply at each directory
location based on matching the directory structure to the class path. 
There are three keywords which refer to certain levels in a directory
tree and the definitions of these are fixed. The keywords are
\texttt{Project}, which refers to the top-level source directory
(usually \texttt{src}), \texttt{SubSystem}, which refers to the
directory one level up, and \texttt{Package}, which refers to a
subdirectory of a \texttt{SubSystem}. A project is not bound to a
structure in which there are always subsystems: in fact, it is
possible to have only a package level under the project \texttt{src}
directory. The advantage to having subsystems is that it becomes
possible to group packages together according to some common task (for
example): groups can then be defined which allow several independent
packages to become a single dependency unit which can be used by other
packages or executables at link-time.

\ni Each directory which is an exact match to a keyword location will be
flagged as such and \textit{structure templates}\index{structure templates}
will be used to create the rules for compiling in these locations. 
Of course, it is possible to redefine what actions to apply at the
subsystem, package or even project level, just by supplying a different
template or overriding an action in the project class path.
For libraries and executables (in general, build products), which are 
associated to a subdirectory inside a package, \textit{product
  templates} define the build targets. 
Generated build rules for directories that do not fully match any
\texttt{classpath} will simply print a message that no action is required 
at that location (\eg for an \texttt{include} or \texttt{interface} directory).
Complex build operations can be activated by modifying the
structure templates to do specific things for specific directories.
This could be for a \texttt{Documentation} subsystem, for example,
where the source code happens to be \texttt{html} or \LaTeX\
sources, or for single packages where source code must be generated
first before normal package build actions.

\ni The syntax of the \texttt{classpath} tag is \index{\texttt{classpath}
  tag}%
\begin{tagprint}
  \lbkt\texttt{classpath}
  path="{[}\textit{pattern\_match}{]}+\textit{template\_type}/\ldots"$/$\rbkt
\end{tagprint}

\ni In the above case, the \texttt{template\_type} could be
\texttt{library}, \texttt{binary} \texttt{module} \etc. (the build
products). The template file name corresponding to the
\texttt{library} template type would be
\texttt{library\_template.tmpl} and this would be located in the
\texttt{config} directory of the project.  Note that where there are
multiple \lbkt\texttt{classpath}\rbkt tags defined, it is always the
last tag that matches the current location that will be used.
See examples in Chapter~\ref{ch:examples}.

\subsubsection{Product Storage Locations}
\index{\texttt{productstore} tag}%

The storage locations are defined using
\begin{tagprint}
  \lbkt\texttt{productstore} name=\textit{"name"} {[}type=\textit{"type"}
  swap=\textit{"t"}{]}  {[}path=\textit{"path"}{]}$/$\rbkt
\end{tagprint}

\ni The name \textit{name} is the name of the directory to be created
and the option \textit{type} can be set to \texttt{arch} so that an
architecture-dependent subdirectory for platform-specific products
will be added in the project area with the product directory
\textit{name} underneath. Without this type option the directory
\textit{name} will be created in the project area.  Using the
\textit{swap} option reverses the order of the architecture-dependent
sub-directory and the name of the storage directory. That is, setting
swap to \textit{true} or \textit{t} will create the product directory
first with an architecture-dependent sub-directory
underneath.\footnote{This is the fixed behaviour for all SCRAM
  releases prior to \scramvx.}

\ni The path \texttt{path} can be specified as the location where all
products corresponding to \textit{name} will be installed: a symbolic
link will be created in the project area which points to this
directory.

\ni When \scram\ finds a \tagstart{productstore} tag, 
a \texttt{Makefile} variable is set which can be used anywhere in a project makefile
when writing custom rules:
\begin{description}
\item[\texttt{SCRAMSTORENAME\_name}]\mbox{}\\
  The path to the storage location \texttt{name} from the project area
  directory (\eg \texttt{lib} or \texttt{lib/slc3\_ia32\_gcc323}).
\end{description}

\ni This could be used, for example, where there may be a default rule for
copying all \texttt{include} files to a single location after building
all libraries. By default, all build products are copied to their
storage areas once built.

\subsection{Local Metadata}\index{local metadata}\index{config/self}

In order to propagate metadata from the local area to the source tree
at compile time, the local settings like \texttt{INCLUDE} or library paths in the
project templates plus the runtime environment, are defined in a local
file called \texttt{Self.xml} found in the \texttt{config} directory\footnote{Note that this is unlike \scram\ V0 where
  such settings were hard-coded in the top-level \buildfile.}.
This file behaves like a tool description file and is set up when the project
area is bootstrapped: all of the information defined within it is
automatically propagated to the whole tree.
In addition, all \texttt{scram} commands used to query tools
can also be used to inspect the local settings and changes can be made
at will with the tool set up by hand to propagate new settings.

\subsection{Defining Groups}\label{sec:defininggroups}
\index{software units!defining a group}
A group can be used by adding a a \lbkt\texttt{group}\dots\rbkt statement
giving the name of the group to be included. 

\ni A group can be defined like this

\small{
\begin{verbatim}
<define_group name="GA">
 <use name="D"/>
 <use name="zlib"/>
 <group name="XY"/>
 <Flags CPPFLAGS="-DGROUP_GA"/>
</define_group>
\end{verbatim}
}\normalsize 

\ni in a subsystem \buildfile.

\ni Note that it is not necessary to declare where the group can be
found (for example in another \scram\ project included as an
external product in the local configuration environment) since \scram\
determines this automatically. Duplicated/overridden groups will raise
a warning when \scram\ parses the \buildfile.

\section{Configuring a New Package}
\label{sec:exportingsoftwareunits}
\index{software units}
\index{software units!defining the interface to}

When a new package is added to a project, it is important that the
directory contains a \buildfile\ (note that it must be the package
directory and \textit{not} the \texttt{src} directory where the
sources are located that contains the \buildfile).
This \buildfile\ should have the following components:
\begin{description}
\item[\textbf{Declarations for all compile-time/link-time dependencies}]\mbox{}\\
  The dependencies should be deduced from the \texttt{include}
  statements in the package sources and a \lbkt\texttt{use}
  name=\textit{"unit"}$/$\rbkt should be added for each required unit
  (external/internal package or external software product) which
  provides a library needed at link-time.
\item[\textbf{Export of the dependencies and package product}]\mbox{}\\
  Every package providing a shared library should permit client software
  units to use it at compile or link time. The
  \lbkt\texttt{export}\rbkt\tagend{export} tag is used to define the
  interface to the package and contains the full list of 
  \lbkt\texttt{use} name=\textit{"unit"}$/$\rbkt statements (as required
  by the package) and a \lbkt\texttt{lib} name=\textit{"PackageName"}$/$\rbkt
  statement with the name of the library provided by the package.
\end{description}

\ni A typical package \buildfile\ will look like this:
\index{example of using \texttt{export} tag}%
\index{software units!exporting}%
\small{
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<doc type="BuildSystem::BuildFile" version="1.0">
 <export>
   <lib name="PX"/>
   <use name="S/A"/>
   <use name="B"/>
 </export>

 <use name="S/A"/>
 <use name="B"/>
</doc>
\end{verbatim}
}\normalsize
\index{defining a set of libraries for a package}
\ni Any other package or executable requiring this package would have 
a statement \lbkt\texttt{use} name=\texttt{"PX"}$/$\rbkt 
in the \buildfile\ of the package/executable, where
\texttt{"PX"} is a path to the package in the
project (and hence could actually look like \lbkt\texttt{use}
name=\texttt{"Subsystem/PX"}$/$\rbkt if the package is located in
a subsystem).

\ni External projects and external tools can be used in the same way
using the \texttt{use} statement, \ie it is not necessary to qualify
the statement with a project name as with the older \scram\ syntax.

\section{Build System Caches}
\label{sec:bscaches}
\index{Build system!caches}

Tracking changes to files in the source tree is achieved by caching
file timestamps and this is especially important for files that are
part of the project configuration. Caching is also extensively used 
to store metadata as it is read from the \buildfile s
and tool description documents and to minimise subsequent re-parsing of
build data when the dependencies of a target change.

\subsection{File Timestamp Cache}
\label{sec:bstscache}
\index{File Timestamp Cache}

Build tools like \texttt{Make} keep track of relationships between
targets and the source files or headers needed to build those targets.
When a timestamp on a source file or header changes, \texttt{Make}
knows how to rebuild the target having determined that the target is
out of date with respect to those modified files. A limitation arises
when code is retrieved from a code repository such as one based on
\texttt{CVS}.  Often, the timestamps on checked-out files are in the
past (usually the time of the commit) which implies that a target will
not be rebuilt if these files are added to the source code tree since
they will be older than the target.

\ni To cope with situations like this, \scram\ employs a cache mechanism
which stores the timestamps of the \buildfile s and the directories in
the source code tree. Note that it is not necessary to store the
timestamp of every source file since it is the change of timestamp of
the parent directory that will change when files are added or removed.
Once populated (when \scram\ first performs a build), the existing
cache will be used to determine when the status of a directory or a
file has changed. Such a change to the status can be found by using
the \texttt{stat} command and comparing information like access mode
in addition to the timestamp. Changes in timestamp provoke a rebuild
of the updated package. If a \buildfile\ changes then the package is
rebuilt automatically, otherwise \scram\ will trigger a rebuild by
modifying the timestamp of the \buildfile\ of the package where the
files were added or removed first.

\subsection{Metadata Cache}
\label{sec:bsmdcache}
\index{Metadata Cache}

The actions to be taken by the build system when compiling and the
relationships between project software units are described in
\buildfile s located in the package directories in the source
code tree and the project configuration directory. Since it is
important to discover when metadata has changed, the timestamps of all
templates and the tool cache are also monitored. Since a change in a
tool setting or a template could affect the whole project, these
changes force a reparse of all \buildfile s and a complete rebuild of
the project.

\section{Understanding the Build Templates}
\label{sec:bstemplates}
\index{Build system!buildtemplates}

Many open source and commercial software projects use \texttt{make} to manage rebuilds
of large programs or collections of programs. Each build action is
defined using a rule which describes the steps that should be executed
to build the program. The rules are written in a file called a 
\texttt{Makefile}. In very large projects, a \texttt{Makefile} can typically be
thousands of lines long and is very difficult to write
from scratch and manage manually; it is preferable to generate it
automatically using a more abstract process. Since \scram\ projects can
contain many occurrences of the same class of build object (\eg shared
libraries, executables), a complete \texttt{Makefile} can be
generated from templates which implement the rules for these different classes.
Thus, \scram\ can generate a \texttt{Makefile} for a complex project structure easily.

\subsection{What is a Template?}

A template is a file which is written in the same way as a
\texttt{Makefile} except that some parts of the rules or environment
variables are inserted at the time of generation.

%%\begin{center}
%%  \textit{More to be added here over time. Check snapshots pages!}
%%\end{center}

% An Example Rule: <<FIXME


%% Build System
%% ------------

%% The SCRAM version 1.0 build system consists of two stages. Firstly,
%% all external requirements and build actions are determined and cached
%% for every location in the project. Secondly, the processed metadata
%% (lists of libraries used, INCLUDE/LIBDIR paths and compiler flags) are
%% used by the template engine to produce Makefile fragments used by
%% gmake in the usual way. Templates can easily be adapted to support
%% both different kinds of compilations (e.g. using java) or different 
%% architectures.

%% The project data and the state of the project area are made persistent
%% so that, by checking the current state relative to the last cached
%% state, any new actions (e.g. a rebuild after a modification to a BuildFile)
%% can be affected very quickly without resorting to a traversal of the
%% entire directory tree.


%% - The Directory Cache

%% In an empty project area, the first step is to populate the directory
%% cache with the timestamp and content information for the project
%% directory tree. All timestamps and file modes are stored for parent
%% and subdirectories in the ``src'' tree. Parameters for important files 
%% used in the build system, such as templates and other files in
%% ``config'' are also recorded. The timestamps of other directories in
%% the project area (tmp and build product stores for example), are not
%% stored.
%% Once the timestamp information is stored, the cache (simply a Perl
%% object of type ``Cache::Cache'') is converted to a data structure 
%% using the CPAN module ``Data::Dumper'' and written to a file 
%% called ``.SCRAM/DirCache.db''. This is the directory cache.
%% Removing this file will result in a re-read of the directory tree and
%% repopulation of the cache on a subsequent ``scram build''. This can
%% happen intentionally via a ``scram build distclean''.


%% - The Build Metadata Cache

%% The next step is to collect the build metadata and store it in a cache
%% that is separate to the directory cache. This cache is also a Perl
%% object (the same methods are used for reading and writing caches in
%% all cache handling operations in SCRAM version 1.0) which is written
%% to a file called ``.SCRAM/ProjectCache.db''. The object is of type 
%% ``BuildSystem::BuildDataStorage''.

%% After checking that there is a project BuildFile in the config
%% directory, which is essential for obtaining the ClassPath data which
%% directs all build operations, each directory known to the directory
%% cache is scanned. Every path is assigned a ``BuildSystem::TreeItem''
%% object which is used to store all metadata required by the template
%% engine which will be used to generate a Makefile.

%% Two main actions are performed for each path:
%% ---------------------------------------------
 
%% i. if a BuildFile exists under ``path/Buildfile'', it is parsed and
%% this raw data is stored in the TreeItem object. Any groups defined in
%% the BuildFile are recorded in the build cache as a KNOWNGROUPS hash 
%% with the name of the group as the key and the path to the buildFile 
%% defining it as the value. This is required so that later the
%% KNOWNGROUPS hash can be used as a lookup table when resolving 
%% <group name=X> type tags.
%% The raw metadata is itself stored as an object of type
%% ``BuildSystem::BuildFile'' in the TreeItem.

%% ii. the path is compared to each known ClassPath (as obtained from
%% config/BuildFile) to establish what build actions should be applied
%% there. The directory is assigned the following based on a best match to a
%% ClassPath:

%% - a class, i.e. a type of template to apply (Project, SubSystem,
%% Package, Library, Binary, etc..)

%% - a classdir, the part of the path that matched the ClassPath

%% - a suffix, the part of the path that dir *not* match

%% Because package dependencies are in general stated in <use name=X>
%% tags as ``subsystem/package''and not ``src/subsystem/package'', the 
%% path is converted to a DATAPATH by removing the ``src'', or rather, 
%% by removing the start of the path that matches \$ENV{SCRAM\_SOURCEDIR}.
%% This data is stored in the TreeItem which is itself stored in the
%% build cache, accessed using the DATAPATH as the key. This provides an
%% efficient lookup table for accessing package-level metadata when
%% resolving build requirements.

%% The parent directory and subdirectories (children) are recorded in
%% each TreeItem: this allows traversal from parent to children (a
%% directory ``branch'') and when coupled with the class information, can
%% permit simple determination of proper locations for build actions
%% (i.e. the actual path where the build of a certain class should be
%% applied) and greatly facilitates updating of build data when a
%% BuildFile somewhere in the branch has been modified. Thus it is not
%% necessary to reparse all BuildFiles after an modification to only one
%% of them.


%% Updating Metadata
%% -----------------

%% At the start of a build, the directory cache is scanned and files that
%% are new or have newer timestamps are updated. Any BuildFiles that have
%% been updated are passed to the update routines of the
%% ``BuildSystem::BuildDataStorage'' object which is responsible for
%% collecting and managing the metadata.
%% The BuildFiles are re-parsed and the TreeItem for the path and any
%% subdirectories is updated. Only the BuildFiles that have been
%% modified are re-processed in this way and thus, only the relevant
%% makefile fragments, are remade. After updating, the directory cache is
%% marked as up-to-date and the build proceeds as normal.


%% From Metadata to Makefile
%% -------------------------

%% Once all metadata is available, the template engine takes over. The
%% TemplateInterface object, which is a global, handles the interfacing
%% to the templates and their plugin modules.
%% The templates know how to obtain the metadata from the collected data
%% via the methods in the plugins. The TreeItem object provides all
%% needed metadata for a particular path: once the template engine has a
%% TreeItem, it uses methods in the PluginCore object to obtain

%% - lists of libraries in link order;
%% - LIBDIR and INCLUDEDIR lists in link order;
%% - compiler flags and makefile text, correctly formatted;
%% - package dependencies


%% Using Private Plugins
%% ---------------------


%% Customizations can be provided by way of project Template plugin
%% modules. These modules are standard Perl modules, inheriting from the
%% SCRAM base plugin module class.

%% For example, to override the main PluginCore module, one could do the
%% following:

%% - Write a module called SCRAM::Plugins::MyPluginCore inheriting from 
%%   BuildSystem::Template::Plugins::PluginCore; 

%% - Add 
%%    [% USE MyPluginCore %]
   
%%   to the project templates. The build system will then have access to
%%   customized build metadata.

%% NB: Custom base class MUST be SCRAM::Plugins....


%% \section{Brief Description of the Build Process}\label{sec:buildprocess}
%% \index{description of the SCRAM build process}

%% Assuming that the build area is clean (no builds have already been
%% performed) and that all tools are correctly set up, the actions taken
%% by \scram are as follows:

%% \begin{itemize}
%% \item Initially, \scram checks the current location to test if it is a
%%   project area. If it isn't, an error message like
  
%% %%   \small{\begin{verbatim} 
%% %% SCRAM error: Unable to locate the top of local release. Exitting.
%% %% \end{verbatim}}\normalsize
      
%% \ni will appear on \texttt{STDERR}.
      
      
%%     \item Tool settings are read and a makefile stub is created which
%%       contains all relevant path information for all tools in makefile
%%       syntax. The makefile stub is called \texttt{clientmakefile} and
%%       is located in the directory \texttt{tmp} in the project area.
      
%%     \item \scram parses the project \texttt{BuildFile}, creating a
%%       corresponding makefile called \texttt{BuildFile.mk} located
%%       under \texttt{tmp/config}. The \texttt{ClassPath} settings are
%%       parsed to determine the appropriate build actions.
  
%%     \item A makefile is created according to the current directory.
%%       The makefile is located in a directory under \texttt{tmp/src}
%%       which has the same name as the current directory. This makefile
%%       will be merged with appropriate makefiles determined from the
%%       \texttt{ClassPath} and will include the makefile generated from 
%%       the project \texttt{BuildFile}. A list of subdirectories in
%%       which build actions should occur is stored in a make variable 
%%       \texttt{\$(SUBDIRS)}-- the build order of various packages is
%%       the same as the order in which the package directories appear in
%%       this variable. To view the order, type \texttt{scram b echo\_SUBDIRS}.

%%     \item Before running \texttt{gmake}, the generated makefiles are
%%       merged with \texttt{basics.mk} from the \scram sources (which
%%       also includes \texttt{toolrules.mk} which contains the rules
%%       for compiling different file types and how to create libraries,
%%       binaries or modules).

%%     \item The build runs: any extra makefile statements or compiler
%%       flags are passed directly to \texttt{gmake}. The working directory for
%%       compilation is \texttt{/tmp/\$(SCRAM\_ARCH)}. Errors and warnings
%%       are reported directly to standard output.

%%     \item The build products are moved from the working directory to
%%       the product storage areas.
      
%% \end{itemize}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "SCRAM-manual"
%%% End: 

%%____________________________________________________________________ 
%% End of BuildSystem.tex
%%____________________________________________________________________ 
%%  
Revision:	1.7
Committed:	Wed Feb 28 12:41:28 2007 UTC (18 years, 2 months ago) by sashby
Content type:	application/x-tex
Branch:	MAIN
CVS Tags:	HEAD_SM_071214, V1_1_0, v110p1, V110p6, V110p5, V110p4
Branch point for:	HEAD_BRANCH_SM_071214
Changes since 1.6:	+2 -2 lines
Log Message:	Updates to doc.