Attachment 67713 Details for Bug 103921 – This update includes another chapter

This update includes another chapter

jam-guide.xml (text/plain), 9.71 KB, created by Colonel Paneek on 2005-09-05 21:16:14 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Colonel Paneek

Created: 2005-09-05 21:16:14 UTC

Size: 9.71 KB

patch

obsolete

><?xml version='1.0' encoding="UTF-8"?>
>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
><guide link="/doc/en/jam-guide.xml">
><title>Gentoo Linux Jam Guide</title>
>
><author title="Author">
>  <mail link="colp@solder.ath.cx">Colonel Paneek</mail>
></author>
>
><abstract>
>This document explains the Jam build system to a first-time user.
></abstract>
>
>
>
><license/>
>
><version>0.1</version>
><date>2005-09-04</date>
>
><chapter>
><title>Introduction</title>
><section>
><title>What is Jam?</title>
><body>
>
><p>
>Jam is a software build tool. It is an alternative the the GNU make tools. Jam was written by <uri link="http://www.perforce.com/jam/jam.html">Perforce Software</uri> and has been released as open source.
></p>
>
><p>
>Jam includes an interpreted procedural language to define the rules and actions processed by Jam. The Jam language is case sensitive.
>Jam uses these rules (from a Jamfile or a group of Jamfiles) to define how Jam should build a set of targets, which can be object files, libraries, or executables.
>
></p>
><p>
>Jam's features include automatically generating C &amp; C++ header dependencies, eliminating the necessity to declare header or object files in the Jamfile.
></p>
>
>
></body>
></section>
>
><section>
><title>Prerequisites</title>
><body>
><p>
>While no prior knowledge of Jam is assumed, a basic understanding of the C++ language and the GNU toolchain and a working knoledge of the bash shell is reccomended.
></p>
></body>
></section>
></chapter>
>
><chapter>
><title>Installing Jam</title>
><section>
><body>
><p>
>First of all Jam needs to be installed on your system.
></p>
>
><pre caption="Building Jam">
># <i>emerge dev-util/jam</i>
></pre>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Hello World</title>
><section>
><body>
>
><p>
>The next step is to create a small set of files to test the build process.
></p>
></body>
></section>
>
><section>
><title>Create the source file</title>
><body>
>
><pre caption="hello.cc">
>#include &lt;iostream&gt;
>
>using namespace std;
>
>int main (int argc, char *argv[]) {
>
>	cout &lt;&lt; "hello world" &lt;&lt; endl;
>}
></pre>
>
></body>
></section>
>
><section>
><title>Create the Jamfile</title>
><body>
>
><note>
>In a Jamfile the semicolons are tokens and must be separated by whitespace.
></note>
>
><pre caption="Jamfile">
>C++ = g++ ;
>LINK = $(C++) ;
>
>Main hello : hello.cc ;
></pre>
>
></body>
></section>
>
><section>
><title>Make, test, and remove the executable</title>
><body>
>
><pre caption="Make the executable">
>$ <i>jam</i>
>...found 11 target(s)...
>...updating 2 target(s)...
>Link hello 
>Chmod1 hello 
>...updated 2 target(s)...
></pre>
>
><pre caption="Test the executable">
>$ <i>./hello</i>
>hello world
></pre>
>
><pre caption="Remove the executable and object files.">
>$ <i>jam clean</i>
>...found 1 target(s)...
>...updating 1 target(s)...
>Clean clean 
>...updated 1 target(s)...
></pre>
>
>
><p>
>You can remove the object and executable files by typing <e>jam clean</e>.
></p>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Linking user-built object files</title>
>
><section id="mytools_h">
><title>Create the header file</title>
><body>
>
><pre caption="mytools.h">
>#ifndef _MYTOOLS_
>#define _MYTOOLS_
>
>#include &lt;string&gt;
>
>namespace std {
>
>	void whatever (string s);
>}
>
>#endif
></pre>
>
></body>
></section>
>
><section id="mytools_cc">
><title>Create the source file</title>
><body>
>
><pre caption="mytools.cc">
>#include &lt;iostream&gt;
>#include "mytools.h"
>
>using namespace std;
>
>void std::whatever (string s) {
>
>	cout &lt;&lt; "whatever [" &lt;&lt; s &lt;&lt; ']' &lt;&lt; endl;
>}
></pre>
>
></body>
></section>
>
><section id="hello_cc">
><title>Modify hello.cc</title>
><body>
>
><p>
>The new header file needs to be included, and the procedure <e>whatever</e> needs to be called by <e>main</e>.
></p>
>
><pre caption="hello.cc">
>#include &lt;iostream&gt;
>#include "mytools.h"
>
>using namespace std;
>
>int main (int argc, char *argv[]) {
>
>	cout &lt;&lt; "hello world" &lt;&lt; endl;
>	whatever ("test");
>}
></pre>
>
></body>
></section>
>
>
><section>
><title>Modify the Jamfile</title>
><body>
>
><p>
>The file <e>mytools.cc</e> needs to be added to the main dependency list.
></p>
>
><pre caption="Jamfile">
>C++ = g++ ;
>LINK = $(C++) ;
>
>Main hello : hello.cc mytools.cc ;
></pre>
>
><p>
>The executable may now be built as normal.
></p>
></body>
></section>
></chapter>
>
><chapter>
><title>Linking pre-compiled libraries</title>
>
><section>
><title>Modify the source file</title>
><body>
>
><p>
>The header file <e>math.h</e> should be included along with the other headers.
>To test the library the arctangent of 1 is calculated.
></p>
>
><pre caption="mytools.cc">
>#include &lt;iostream&gt;
>#include &lt;math.h&gt;
>#include "mytools.h"
>
>using namespace std;
>
>void whatever (string s) {
>
>	cout &lt;&lt; "whatever [" &lt;&lt; s &lt;&lt; ']' &lt;&lt; endl;
>	cout &lt;&lt; "atan (1.0) = " &lt;&lt; atan (1.0) &lt;&lt; endl;
>}
></pre>
>
></body>
></section>
>
><section>
><title>Modify the Jamfile</title>
><body>
>
><p>
>The math library <e>libm</e> needs to be added to library list.
></p>
>
><pre caption="Jamfile">
>C++ = g++ ;
>LINK = $(C++) ;
>
>LINKLIBS += -lm ;
>
>Main hello : hello.cc mytools.cc ;
></pre>
>
></body>
></section>
>
><section>
><title>Examine the build command</title>
><body>
>
><p>
>Run Jam with the <e>-an</e> flags to see how the math library is added to the build command.
></p>
>
><pre caption="Dry-run">
>$ <i>jam -an</i>
>...found 29 target(s)...
>...updating 3 target(s)...
>C++ hello.o 
>
>g++ -c -o hello.o -O   hello.cc
>
>C++ mytools.o 
>
>g++ -c -o mytools.o -O   mytools.cc
>
>Link hello 
>
>g++  -o hello  hello.o mytools.o  -lm 
>
>Chmod1 hello 
>
>chmod 711 hello
>
>...updated 3 target(s)...
></pre>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Directories</title>
>
><section>
><title>Overview</title>
><body>
>
><p>
>Two rules, <e>SubDir</e> and <e>SubInclude</e>, are used, along with shared variables, to manage subdirectories.
></p>
>
><p>
>The SubDir rule identifies the directory which contains a Jamfile. At the root of the tree containing Jamfiles there should be a <e>Jamrules</e> file, which contains any default rules for the Jamfiles.
>A side effect of the SubDir rule is that the Jamrules file is read. The Jamrules file is only ever read once, at the first occurance of the SubDir rule.
>The SubDir rule should preceed any rules which refer to the contents of the directory. 
></p>
><p>
>The SubInclude rule causes another Jamfile to be read in. 
>Typically the Jamfile in the root directory (where the Jamrules file is) will contain a SubInclude rule for each subdirectory one level down. Multiple levels of subdirectories may be managed by writing SubInclude rules for a particular directory in the Jamfile of the parent directory, rather that putting all of the SubInclude rules in the Jamfile in the root directory. 
></p>
><p>
>An environment variable should be used to define the root of the directory tree which contains Jamfiles. In this guide the variable <e>JAMR</e> is used. A Jamrules file (which contains variables shared by the individual Jamfiles) should be present in the JAMR root directory.
></p>
>
></body>
></section>
>
><section>
><title>Example</title>
><body>
>
>The environment variable may be included within the <e>.bash_profile</e> file in your home directory.
>
><pre caption="~/.bash_profile">
>export JAMR=~/jam
></pre>
>
><p>
>An example directory structure may be set up with the following commands:
></p>
>
><pre>
>$ <i>mkdir $JAMR</i>
>$ <i>cd $JAMR</i>
>$ <i>mkdir main tools</i>
></pre>
>
><p>
>The files <uri link="#mytools_h">mytools.h</uri> &amp; <uri link="#mytools_cc">mytools.cc</uri> should go into the <e>tools</e> directory.
>The file  <uri link="#hello_cc">hello.c</uri> should go into the <e>main</e> directory.
></p>
>
><p>
>The Jamfile in the JAMR directory should be as follows:
></p>
>
><pre caption="Jamfile">
>SubDir JAMR ;
>SubInclude JAMR tools ;
>SubInclude JAMR main ;
></pre>
>
><p>
>The Jamrules file belongs in the JAMR directory. Here are the rules for variables which are commonly referenced by the individual Jamfiles.
>The Jam language assigns values to strings in a fashion similar to that of the bash shell. Here the string variable <e>TOOLS</e> is set to the path of the tools subdirectory.
></p>
><pre caption="Jamrules">
>Echo "Parsing Jamrules" ;
>
>C++ = g++ ;
>LINK = $(C++) ;
>TOOLS = $(JAMR)/tools ;
></pre>
>
><p>
>The Jamfile in the tools subdirectory uses the Objects rule to specify that only the compilation of the object file is desired.
></p>
>
><pre caption="tools/Jamfile">
>SubDir JAMR tools ;
>
>Objects mytools.cc ;
></pre>
>
><p>
>The Jamfile in the main directory refers to the tools directory for a dependecy.
>The HDRS variable is a list of directories that the compiler will search for header files, and must include the tools subdirectory in this case.
></p>
>
><pre caption="main/Jamfile">
>SubDir JAMR main ;
>
>HDRS += $(TOOLS) ;
>
>Main hello : hello.cc $(TOOLS)/mytools.cc ;
></pre>
>
></body>
></section>
></chapter>
><chapter>
><title>Other languages</title>
>
><section>
><title>Overview</title>
><body>
><p>
>Jam is not exclusively for C and C++ programs. It can be used to build executables for any language, so long as the appropriate rules and actions are defined.
></p>
></body>
></section>
><section>
><title>Example</title>
><body>
>
><p>This new rule defines build dependencies and ensures that the output file will be removed when <e>jam clean</e> is invoked.
></p>
>
><pre caption="Rules">
>rule MakeHtml {
>
>	Depends $(&lt;) : $(&gt;) ;
>	Depends all : $(&lt;) ;
>	Clean clean : $(&lt;) ;
>}
></pre>
>
><p>
>The action has reduced whitespace so that the build command appears in Jam's output the same way as Jam's built-in build commands do.
></p>
>
><pre caption="Action">
>actions MakeHtml {
>xsltproc --novalid demo.xsl $(&gt;) >$(&lt;) ;
>}
></pre>
>
><p>
>A rule that references the dependencies must be invoked before Jam will
>attempt to build anything.
></p>
>
><pre caption="Invocation">
>MakeHtml demo.html : demo.xml ;
></pre>
>
></body>
></section>
></chapter>
></guide>
>

Actions: View

Attachments on bug 103921: 66974 | 67713