tex/manual/Examples.tex

%%____________________________________________________________________ 
%% File: Examples.tex
%%____________________________________________________________________ 
%%  
%% Author: Shaun ASHBY <Shaun.Ashby@cern.ch>
%% Update: 2005-11-02 17:08:52+0100
%% Revision: $Id: Examples.tex,v 1.5 2007/02/27 11:59:40 sashby Exp $ 
%%
%% Copyright: 2005 (C) Shaun ASHBY
%%
%%--------------------------------------------------------------------
\chapter{Examples}\label{ch:examples}

This chapter contains some useful examples of how to work with \scram.

\section{Configuring New Projects}\label{sec:configuringprojectexample}

This section covers how to create a new project using the boot
mechanism. Normally, a boot file will instruct \scram\ to download
configuration documents from a \texttt{CVS} repository. However,
sometimes this may not be possible because the appropriately
configured files may not yet be available in a repository or it is
more desirable to make a prototype locally before committing anything.

\subsection{Creating Standalone Projects}\label{sec:configuringstandaloneprojects}

First we will describe how to boot a project from copies of
configuration files based on the templates provided by
\scram. These templates can be obtained using \texttt{scram project -t}.
The \texttt{config} directory created locally contains build
templates and a global \buildfile, plus the boot and requirements
files. The boot file looks like this:
\small{
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<doc type="Configuration::BootStrapProject" version="1.0">
 <project name="TEST" version="1_0">
  <base url="file:SCRAMToolBox">
   <download url="file:/CMSconfigs" name="config/site"/>
  </base>
 
   Boot file for TEST project version 1.0.

  <config dir="config"/>
  <base url="file:config">
   <download url="file:/" name="config"/>
    <requirementsdoc name="config/requirements.xml"/>
  </base>
 </project>
</doc>
\end{verbatim}}\normalsize

\ni and the requirements document looks like this:
\small{
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<doc type="BuildSystem::Requirements" version="2.0">
 <base url="file:SCRAMToolBox">
  <include url="file:/CMS/Configuration/CMSconfiguration.xml"/>
  <select name="cxxcompiler"/>
 </base>
</doc>
\end{verbatim}}\normalsize

\ni These must now be edited to suit. Here is a recipe:

\begin{description}
\item[Decide on a project name and version:]\mbox{}\\
Edit the boot file, changing the name and version of the project as
desired. In the example, the project name is \texttt{TEST} and the
version is $1.0$.
\item[Configure a toolbox with required tools:]\mbox{}\\
In this example, we configure a completely standalone toolbox as a
directory structure containing the tool descriptions needed for the
project dependencies. There are no references to \texttt{cvs:\\} type
URLS and therefore no interaction with a CVS repository.
This allows for a very fast setup process since files are
"downloaded" from a local disk.
\end{description}

\ni Now we follow a second example in which a toolbox configuration
already exists, as prepared by the software librarian, with a
published CVS tag. The boot file looks like this:
\small{
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<doc type="Configuration::BootStrapProject" version="1.0">
 <project name="TEST" version="1_0">
  <base url="cvs://cmscvs.cern.ch/cvs_server/repositories/SCRAMToolBox
          ?auth=pserver&amp;user=anonymous&amp;passkey=AA_:yZZ3e&amp;version=CMS_145a_2">
   <download url="cvs:?module=SCRAMToolBox/CMSconfigs" name="config/site"/>
  </base>

  <config dir="config"/>
  <base url="file:config">
   <download url="file:/" name="config"/>
   <requirementsdoc name="config/requirements.xml"/>
  </base>
 </project>
</doc>
\end{verbatim}}\normalsize

