summaryrefslogtreecommitdiff
path: root/doc/user/simple.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
committerLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
commit72c578fd4b0b4a5a43e18594339ac4ff26c376dc (patch)
treecadaf3abe37a1066ceae933bc8fe7b75c85f56d2 /doc/user/simple.xml
parent548ed1064f327bccc6e538806740d41ea2d928a1 (diff)
Imported Upstream version 1.2.0.d20091224upstream/1.2.0.d20091224
Diffstat (limited to 'doc/user/simple.xml')
-rw-r--r--doc/user/simple.xml587
1 files changed, 587 insertions, 0 deletions
diff --git a/doc/user/simple.xml b/doc/user/simple.xml
new file mode 100644
index 0000000..598d44b
--- /dev/null
+++ b/doc/user/simple.xml
@@ -0,0 +1,587 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+ <para>
+
+ In this chapter,
+ you will see several examples of
+ very simple build configurations using &SCons;,
+ which will demonstrate how easy
+ it is to use &SCons; to
+ build programs from several different programming languages
+ on different types of systems.
+
+ </para>
+
+ <section>
+ <title>Building Simple C / C++ Programs</title>
+
+ <para>
+
+ Here's the famous "Hello, World!" program in C:
+
+ </para>
+
+ <programlisting>
+ int
+ main()
+ {
+ printf("Hello, world!\n");
+ }
+ </programlisting>
+
+ <para>
+
+ And here's how to build it using &SCons;.
+ Enter the following into a file named &SConstruct;:
+
+ </para>
+
+ <programlisting>
+ Program('hello.c')
+ </programlisting>
+
+ <para>
+
+ This minimal configuration file gives
+ &SCons; two pieces of information:
+ what you want to build
+ (an executable program),
+ and the input file from
+ which you want it built
+ (the <filename>hello.c</filename> file).
+ &b-link-Program; is a <firstterm>builder_method</firstterm>,
+ a Python call that tells &SCons; that you want to build an
+ executable program.
+
+ </para>
+
+ <para>
+
+ That's it. Now run the &scons; command to build the program.
+ On a POSIX-compliant system like Linux or UNIX,
+ you'll see something like:
+
+ </para>
+
+ <screen>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ scons: done building targets.
+ </screen>
+
+ <para>
+
+ On a Windows system with the Microsoft Visual C++ compiler,
+ you'll see something like:
+
+ </para>
+
+ <screen>
+ C:\><userinput>scons</userinput>
+ scons: Reading SConscript files ...
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cl /Fohello.obj /c hello.c /nologo
+ link /nologo /OUT:hello.exe hello.obj
+ scons: done building targets.
+ </screen>
+
+ <para>
+
+ First, notice that you only need
+ to specify the name of the source file,
+ and that &SCons; correctly deduces the names of
+ the object and executable files to be built
+ from the base of the source file name.
+
+ </para>
+
+ <para>
+
+ Second, notice that the same input &SConstruct; file,
+ without any changes,
+ generates the correct output file names on both systems:
+ <filename>hello.o</filename> and <filename>hello</filename>
+ on POSIX systems,
+ <filename>hello.obj</filename> and <filename>hello.exe</filename>
+ on Windows systems.
+ This is a simple example of how &SCons;
+ makes it extremely easy to
+ write portable software builds.
+
+ </para>
+
+ <para>
+
+ (Note that we won't provide duplicate side-by-side
+ POSIX and Windows output for all of the examples in this guide;
+ just keep in mind that, unless otherwise specified,
+ any of the examples should work equally well on both types of systems.)
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Building Object Files</title>
+
+ <para>
+
+ The &b-link-Program; builder method is only one of
+ many builder methods that &SCons; provides
+ to build different types of files.
+ Another is the &b-link-Object; builder method,
+ which tells &SCons; to build an object file
+ from the specified source file:
+
+ </para>
+
+ <programlisting>
+ Object('hello.c')
+ </programlisting>
+
+ <para>
+
+ Now when you run the &scons; command to build the program,
+ it will build just the &hello_o; object file on a POSIX system:
+
+ </para>
+
+ <screen>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -o hello.o -c hello.c
+ scons: done building targets.
+ </screen>
+
+ <para>
+
+ And just the &hello_obj; object file
+ on a Windows system (with the Microsoft Visual C++ compiler):
+
+ </para>
+
+ <screen>
+ C:\><userinput>scons</userinput>
+ scons: Reading SConscript files ...
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cl /Fohello.obj /c hello.c /nologo
+ scons: done building targets.
+ </screen>
+
+ </section>
+
+ <section>
+ <title>Simple Java Builds</title>
+
+ <para>
+
+ &SCons; also makes building with Java extremely easy.
+ Unlike the &b-link-Program; and &b-link-Object; builder methods,
+ however, the &b-link-Java; builder method
+ requires that you specify
+ the name of a destination directory in which
+ you want the class files placed,
+ followed by the source directory
+ in which the <filename>.java</filename> files live:
+
+ </para>
+
+ <programlisting>
+ Java('classes', 'src')
+ </programlisting>
+
+ <para>
+
+ If the <filename>src</filename> directory
+ contains a single <filename>hello.java</filename> file,
+ then the output from running the &scons; command
+ would look something like this
+ (on a POSIX system):
+
+ </para>
+
+ <screen>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ javac -d classes -sourcepath src src/hello.java
+ scons: done building targets.
+ </screen>
+
+ <para>
+
+ We'll cover Java builds in more detail,
+ including building Java archive (<filename>.jar</filename>)
+ and other types of file,
+ in <xref linkend="chap-java"></xref>.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Cleaning Up After a Build</title>
+
+ <para>
+
+ When using &SCons;, it is unnecessary to add special
+ commands or target names to clean up after a build.
+ Instead, you simply use the
+ <literal>-c</literal> or <literal>--clean</literal>
+ option when you invoke &SCons;,
+ and &SCons; removes the appropriate built files.
+ So if we build our example above
+ and then invoke <literal>scons -c</literal>
+ afterwards, the output on POSIX looks like:
+
+ </para>
+
+
+
+ <screen>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ scons: done building targets.
+ % <userinput>scons -c</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Cleaning targets ...
+ Removed hello.o
+ Removed hello
+ scons: done cleaning targets.
+ </screen>
+
+ <para>
+
+ And the output on Windows looks like:
+
+ </para>
+
+ <screen>
+ C:\><userinput>scons</userinput>
+ scons: Reading SConscript files ...
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cl /Fohello.obj /c hello.c /nologo
+ link /nologo /OUT:hello.exe hello.obj
+ scons: done building targets.
+ C:\><userinput>scons -c</userinput>
+ scons: Reading SConscript files ...
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ scons: done reading SConscript files.
+ scons: Cleaning targets ...
+ Removed hello.obj
+ Removed hello.exe
+ scons: done cleaning targets.
+ </screen>
+
+ <para>
+
+ Notice that &SCons; changes its output to tell you that it
+ is <literal>Cleaning targets ...</literal> and
+ <literal>done cleaning targets.</literal>
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>The &SConstruct; File</title>
+
+ <para>
+
+ If you're used to build systems like &Make;
+ you've already figured out that the &SConstruct; file
+ is the &SCons; equivalent of a &Makefile;.
+ That is, the &SConstruct; file is the input file
+ that &SCons; reads to control the build.
+
+ </para>
+
+ <section>
+ <title>&SConstruct; Files Are Python Scripts</title>
+
+ <para>
+
+ There is, however, an important difference between
+ an &SConstruct; file and a &Makefile;:
+ the &SConstruct; file is actually a Python script.
+ If you're not already familiar with Python, don't worry.
+ This User's Guide will introduce you step-by-step
+ to the relatively small amount of Python you'll
+ need to know to be able to use &SCons; effectively.
+ And Python is very easy to learn.
+
+ </para>
+
+ <para>
+
+ One aspect of using Python as the
+ scripting language is that you can put comments
+ in your &SConstruct; file using Python's commenting convention;
+ that is, everything between a '#' and the end of the line
+ will be ignored:
+
+ </para>
+
+ <programlisting>
+ # Arrange to build the "hello" program.
+ Program('hello.c') # "hello.c" is the source file.
+ </programlisting>
+
+ <para>
+
+ You'll see throughout the remainder of this Guide
+ that being able to use the power of a
+ real scripting language
+ can greatly simplify the solutions
+ to complex requirements of real-world builds.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>&SCons; Functions Are Order-Independent</title>
+
+ <para>
+
+ One important way in which the &SConstruct;
+ file is not exactly like a normal Python script,
+ and is more like a &Makefile;,
+ is that the order in which
+ the &SCons; functions are called in
+ the &SConstruct; file
+ does <emphasis>not</emphasis>
+ affect the order in which &SCons;
+ actually builds the programs and object files
+ you want it to build.<footnote>
+ <para>In programming parlance,
+ the &SConstruct; file is
+ <emphasis>declarative</emphasis>,
+ meaning you tell &SCons; what you want done
+ and let it figure out the order in which to do it,
+ rather than strictly <emphasis>imperative</emphasis>,
+ where you specify explicitly the order in
+ which to do things.
+ </para>
+ </footnote>
+ In other words, when you call the &b-link-Program; builder
+ (or any other builder method),
+ you're not telling &SCons; to build
+ the program at the instant the builder method is called.
+ Instead, you're telling &SCons; to build the program
+ that you want, for example,
+ a program built from a file named &hello_c;,
+ and it's up to &SCons; to build that program
+ (and any other files) whenever it's necessary.
+ (We'll learn more about how
+ &SCons; decides when building or rebuilding a file
+ is necessary in <xref linkend="chap-depends"></xref>, below.)
+
+ </para>
+
+ <para>
+
+ &SCons; reflects this distinction between
+ <emphasis>calling a builder method like</emphasis> &b-Program;
+ and <emphasis>actually building the program</emphasis>
+ by printing the status messages that indicate
+ when it's "just reading" the &SConstruct; file,
+ and when it's actually building the target files.
+ This is to make it clear when &SCons; is
+ executing the Python statements that make up the &SConstruct; file,
+ and when &SCons; is actually executing the
+ commands or other actions to
+ build the necessary files.
+
+ </para>
+
+ <para>
+
+ Let's clarify this with an example.
+ Python has a <literal>print</literal> statement that
+ prints a string of characters to the screen.
+ If we put <literal>print</literal> statements around
+ our calls to the &b-Program; builder method:
+
+ </para>
+
+ <programlisting>
+ print "Calling Program('hello.c')"
+ Program('hello.c')
+ print "Calling Program('goodbye.c')"
+ Program('goodbye.c')
+ print "Finished calling Program()"
+ </programlisting>
+
+ <para>
+
+ Then when we execute &SCons;,
+ we see the output from the <literal>print</literal>
+ statements in between the messages about
+ reading the &SConscript; files,
+ indicating that that is when the
+ Python statements are being executed:
+
+ </para>
+
+ <screen>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ Calling Program('hello.c')
+ Calling Program('goodbye.c')
+ Finished calling Program()
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -o goodbye.o -c goodbye.c
+ cc -o goodbye goodbye.o
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ scons: done building targets.
+ </screen>
+
+ <para>
+
+ Notice also that &SCons; built the &goodbye; program first,
+ even though the "reading &SConscript;" output
+ shows that we called <literal>Program('hello.c')</literal>
+ first in the &SConstruct; file.
+
+ </para>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Making the &SCons; Output Less Verbose</title>
+
+ <para>
+
+ You've already seen how &SCons; prints
+ some messages about what it's doing,
+ surrounding the actual commands used to build the software:
+
+ </para>
+
+ <screen>
+ C:\><userinput>scons</userinput>
+ scons: Reading SConscript files ...
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cl /Fohello.obj /c hello.c /nologo
+ link /nologo /OUT:hello.exe hello.obj
+ scons: done building targets.
+ </screen>
+
+ <para>
+
+ These messages emphasize the
+ order in which &SCons; does its work:
+ all of the configuration files
+ (generically referred to as &SConscript; files)
+ are read and executed first,
+ and only then are the target files built.
+ Among other benefits, these messages help to distinguish between
+ errors that occur while the configuration files are read,
+ and errors that occur while targets are being built.
+
+ </para>
+
+ <para>
+
+ One drawback, of course, is that these messages clutter the output.
+ Fortunately, they're easily disabled by using
+ the &Q; option when invoking &SCons;:
+
+ </para>
+
+ <screen>
+ C:\><userinput>scons -Q</userinput>
+
+ scons: warning: No installed VCs
+ File "&lt;stdin&gt;", line 67, in __call__
+
+ scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly
+ File "&lt;stdin&gt;", line 67, in __call__
+ cl /Fohello.obj /c hello.c /nologo
+ link /nologo /OUT:hello.exe hello.obj
+ </screen>
+
+ <para>
+
+ Because we want this User's Guide to focus
+ on what &SCons; is actually doing,
+ we're going to use the &Q; option
+ to remove these messages from the
+ output of all the remaining examples in this Guide.
+
+ </para>
+
+ </section>