Merged revisions 1784-1824 via svnmerge from

[scons.git] / doc / user / variants.sgml

diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml
index 3024c02381bd5f42c21fbbe8c8a845ed7425dccc..672785953dcb89fc97143784f6737cfa798f9266 100644 (file)
--- a/doc/user/variants.sgml
+++ b/doc/user/variants.sgml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003 Steven Knight
+  __COPYRIGHT__
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -22,19 +22,113 @@
   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 -->
- <para>
 
-   X
+<!--
+
+=head1 Variant builds
+
+=head2 Variations on a theme
+
+Other variations of this model are possible. For example, you might decide
+that you want to separate out your include files into platform dependent and
+platform independent files. In this case, you'd have to define an
+alternative to C<$INCLUDE> for platform-dependent files. Most F<Conscript>
+files, generating purely platform-independent include files, would not have
+to change.
+
+You might also want to be able to compile your whole system with debugging
+or profiling, for example, enabled. You could do this with appropriate
+command line options, such as C<DEBUG=on>. This would then be translated
+into the appropriate platform-specific requirements to enable debugging
+(this might include turning off optimization, for example). You could
+optionally vary the name space for these different types of systems, but, as
+we'll see in the next section, it's not B<essential> to do this, since Cons
+is pretty smart about rebuilding things when you change options.
+
+-->
+
+  <para>
+
+  The &build_dir; keyword argument of
+  the &SConscript; function provides everything
+  we need to show how easy it is to create
+  variant builds using &SCons;.
+  Suppose, for example, that we want to
+  build a program for both Windows and Linux platforms,
+  but that we want to build it in a shared directory
+  with separate side-by-side build directories
+  for the Windows and Linux versions of the program.
+
+  </para>
+
+  <programlisting>
+    platform = ARGUMENTS.get('OS', Platform())
+
+    include = "#export/$PLATFORM/include"
+    lib = "#export/$PLATFORM/lib"
+    bin = "#export/$PLATFORM/bin"
+
+    env = Environment(PLATFORM = platform,
+                      BINDIR = bin,
+                      INCDIR = include,
+                      LIBDIR = lib,
+                      CPPPATH = [include],
+                      LIBPATH = [lib],
+                      LIBS = 'world')
+
+    Export('env')
+
+    env.SConscript('src/SConscript', build_dir='build/$PLATFORM')
+  </programlisting>
+
+  <para>
+
+  This SConstruct file,
+  when run on a Linux system, yields:
+
+  </para>
+
+  <screen>
+    % <userinput>scons -Q OS=linux</userinput>
+    Install file: "build/linux/world/world.h" as "export/linux/include/world.h"
+    cc -o build/linux/hello/hello.o -c -Iexport/linux/include build/linux/hello/hello.c
+    cc -o build/linux/world/world.o -c -Iexport/linux/include build/linux/world/world.c
+    ar rc build/linux/world/libworld.a build/linux/world/world.o
+    ranlib build/linux/world/libworld.a
+    Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a"
+    cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld
+    Install file: "build/linux/hello/hello" as "export/linux/bin/hello"
+  </screen>
+
+  <para>
+
+  The same SConstruct file on Windows would build:
 
- </para>
+  </para>
 
- <section>
- <title>X</title>
+  <screen>
+    C:\><userinput>scons -Q OS=windows</userinput>
+    Install file: "build/windows/world/world.h" as "export/windows/include/world.h"
+    cl /nologo /Iexport\windows\include /c build\windows\hello\hello.c /Fobuild\windows\hello\hello.obj
+    cl /nologo /Iexport\windows\include /c build\windows\world\world.c /Fobuild\windows\world\world.obj
+    lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj
+    Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib"
+    link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj
+    Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe"
+  </screen>
 
-   <para>
+  <!--
 
-   X
+  <scons_example name="ex_var2">
+    <file name="SConstruct" printme="1">
+    env = Environment(OS = ARGUMENTS.get('OS'))
+    for os in ['newell', 'post']:
+        SConscript('src/SConscript', build_dir='build/' + os)
+    </file>
+  </scons_example>
 
-   </para>
+  <scons_output example="ex_var2">
+    <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
 
- </section>
+  -->