\ni and the requirements document looks like this:
\small{
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<doc type="BuildSystem::Requirements" version="2.0">
 <base url="cvs://cmscvs.cern.ch/cvs_server/repositories/SCRAMToolBox
          ?auth=pserver&amp;user=anonymous&amp;passkey=AA_:yZZ3e&amp;version=CMS_145a_2">
  <include url="cvs:?module=SCRAMToolBox/CMS/Configuration/CMSconfiguration.xml"/>
  <select name="cxxcompiler"/>
 </base>
</doc>
\end{verbatim}}\normalsize

\ni The toolbox has the CVS tag \texttt{CMS\_145a\_2} which is
formatted according to local conventions but can be any valid
(existing) tag. When the project is booted, the toolbox will be
checked out from CVS but the project configuration will be taken from
a local \texttt{config} directory and copied to the final project area.


\section{BuildSystem and Configuration Tips And Tricks}

Examples of useful tips? For configuration, could mention changes to \texttt{Self}.

\paragraph{Redefining An Existing Tool}

Currently it is not possible to have multiple versions of the same
tool. Therefore, this recipe should be followed if an installed tool
should be modified, for example to redefine the libraries used or to
add an extra runtime variable definition.

\begin{itemize}
\item Create a new template using \scram, or copy the installed version
  from \texttt{.SCRAM/architecture/InstalledTools}. If you cannot see
the \texttt{InstalledTools} directory (which sometimes happens for
%% FIXME>> Should this be ``scram set'' or will ``scram setup <tool>'' work?
developer areas), type \texttt{scram setup} or copy the tool description file
from the release area for the version of the project you're using to
the project area.

\item Edit this version of the tool file.

\item Delete the installed version by running \texttt{scram tool remove <tool>}.

\item Set up the new version of the tool, giving a \texttt{file:} URL to
  point to your new tool description file.
\end{itemize}

\paragraph{Creating an executable}

How to create a binary executable. Define real binaries in a
\texttt{bin} directory in the package.

\paragraph{Creating a test executable}

How to create a test binary executable? Binaries defined in
\texttt{test} subdirectories are automatically treated as test executables
A different template for tests (relative to normal binaries) defines custom behaviour, in this
case to move the product to a \texttt{test} storage location and defining rules for executing the test. 

\paragraph{Changing the default name of a package library}

The CMSSW example. Demonstrate how to change the name of the target,
taking the path information from the standard template for the library.

\paragraph{Creating an extra shared library}

How to use the \texttt{extra\_library\_template.tmpl} template. Types of globs
to pick up source files from a stubs directory, for example.

\paragraph{How to create a debug version of something}

