summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorSteven Knight <knight@baldmt.com>2004-02-28 09:25:48 (GMT)
committerSteven Knight <knight@baldmt.com>2004-02-28 09:25:48 (GMT)
commitf44fa0975d10611186de5a61d8e061154e92bccc (patch)
tree40f86de321e05aa6a301b81f8b83039dcacb7d5f /doc
parent5b26639256205eabd4e055040c7529b8ec868dcf (diff)
downloadSCons-f44fa0975d10611186de5a61d8e061154e92bccc.zip
SCons-f44fa0975d10611186de5a61d8e061154e92bccc.tar.gz
SCons-f44fa0975d10611186de5a61d8e061154e92bccc.tar.bz2
Branch for User's Guide work.
Diffstat (limited to 'doc')
-rw-r--r--doc/user/builders-commands.sgml2
-rw-r--r--doc/user/builders-writing.in10
-rw-r--r--doc/user/builders-writing.sgml10
-rw-r--r--doc/user/command-line.in6
-rw-r--r--doc/user/command-line.sgml10
-rw-r--r--doc/user/depends.in12
-rw-r--r--doc/user/depends.sgml12
-rw-r--r--doc/user/environments.sgml2
-rw-r--r--doc/user/libraries.in88
-rw-r--r--doc/user/libraries.sgml80
-rw-r--r--doc/user/scanners.in2
-rw-r--r--doc/user/scanners.sgml2
-rw-r--r--doc/user/simple.in60
-rw-r--r--doc/user/simple.sgml77
14 files changed, 323 insertions, 50 deletions
diff --git a/doc/user/builders-commands.sgml b/doc/user/builders-commands.sgml
index 64c81e5..49ba08d 100644
--- a/doc/user/builders-commands.sgml
+++ b/doc/user/builders-commands.sgml
@@ -71,7 +71,7 @@
<programlisting>
env = Environment()
- env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
+ env.Command('foo.out', 'foo.in', "sed 's/x/y/' &lt; $SOURCE &gt; $TARGET")
</programlisting>
<literallayout>
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 50c9114..d68b872 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -221,7 +221,7 @@ This functionality could be invoked as in the following example:
<scons_example name="ex2">
<file name="SConstruct" printme="1">
- bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+ bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file.foo', 'file.input')
env.Program('hello.c')
@@ -409,7 +409,7 @@ This functionality could be invoked as in the following example:
the target or targets to be
built by this builder function.
The file names of these target(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
@@ -425,7 +425,7 @@ This functionality could be invoked as in the following example:
the sources to be
used by this builder function to build the targets.
The file names of these source(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
@@ -542,7 +542,7 @@ This functionality could be invoked as in the following example:
by the command or other action
generated by this function.
The file names of these source(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
@@ -560,7 +560,7 @@ This functionality could be invoked as in the following example:
by the command or other action
generated by this function.
The file names of these target(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml
index 796e199..4dddb55 100644
--- a/doc/user/builders-writing.sgml
+++ b/doc/user/builders-writing.sgml
@@ -207,7 +207,7 @@ This functionality could be invoked as in the following example:
</para>
<programlisting>
- bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+ bld = Builder(action = 'foobuild &lt; $SOURCE &gt; $TARGET')
env = Environment(BUILDERS = {'Foo' : bld})
env.Foo('file.foo', 'file.input')
env.Program('hello.c')
@@ -355,7 +355,7 @@ This functionality could be invoked as in the following example:
the target or targets to be
built by this builder function.
The file names of these target(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
@@ -371,7 +371,7 @@ This functionality could be invoked as in the following example:
the sources to be
used by this builder function to build the targets.
The file names of these source(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
@@ -484,7 +484,7 @@ This functionality could be invoked as in the following example:
by the command or other action
generated by this function.
The file names of these source(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
@@ -502,7 +502,7 @@ This functionality could be invoked as in the following example:
by the command or other action
generated by this function.
The file names of these target(s)
- may be extracted using the Python &str; funcion.
+ may be extracted using the Python &str; function.
</para>
</listitem>
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index 6f523a8..70c7ca7 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -67,9 +67,9 @@
def b(target, source, env):
pass
def s(target, source, env):
- return " ..."
+ return " ... [build output] ..."
a = Action(b, strfunction = s)
- env = Environment(BUILDERS = {'A' : a})
+ env = Environment(BUILDERS = {'A' : Builder(action=a)})
env.A('foo.out', 'foo.in')
</file>
<file name="foo.in">
@@ -80,7 +80,7 @@
<scons_output example="SCONSFLAGS">
<command>scons</command>
<command>export SCONSFLAGS="-Q"</command>
- <command>scons</command>
+ <command environment="SCONSFLAGS=-Q">scons</command>
</scons_output>
<para>
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index cf15b93..78c94e1 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -67,19 +67,13 @@
<literallayout>
% <userinput>scons</userinput>
scons: Reading SConscript files ...
- ...
scons: done reading SConscript files.
scons: Building targets ...
- scons: `.' is up to date.
+ ... [build output] ...
scons: done building targets.
% <userinput>export SCONSFLAGS="-Q"</userinput>
% <userinput>scons</userinput>
- scons: Reading SConscript files ...
- ...
- scons: done reading SConscript files.
- scons: Building targets ...
- scons: `.' is up to date.
- scons: done building targets.
+ ... [build output] ...
</literallayout>
<para>
diff --git a/doc/user/depends.in b/doc/user/depends.in
index bedc91d..43ec7f3 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -379,7 +379,7 @@ operating system on which the build is performed (as reported by C<uname
Program('hello.c', CPPPATH = '.')
</file>
<file name="hello.c" printme="1">
- #include "hello.h"
+ #include &lt;hello.h&gt;
int
main()
{
@@ -741,9 +741,8 @@ operating system on which the build is performed (as reported by C<uname
</para>
<programlisting>
- env = Environment()
- hello = env.Program('hello.c')
- env.Ignore(hello, '/usr/include/stdio.h')
+ hello = Program('hello.c')
+ Ignore(hello, '/usr/include/stdio.h')
</programlisting>
</section>
@@ -765,9 +764,8 @@ operating system on which the build is performed (as reported by C<uname
</para>
<programlisting>
- env = Environment()
- hello = env.Program('hello.c')
- env.Depends(hello, 'other_file')
+ hello = Program('hello.c')
+ Depends(hello, 'other_file')
</programlisting>
<!-- XXX mention that you can use arrays for target and source? -->
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index f595e08..09fb62d 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -386,7 +386,7 @@ operating system on which the build is performed (as reported by C<uname
</para>
<programlisting>
- #include "hello.h"
+ #include &lt;hello.h&gt;
int
main()
{
@@ -753,9 +753,8 @@ operating system on which the build is performed (as reported by C<uname
</para>
<programlisting>
- env = Environment()
- hello = env.Program('hello.c')
- env.Ignore(hello, '/usr/include/stdio.h')
+ hello = Program('hello.c')
+ Ignore(hello, '/usr/include/stdio.h')
</programlisting>
</section>
@@ -777,9 +776,8 @@ operating system on which the build is performed (as reported by C<uname
</para>
<programlisting>
- env = Environment()
- hello = env.Program('hello.c')
- env.Depends(hello, 'other_file')
+ hello = Program('hello.c')
+ Depends(hello, 'other_file')
</programlisting>
<!-- XXX mention that you can use arrays for target and source? -->
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml
index 2b4fb5d..eb9bf5b 100644
--- a/doc/user/environments.sgml
+++ b/doc/user/environments.sgml
@@ -506,7 +506,7 @@ environment undisturbed.
<literallayout>
% <userinput>scons -Q</userinput>
- scons: *** Two different environments were specified for the same target: foo.o
+ scons: *** Two environments with different actions were specified for the same target: foo.o
File "SConstruct", line 6, in ?
</literallayout>
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index a31b2b4..7a88d6f 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -46,9 +46,6 @@
<file name="SConstruct" printme="1">
Library('foo', ['f1.c', 'f2.c', 'f3.c'])
</file>
- <file name="hello.c">
- int main() { printf("Hello, world!\n"); }
- </file>
<file name="f1.c">
void f1() { printf("f1.c\n"); }
</file>
@@ -96,6 +93,91 @@
</para>
+ <section>
+ <title>Building Static Libraries Explicitly</title>
+
+ <para>
+
+ The &Library; function builds a traditional static library.
+ If you want to be explicit about the type of library being built,
+ you can use the synonym &StaticLibrary; function
+ instead of &Library:
+
+ </para>
+
+ <scons_example name="StaticLibrary" printme="1">
+ <file name="SConstruct" printme="1">
+ StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+ </file>
+ </scons_example>
+
+ <para>
+
+ There is no functional difference between the
+ &StaticLibrary; and &Library; functions.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Building Shared (DLL) Libraries</title>
+
+ <para>
+
+ If you want to build a shared library (on POSIX systems)
+ or a DLL file (on Windows systems),
+ you use the &SharedLibrary; function:
+
+ </para>
+
+ <scons_example name="SharedLibrary" printme="1">
+ <file name="SConstruct" printme="1">
+ SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+ </file>
+ <file name="f1.c">
+ void f1() { printf("f1.c\n"); }
+ </file>
+ <file name="f2.c">
+ void f2() { printf("f2.c\n"); }
+ </file>
+ <file name="f3.c">
+ void f3() { printf("f3.c\n"); }
+ </file>
+ </scons_example>
+
+ <para>
+
+ The output on POSIX:
+
+ </para>
+
+ <scons_output example="SharedLibrary" os="posix">
+ <command>scons -Q</command>
+ </scons_output>
+
+ <para>
+
+ And the output on Windows:
+
+ </para>
+
+ <scons_output example="SharedLibrary" os="win32">
+ <command>scons -Q</command>
+ </scons_output>
+
+ <para>
+
+ Notice again that &SCons; takes care of
+ building the output file correctly,
+ adding the <literal>-shared</literal> option
+ for a POSIX compilation,
+ and the <literal>/dll</literal> option on Windows.
+
+ </para>
+
+ </section>
+
</section>
<section>
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml
index fedeb7f..a47446a 100644
--- a/doc/user/libraries.sgml
+++ b/doc/user/libraries.sgml
@@ -91,6 +91,86 @@
</para>
+ <section>
+ <title>Building Static Libraries Explicitly</title>
+
+ <para>
+
+ The &Library; function builds a traditional static library.
+ If you want to be explicit about the type of library being built,
+ you can use the synonym &StaticLibrary; function
+ instead of &Library;:
+
+ </para>
+
+ <programlisting>
+ StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+ </programlisting>
+
+ <para>
+
+ There is no functional difference between the
+ &StaticLibrary; and &Library; functions.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Building Shared (DLL) Libraries</title>
+
+ <para>
+
+ If you want to build a shared library (on POSIX systems)
+ or a DLL file (on Windows systems),
+ you use the &SharedLibrary; function:
+
+ </para>
+
+ <programlisting>
+ SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+ </programlisting>
+
+ <para>
+
+ The output on POSIX:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons -Q</userinput>
+ cc -c -o f1.os f1.c
+ cc -c -o f2.os f2.c
+ cc -c -o f3.os f3.c
+ cc -shared -o libfoo.so f1.os f2.os f3.os
+ </literallayout>
+
+ <para>
+
+ And the output on Windows:
+
+ </para>
+
+ <literallayout>
+ C:\><userinput>scons -Q</userinput>
+ cl /nologo /c f1.c /Fof1.obj
+ cl /nologo /c f2.c /Fof2.obj
+ cl /nologo /c f3.c /Fof3.obj
+ link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
+ </literallayout>
+
+ <para>
+
+ Notice again that &SCons; takes care of
+ building the output file correctly,
+ adding the <literal>-shared</literal> option
+ for a POSIX compilation,
+ and the <literal>/dll</literal> option on Windows.
+
+ </para>
+
+ </section>
+
</section>
<section>
diff --git a/doc/user/scanners.in b/doc/user/scanners.in
index fe409ad..254b433 100644
--- a/doc/user/scanners.in
+++ b/doc/user/scanners.in
@@ -291,7 +291,7 @@ over the file scanning rather than being called for each input line:
env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'})
env.Append(SCANNERS = kscan)
- env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
+ env.Command('foo', 'foo.k', 'kprocess &lt; $SOURCES &gt; $TARGET')
</file>
<file name="foo.k">
include other_file
diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml
index 23cd044..ee82b43 100644
--- a/doc/user/scanners.sgml
+++ b/doc/user/scanners.sgml
@@ -290,7 +290,7 @@ over the file scanning rather than being called for each input line:
env = Environment(ENV = {'PATH' : '/usr/local/bin'})
env.Append(SCANNERS = kscan)
- env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
+ env.Command('foo', 'foo.k', 'kprocess &lt; $SOURCES &gt; $TARGET')
</programlisting>
<!--
diff --git a/doc/user/simple.in b/doc/user/simple.in
index 3940bc3..3d9d7dc 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -111,6 +111,58 @@
</para>
<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>
+
+ <scons_example name="clean">
+ <file name="SConstruct">
+ Program('hello.c')
+ </file>
+ <file name="hello.c">
+ int main() { printf("Hello, world!\n"); }
+ </file>
+ </scons_example>
+
+ <scons_output example="clean" os="posix">
+ <command>scons</command>
+ <command>scons -c</command>
+ </scons_output>
+
+ <para>
+
+ And the output on Windows looks like:
+
+ </para>
+
+ <scons_output example="clean" os="win32">
+ <command>scons</command>
+ <command>scons -c</command>
+ </scons_output>
+
+ <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>
@@ -347,7 +399,7 @@
</para>
<programlisting>
- Program('program', Split('main.c file1.c file2.'))
+ Program('program', Split('main.c file1.c file2.c'))
</programlisting>
<para>
@@ -381,7 +433,7 @@
</para>
<programlisting>
- list = Split('main.c file1.c file2.')
+ list = Split('main.c file1.c file2.c')
Program('program', list)
</programlisting>
@@ -422,7 +474,7 @@
</para>
<programlisting>
- list = Split('main.c file1.c file2.')
+ list = Split('main.c file1.c file2.c')
Program(target = 'program', source = list)
</programlisting>
@@ -435,7 +487,7 @@
</para>
<programlisting>
- list = Split('main.c file1.c file2.')
+ list = Split('main.c file1.c file2.c')
Program(source = list, target = 'program')
</programlisting>
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index 02a57ef..4309837 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -118,6 +118,75 @@
</para>
<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>
+
+
+
+ <literallayout>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -c -o hello.o 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.
+ </literallayout>
+
+ <para>
+
+ And the output on Windows looks like:
+
+ </para>
+
+ <literallayout>
+ C:\><userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cl /nologo /c hello.c /Fohello.obj
+ link /nologo /OUT:hello.exe hello.obj
+ scons: done building targets.
+ C:\><userinput>scons -c</userinput>
+ scons: Reading SConscript files ...
+ scons: done reading SConscript files.
+ scons: Cleaning targets ...
+ Removed hello.obj
+ Removed hello.exe
+ scons: done cleaning targets.
+ </literallayout>
+
+ <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>
@@ -352,7 +421,7 @@
</para>
<programlisting>
- Program('program', Split('main.c file1.c file2.'))
+ Program('program', Split('main.c file1.c file2.c'))
</programlisting>
<para>
@@ -386,7 +455,7 @@
</para>
<programlisting>
- list = Split('main.c file1.c file2.')
+ list = Split('main.c file1.c file2.c')
Program('program', list)
</programlisting>
@@ -427,7 +496,7 @@
</para>
<programlisting>
- list = Split('main.c file1.c file2.')
+ list = Split('main.c file1.c file2.c')
Program(target = 'program', source = list)
</programlisting>
@@ -440,7 +509,7 @@
</para>
<programlisting>
- list = Split('main.c file1.c file2.')
+ list = Split('main.c file1.c file2.c')
Program(source = list, target = 'program')
</programlisting>