Branch for User's Guide work.

[scons.git] / doc / user / libraries.in

diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index a31b2b4fa9ab0a8b96f0f65516704f76cd470872..7a88d6f969a89a4d8dd3fb4a264296e9dbc1c0ff 100644 (file)
--- 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>