diff options
| -rw-r--r-- | doc/user/builders-commands.sgml | 2 | ||||
| -rw-r--r-- | doc/user/builders-writing.in | 10 | ||||
| -rw-r--r-- | doc/user/builders-writing.sgml | 10 | ||||
| -rw-r--r-- | doc/user/command-line.in | 6 | ||||
| -rw-r--r-- | doc/user/command-line.sgml | 10 | ||||
| -rw-r--r-- | doc/user/depends.in | 12 | ||||
| -rw-r--r-- | doc/user/depends.sgml | 12 | ||||
| -rw-r--r-- | doc/user/environments.sgml | 2 | ||||
| -rw-r--r-- | doc/user/libraries.in | 88 | ||||
| -rw-r--r-- | doc/user/libraries.sgml | 80 | ||||
| -rw-r--r-- | doc/user/scanners.in | 2 | ||||
| -rw-r--r-- | doc/user/scanners.sgml | 2 | ||||
| -rw-r--r-- | doc/user/simple.in | 60 | ||||
| -rw-r--r-- | doc/user/simple.sgml | 77 |
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/' < $SOURCE > $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 < $SOURCE > $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 < $SOURCE > $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 <hello.h> 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 <hello.h> 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 < $SOURCES > $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 < $SOURCES > $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> |