Adding $<$flags \texttt{CXXFLAGS}=\texttt{"-g -O0"}$/>$ to the top-level
\buildfile\ will add the debug flags to the global compiler
flags. Alternatively, adding the statement to a package \buildfile\
will produce debug symbold in that package only (likewise for
executables and modules defined in \texttt{bin} or \texttt{test} directories.

\subsection{How To Avoid Rebuilding}

Create a private "release" area from which to create
a developer area. Use your own project database by setting
\texttt{SCRAM\_USERLOOKUPDB} to a local directory in which a
\texttt{project.lookup} is added. 
To install the project on which a release will be based, change to the
project area and type \texttt{scram install}. The project should now
appear in the list of projects returned by \texttt{scram list}.

\ni A developer area can be created using \texttt{scram project NAME
  VERSION}, where the \texttt{NAME} and \texttt{VERSION} match those
in the list of projects.

\example{Defining a New Classpath}

Following the recommended project structure conventions, here is an
example of \lbkt\texttt{classpath}\rbkt settings for a project, as
defined in the top-level project \buildfile:
\index{\texttt{classpath} tag!example}

\small{
\begin{verbatim} 
 <classpath path="+Project/+SubSystem/+Package/scripts+scripts"/>
 <classpath path="+Project/Documentation+Documentation/+doc"/>
 <classpath path="+Project/+SubSystem/+Package/src+library"/>
 <classpath path="+Project/+SubSystem/+Package/bin+binary"/>
 <classpath path="+Project/+SubSystem/+Package/test+test"/>
 <classpath path="+Project/+SubSystem/+Package/data+data_install"/>
\end{verbatim}}\normalsize

\index{structure templates! and the \texttt{classpath}}
\ni These settings will associate the top-level \texttt{src}
directory with \texttt{Project\_template.tmpl} and any directory in the next
level with the template \texttt{SubSystem\_template.tmpl}. 
The level below that will be associated with \texttt{Package\_template.tmpl}.
The last elements have a pattern-matching string before the \texttt{+}
sign: only directories matching the names \texttt{src},
\texttt{test} and \texttt{bin} at the third level below
the top-level \texttt{src} directory will be mapped to the
templates \texttt{library\_template.tmpl},
\texttt{test\_template.tmpl} and
\texttt{binary\_template.tmpl} respectively.  Thus, any
source files in a directory \texttt{src} at package-level will
source the template \texttt{library\_template.tmpl} for build
rules to build a library. Likewise, binary executables will be
built from sources located in any directory called
\texttt{bin} using a template \texttt{binary\_template.tmpl}.

\example{An Example Productstore Definition} 
To create separate \texttt{include},\texttt{bin} and \texttt{lib} subdirectories, all of which are 
architecture-dependent, the following tags would be added to the project \buildfile:
\index{\texttt{productstore} tag!example}

\small{
\begin{verbatim} 
 <productstore name="include" type="arch"/>
 <productstore name="lib" type="arch"/>
 <productstore name="bin" type="arch"/>
 <productstore name="module" type="arch" swap="t"/>
\end{verbatim}}\normalsize

\ni In the above example, the storage location for modules is architecture-dependent and is
created as \texttt{module/slc3\_ia32\_gcc323} on a system with a \scram\
architecture \texttt{slc3\_ia32\_gcc323}. The other directories
(\texttt{bin}, \texttt{lib} and \texttt{include}) are created under a
directory \texttt{slc3\_ia32\_gcc323} in the project area.

\ni To store all products on a local disk in a directory independent
of the project area, use the \texttt{path} option when defining the
product store. Suppose the local directory is called
\texttt{/localscrath/u/user}- in this case, the definition for the
product stores would look like this:

\small{
\begin{verbatim} 
 <productstore name="include" type="arch" path="/localscratch/u/user"/>
 <productstore name="lib" type="arch" path="/localscratch/u/user"/>
 <productstore name="bin" type="arch" path="/localscratch/u/user"/>
 <productstore name="module" type="arch" swap="t" path="/localscratch/u/user"/>
\end{verbatim}}\normalsize

\ni The storage directories inside the project area will be links to
the locations under \texttt{/localscratch/u/user}.

\example{Example Binary BuildFile}
Here is an example of a \buildfile\ to build two binary executables,
\texttt{mySimReaderExe} and \texttt{testObserver}:

\small{
\begin{verbatim}
<use name="Sim/Reader"/>
<bin file="testSimReader.cpp" name="mySimReaderExe"/>
<bin file="testObserver.cpp"/>
\end{verbatim}}\normalsize

\ni The object files for both binaries are linked against the
library provided by the package \texttt{Sim/Reader} to produce the executables.

\example{Example Plugin BuildFile} This example will build
a shared library which is to be used as a managed plugin:

\small{
\begin{verbatim}
<library file="SimpleUtilitiesModule.cpp" name="SimpleUtilPlugin">
 <use name="Base/Utilities"/>
 <Flags SEAL_PLUGIN_NAME="SimpleUtilPlugin"/>
</library>
\end{verbatim}}\normalsize

Another example includes more than one source file in the plugin
library:

\small{
\begin{verbatim}
<library file="*.cc,BaseUtilitiesModule.cpp" name="BaseUtilPlugin">
 <use name="Base/Utilities"/>
 <Flags SEAL_PLUGIN_NAME="BaseUtilPlugin"/>
</library>
\end{verbatim}}\normalsize


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

%%____________________________________________________________________ 
%% End of Examples.tex
%%____________________________________________________________________ 
%%  
Revision:	1.6
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:	V110p6, V110p5, V110p4
Changes since 1.5:	+8 -8 lines
Log Message:	Updates to doc.
#	User	Rev	Content
1	sashby	1.1	%%____________________________________________________________________
2			%% File: Examples.tex
3			%%____________________________________________________________________
4			%%
5			%% Author: Shaun ASHBY <Shaun.Ashby@cern.ch>
6			%% Update: 2005-11-02 17:08:52+0100
7	sashby	1.6	%% Revision: $Id: Examples.tex,v 1.5 2007/02/27 11:59:40 sashby Exp $
8	sashby	1.1	%%
9			%% Copyright: 2005 (C) Shaun ASHBY
10			%%
11			%%--------------------------------------------------------------------
12			\chapter{Examples}\label{ch:examples}
13
14	sashby	1.5	This chapter contains some useful examples of how to work with \scram.
15	sashby	1.1
16			\section{Configuring New Projects}\label{sec:configuringprojectexample}
17
18	sashby	1.2	This section covers how to create a new project using the boot
19			mechanism. Normally, a boot file will instruct \scram\ to download
20			configuration documents from a \texttt{CVS} repository. However,
21			sometimes this may not be possible because the appropriately
22			configured files may not yet be available in a repository or it is
23			more desirable to make a prototype locally before committing anything.
24	sashby	1.1
25			\subsection{Creating Standalone Projects}\label{sec:configuringstandaloneprojects}
26
27	sashby	1.2	First we will describe how to boot a project from copies of
28			configuration files based on the templates provided by
29			\scram. These templates can be obtained using \texttt{scram project -t}.
30			The \texttt{config} directory created locally contains build
31			templates and a global \buildfile, plus the boot and requirements
32			files. The boot file looks like this:
33			\small{
34			\begin{verbatim}
35	sashby	1.5	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
36			<doc type="Configuration::BootStrapProject" version="1.0">
37			<project name="TEST" version="1_0">
38			<base url="file:SCRAMToolBox">
39			<download url="file:/CMSconfigs" name="config/site"/>
40			</base>
41
42			Boot file for TEST project version 1.0.
43
44			<config dir="config"/>
45			<base url="file:config">
46			<download url="file:/" name="config"/>
47	sashby	1.6	<requirementsdoc name="config/requirements.xml"/>
48	sashby	1.5	</base>
49			</project>
50			</doc>
51	sashby	1.2	\end{verbatim}}\normalsize
52
53			\ni and the requirements document looks like this:
54			\small{
55			\begin{verbatim}
56	sashby	1.5	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
57			<doc type="BuildSystem::Requirements" version="2.0">
58			<base url="file:SCRAMToolBox">
59	sashby	1.6	<include url="file:/CMS/Configuration/CMSconfiguration.xml"/>
60	sashby	1.5	<select name="cxxcompiler"/>
61			</base>
62			</doc>
63	sashby	1.2	\end{verbatim}}\normalsize
64
65	sashby	1.3	\ni These must now be edited to suit. Here is a recipe:
66	sashby	1.2
67			\begin{description}
68			\item[Decide on a project name and version:]\mbox{}\\
69			Edit the boot file, changing the name and version of the project as
70	sashby	1.3	desired. In the example, the project name is \texttt{TEST} and the
71			version is $1.0$.
72	sashby	1.2	\item[Configure a toolbox with required tools:]\mbox{}\\
73			In this example, we configure a completely standalone toolbox as a
74			directory structure containing the tool descriptions needed for the
75			project dependencies. There are no references to \texttt{cvs:\\} type
76			URLS and therefore no interaction with a CVS repository.
77			This allows for a very fast setup process since files are
78			"downloaded" from a local disk.
79	sashby	1.3	\end{description}
80	sashby	1.2
81			\ni Now we follow a second example in which a toolbox configuration
82			already exists, as prepared by the software librarian, with a
83	sashby	1.3	published CVS tag. The boot file looks like this:
84			\small{
85			\begin{verbatim}
86	sashby	1.5	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
87			<doc type="Configuration::BootStrapProject" version="1.0">
88			<project name="TEST" version="1_0">
89			<base url="cvs://cmscvs.cern.ch/cvs_server/repositories/SCRAMToolBox
90	sashby	1.6	?auth=pserver&user=anonymous&passkey=AA_:yZZ3e&version=CMS_145a_2">
91	sashby	1.5	<download url="cvs:?module=SCRAMToolBox/CMSconfigs" name="config/site"/>
92			</base>
93
94			<config dir="config"/>
95			<base url="file:config">
96			<download url="file:/" name="config"/>
97	sashby	1.6	<requirementsdoc name="config/requirements.xml"/>
98	sashby	1.5	</base>
99			</project>
100			</doc>
101	sashby	1.3	\end{verbatim}}\normalsize
102
103			\ni and the requirements document looks like this:
104			\small{
105			\begin{verbatim}
106	sashby	1.5	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
107			<doc type="BuildSystem::Requirements" version="2.0">
108			<base url="cvs://cmscvs.cern.ch/cvs_server/repositories/SCRAMToolBox
109	sashby	1.6	?auth=pserver&user=anonymous&passkey=AA_:yZZ3e&version=CMS_145a_2">
110			<include url="cvs:?module=SCRAMToolBox/CMS/Configuration/CMSconfiguration.xml"/>
111	sashby	1.5	<select name="cxxcompiler"/>
112			</base>
113			</doc>
114	sashby	1.3	\end{verbatim}}\normalsize
115
116	sashby	1.6	\ni The toolbox has the CVS tag \texttt{CMS\_145a\_2} which is
117	sashby	1.3	formatted according to local conventions but can be any valid
118			(existing) tag. When the project is booted, the toolbox will be
119			checked out from CVS but the project configuration will be taken from
120			a local \texttt{config} directory and copied to the final project area.
121	sashby	1.1
122
123			\section{BuildSystem and Configuration Tips And Tricks}
124
125			Examples of useful tips? For configuration, could mention changes to \texttt{Self}.
126
127			\paragraph{Redefining An Existing Tool}
128
129			Currently it is not possible to have multiple versions of the same
130			tool. Therefore, this recipe should be followed if an installed tool
131			should be modified, for example to redefine the libraries used or to
132			add an extra runtime variable definition.
133
134	sashby	1.3	\begin{itemize}
135			\item Create a new template using \scram, or copy the installed version
136			from \texttt{.SCRAM/architecture/InstalledTools}. If you cannot see
137	sashby	1.1	the \texttt{InstalledTools} directory (which sometimes happens for
138			%% FIXME>> Should this be ``scram set'' or will ``scram setup <tool>'' work?
139			developer areas), type \texttt{scram setup} or copy the tool description file
140			from the release area for the version of the project you're using to
141			the project area.
142
143	sashby	1.3	\item Edit this version of the tool file.
144	sashby	1.1
145	sashby	1.3	\item Delete the installed version by running \texttt{scram tool remove <tool>}.
146	sashby	1.1
147	sashby	1.3	\item Set up the new version of the tool, giving a \texttt{file:} URL to
148			point to your new tool description file.
149			\end{itemize}
150	sashby	1.1
151			\paragraph{Creating an executable}
152
153	sashby	1.3	How to create a binary executable. Define real binaries in a
154			\texttt{bin} directory in the package.
155	sashby	1.1
156			\paragraph{Creating a test executable}
157
158	sashby	1.3	How to create a test binary executable? Binaries defined in
159			\texttt{test} subdirectories are automatically treated as test executables
160			A different template for tests (relative to normal binaries) defines custom behaviour, in this
161	sashby	1.5	case to move the product to a \texttt{test} storage location and defining rules for executing the test.
162	sashby	1.1
163			\paragraph{Changing the default name of a package library}
164
165			The CMSSW example. Demonstrate how to change the name of the target,
166			taking the path information from the standard template for the library.
167
168			\paragraph{Creating an extra shared library}
169
170	sashby	1.3	How to use the \texttt{extra\_library\_template.tmpl} template. Types of globs
171	sashby	1.1	to pick up source files from a stubs directory, for example.
172
173			\paragraph{How to create a debug version of something}
174
175	sashby	1.5	Adding $<$flags \texttt{CXXFLAGS}=\texttt{"-g -O0"}$/>$ to the top-level
176			\buildfile\ will add the debug flags to the global compiler
177			flags. Alternatively, adding the statement to a package \buildfile\
178			will produce debug symbold in that package only (likewise for
179			executables and modules defined in \texttt{bin} or \texttt{test} directories.
180	sashby	1.1
181			\subsection{How To Avoid Rebuilding}
182
183	sashby	1.5	Create a private "release" area from which to create
184	sashby	1.3	a developer area. Use your own project database by setting
185			\texttt{SCRAM\_USERLOOKUPDB} to a local directory in which a
186			\texttt{project.lookup} is added.
187			To install the project on which a release will be based, change to the
188			project area and type \texttt{scram install}. The project should now
189			appear in the list of projects returned by \texttt{scram list}.
190
191			\ni A developer area can be created using \texttt{scram project NAME
192			VERSION}, where the \texttt{NAME} and \texttt{VERSION} match those
193			in the list of projects.
194	sashby	1.1
195	sashby	1.5	\example{Defining a New Classpath}
196	sashby	1.1
197	sashby	1.3	Following the recommended project structure conventions, here is an
198	sashby	1.5	example of \lbkt\texttt{classpath}\rbkt settings for a project, as
199			defined in the top-level project \buildfile:
200			\index{\texttt{classpath} tag!example}
201	sashby	1.3
202			\small{
203			\begin{verbatim}
204	sashby	1.5	<classpath path="+Project/+SubSystem/+Package/scripts+scripts"/>
205			<classpath path="+Project/Documentation+Documentation/+doc"/>
206			<classpath path="+Project/+SubSystem/+Package/src+library"/>
207			<classpath path="+Project/+SubSystem/+Package/bin+binary"/>
208			<classpath path="+Project/+SubSystem/+Package/test+test"/>
209			<classpath path="+Project/+SubSystem/+Package/data+data_install"/>
210	sashby	1.1	\end{verbatim}}\normalsize
211
212	sashby	1.5	\index{structure templates! and the \texttt{classpath}}
213	sashby	1.1	\ni These settings will associate the top-level \texttt{src}
214			directory with \texttt{Project\_template.tmpl} and any directory in the next
215			level with the template \texttt{SubSystem\_template.tmpl}.
216			The level below that will be associated with \texttt{Package\_template.tmpl}.
217			The last elements have a pattern-matching string before the \texttt{+}
218			sign: only directories matching the names \texttt{src},
219	sashby	1.3	\texttt{test} and \texttt{bin} at the third level below
220	sashby	1.1	the top-level \texttt{src} directory will be mapped to the
221			templates \texttt{library\_template.tmpl},
222	sashby	1.3	\texttt{test\_template.tmpl} and
223			\texttt{binary\_template.tmpl} respectively. Thus, any
224	sashby	1.1	source files in a directory \texttt{src} at package-level will
225			source the template \texttt{library\_template.tmpl} for build
226	sashby	1.3	rules to build a library. Likewise, binary executables will be
227	sashby	1.1	built from sources located in any directory called
228	sashby	1.3	\texttt{bin} using a template \texttt{binary\_template.tmpl}.
229	sashby	1.1
230	sashby	1.5	\example{An Example Productstore Definition}
231	sashby	1.3	To create separate \texttt{include},\texttt{bin} and \texttt{lib} subdirectories, all of which are
232	sashby	1.5	architecture-dependent, the following tags would be added to the project \buildfile:
233			\index{\texttt{productstore} tag!example}
234	sashby	1.3
235			\small{
236			\begin{verbatim}
237	sashby	1.5	<productstore name="include" type="arch"/>
238			<productstore name="lib" type="arch"/>
239			<productstore name="bin" type="arch"/>
240			<productstore name="module" type="arch" swap="t"/>
241	sashby	1.3	\end{verbatim}}\normalsize
242	sashby	1.1
243			\ni In the above example, the storage location for modules is architecture-dependent and is
244	sashby	1.3	created as \texttt{module/slc3\_ia32\_gcc323} on a system with a \scram\
245			architecture \texttt{slc3\_ia32\_gcc323}. The other directories
246	sashby	1.1	(\texttt{bin}, \texttt{lib} and \texttt{include}) are created under a
247	sashby	1.3	directory \texttt{slc3\_ia32\_gcc323} in the project area.
248	sashby	1.1
249	sashby	1.4	\ni To store all products on a local disk in a directory independent
250			of the project area, use the \texttt{path} option when defining the
251			product store. Suppose the local directory is called
252			\texttt{/localscrath/u/user}- in this case, the definition for the
253			product stores would look like this:
254
255			\small{
256			\begin{verbatim}
257	sashby	1.5	<productstore name="include" type="arch" path="/localscratch/u/user"/>
258			<productstore name="lib" type="arch" path="/localscratch/u/user"/>
259			<productstore name="bin" type="arch" path="/localscratch/u/user"/>
260			<productstore name="module" type="arch" swap="t" path="/localscratch/u/user"/>
261	sashby	1.4	\end{verbatim}}\normalsize
262
263			\ni The storage directories inside the project area will be links to
264			the locations under \texttt{/localscratch/u/user}.
265
266	sashby	1.5	\example{Example Binary BuildFile}
267			Here is an example of a \buildfile\ to build two binary executables,
268			\texttt{mySimReaderExe} and \texttt{testObserver}:
269	sashby	1.1
270	sashby	1.3	\small{
271			\begin{verbatim}
272	sashby	1.5	<use name="Sim/Reader"/>
273			<bin file="testSimReader.cpp" name="mySimReaderExe"/>
274			<bin file="testObserver.cpp"/>
275	sashby	1.1	\end{verbatim}}\normalsize
276
277			\ni The object files for both binaries are linked against the
278	sashby	1.5	library provided by the package \texttt{Sim/Reader} to produce the executables.
279	sashby	1.1
280	sashby	1.3	\example{Example Plugin BuildFile} This example will build
281			a shared library which is to be used as a managed plugin:
282	sashby	1.1
283	sashby	1.3	\small{
284			\begin{verbatim}
285	sashby	1.5	<library file="SimpleUtilitiesModule.cpp" name="SimpleUtilPlugin">
286			<use name="Base/Utilities"/>
287			<Flags SEAL_PLUGIN_NAME="SimpleUtilPlugin"/>
288			</library>
289			\end{verbatim}}\normalsize
290
291			Another example includes more than one source file in the plugin
292			library:
293
294			\small{
295			\begin{verbatim}
296			<library file="*.cc,BaseUtilitiesModule.cpp" name="BaseUtilPlugin">
297			<use name="Base/Utilities"/>
298			<Flags SEAL_PLUGIN_NAME="BaseUtilPlugin"/>
299	sashby	1.3	</library>
300	sashby	1.1	\end{verbatim}}\normalsize
301
302
303			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
304
305			%%% Local Variables:
306			%%% mode: latex
307			%%% TeX-master: "SCRAM-manual"
308			%%% End:
309
310			%%____________________________________________________________________
311			%% End of Examples.tex
312			%%____________________________________________________________________
313			%%