From d051e7a170f2207ef9c41e86af17cdd89b931a8f Mon Sep 17 00:00:00 2001 From: stevenknight Date: Sat, 28 Feb 2004 09:25:48 +0000 Subject: [PATCH] Branch for User's Guide work. git-svn-id: http://scons.tigris.org/svn/scons/trunk@910 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- doc/user/builders-commands.sgml | 2 +- doc/user/builders-writing.in | 10 ++-- doc/user/builders-writing.sgml | 10 ++-- doc/user/command-line.in | 6 +-- doc/user/command-line.sgml | 10 +--- doc/user/depends.in | 12 ++--- doc/user/depends.sgml | 12 ++--- doc/user/environments.sgml | 2 +- doc/user/libraries.in | 88 +++++++++++++++++++++++++++++++-- doc/user/libraries.sgml | 80 ++++++++++++++++++++++++++++++ doc/user/scanners.in | 2 +- doc/user/scanners.sgml | 2 +- doc/user/simple.in | 60 ++++++++++++++++++++-- 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 64c81e52..49ba08dd 100644 --- a/doc/user/builders-commands.sgml +++ b/doc/user/builders-commands.sgml @@ -71,7 +71,7 @@ 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") diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index 50c91148..d68b872a 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: - 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. @@ -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. @@ -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. @@ -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. diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml index 796e1994..4dddb554 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: - 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. @@ -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. @@ -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. @@ -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. diff --git a/doc/user/command-line.in b/doc/user/command-line.in index 6f523a89..70c7ca70 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') @@ -80,7 +80,7 @@ scons export SCONSFLAGS="-Q" - scons + scons diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml index cf15b932..78c94e1c 100644 --- a/doc/user/command-line.sgml +++ b/doc/user/command-line.sgml @@ -67,19 +67,13 @@ % scons scons: Reading SConscript files ... - ... scons: done reading SConscript files. scons: Building targets ... - scons: `.' is up to date. + ... [build output] ... scons: done building targets. % export SCONSFLAGS="-Q" % scons - scons: Reading SConscript files ... - ... - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. + ... [build output] ... diff --git a/doc/user/depends.in b/doc/user/depends.in index bedc91d6..43ec7f3b 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 - #include "hello.h" + #include <hello.h> int main() { @@ -741,9 +741,8 @@ operating system on which the build is performed (as reported by C - env = Environment() - hello = env.Program('hello.c') - env.Ignore(hello, '/usr/include/stdio.h') + hello = Program('hello.c') + Ignore(hello, '/usr/include/stdio.h') @@ -765,9 +764,8 @@ operating system on which the build is performed (as reported by C - env = Environment() - hello = env.Program('hello.c') - env.Depends(hello, 'other_file') + hello = Program('hello.c') + Depends(hello, 'other_file') diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index f595e085..09fb62de 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 - #include "hello.h" + #include <hello.h> int main() { @@ -753,9 +753,8 @@ operating system on which the build is performed (as reported by C - env = Environment() - hello = env.Program('hello.c') - env.Ignore(hello, '/usr/include/stdio.h') + hello = Program('hello.c') + Ignore(hello, '/usr/include/stdio.h') @@ -777,9 +776,8 @@ operating system on which the build is performed (as reported by C - env = Environment() - hello = env.Program('hello.c') - env.Depends(hello, 'other_file') + hello = Program('hello.c') + Depends(hello, 'other_file') diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml index 2b4fb5dd..eb9bf5be 100644 --- a/doc/user/environments.sgml +++ b/doc/user/environments.sgml @@ -506,7 +506,7 @@ environment undisturbed. % scons -Q - 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 ? diff --git a/doc/user/libraries.in b/doc/user/libraries.in index a31b2b4f..7a88d6f9 100644 --- a/doc/user/libraries.in +++ b/doc/user/libraries.in @@ -46,9 +46,6 @@ Library('foo', ['f1.c', 'f2.c', 'f3.c']) - - int main() { printf("Hello, world!\n"); } - void f1() { printf("f1.c\n"); } @@ -96,6 +93,91 @@ +
+ Building Static Libraries Explicitly + + + + 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: + + + + + + StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + + + + + + There is no functional difference between the + &StaticLibrary; and &Library; functions. + + + +
+ +
+ Building Shared (DLL) Libraries + + + + If you want to build a shared library (on POSIX systems) + or a DLL file (on Windows systems), + you use the &SharedLibrary; function: + + + + + + SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + + + void f1() { printf("f1.c\n"); } + + + void f2() { printf("f2.c\n"); } + + + void f3() { printf("f3.c\n"); } + + + + + + The output on POSIX: + + + + + scons -Q + + + + + And the output on Windows: + + + + + scons -Q + + + + + Notice again that &SCons; takes care of + building the output file correctly, + adding the -shared option + for a POSIX compilation, + and the /dll option on Windows. + + + +
+
diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml index fedeb7f0..a47446a0 100644 --- a/doc/user/libraries.sgml +++ b/doc/user/libraries.sgml @@ -91,6 +91,86 @@ +
+ Building Static Libraries Explicitly + + + + 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;: + + + + + StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + + + + + There is no functional difference between the + &StaticLibrary; and &Library; functions. + + + +
+ +
+ Building Shared (DLL) Libraries + + + + If you want to build a shared library (on POSIX systems) + or a DLL file (on Windows systems), + you use the &SharedLibrary; function: + + + + + SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + + + + + The output on POSIX: + + + + + % scons -Q + 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 + + + + + And the output on Windows: + + + + + C:\>scons -Q + 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 + + + + + Notice again that &SCons; takes care of + building the output file correctly, + adding the -shared option + for a POSIX compilation, + and the /dll option on Windows. + + + +
+
diff --git a/doc/user/scanners.in b/doc/user/scanners.in index fe409ad2..254b4339 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') include other_file diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml index 23cd0447..ee82b43c 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')