summaryrefslogtreecommitdiff
path: root/doc/user/libraries.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/libraries.xml')
-rw-r--r--doc/user/libraries.xml242
1 files changed, 140 insertions, 102 deletions
diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml
index f3a5492..aa4561e 100644
--- a/doc/user/libraries.xml
+++ b/doc/user/libraries.xml
@@ -1,6 +1,27 @@
+<?xml version='1.0'?>
+<!DOCTYPE sconsdoc [
+ <!ENTITY % scons SYSTEM "../scons.mod">
+ %scons;
+
+ <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
+ %builders-mod;
+ <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
+ %functions-mod;
+ <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
+ %tools-mod;
+ <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
+ %variables-mod;
+]>
+
+<chapter id="chap-libraries"
+ xmlns="http://www.scons.org/dbxsd/v1.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd">
+<title>Building and Linking with Libraries</title>
+
<!--
- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
@@ -42,9 +63,20 @@
</para>
- <programlisting>
- Library('foo', ['f1.c', 'f2.c', 'f3.c'])
- </programlisting>
+ <scons_example name="libraries_ex1" printme="1">
+ <file name="SConstruct" printme="1">
+Library('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>
@@ -55,14 +87,9 @@
</para>
- <screen>
- % <userinput>scons -Q</userinput>
- cc -o f1.o -c f1.c
- cc -o f2.o -c f2.c
- cc -o f3.o -c f3.c
- ar rc libfoo.a f1.o f2.o f3.o
- ranlib libfoo.a
- </screen>
+ <scons_output example="libraries_ex1" os="posix" suffix="1">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -71,13 +98,9 @@
</para>
- <screen>
- C:\><userinput>scons -Q</userinput>
- cl /Fof1.obj /c f1.c /nologo
- cl /Fof2.obj /c f2.c /nologo
- cl /Fof3.obj /c f3.c /nologo
- lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
- </screen>
+ <scons_output example="libraries_ex1" os="win32" suffix="2">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -106,9 +129,23 @@
</para>
- <programlisting>
- Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
- </programlisting>
+ <scons_example name="libraries_objects" printme="1">
+ <file name="SConstruct" printme="1">
+Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o'])
+ </file>
+ <file name="f1.c">
+void f1() { printf("f1.c\n"); }
+ </file>
+ <file name="f2.o">
+object file
+ </file>
+ <file name="f3.c">
+void f3() { printf("f3.c\n"); }
+ </file>
+ <file name="f4.o">
+object file
+ </file>
+ </scons_example>
<para>
@@ -118,13 +155,9 @@
</para>
- <screen>
- % <userinput>scons -Q</userinput>
- cc -o f1.o -c f1.c
- cc -o f3.o -c f3.c
- ar rc libfoo.a f1.o f2.o f3.o f4.o
- ranlib libfoo.a
- </screen>
+ <scons_output example="libraries_objects" os="posix" suffix="1">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -151,9 +184,11 @@
</para>
- <programlisting>
- StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
- </programlisting>
+ <scons_example name="libraries_StaticLibrary" printme="1">
+ <file name="SConstruct" printme="1">
+StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
+ </file>
+ </scons_example>
<para>
@@ -175,9 +210,20 @@
</para>
- <programlisting>
- SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c'])
- </programlisting>
+ <scons_example name="libraries_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>
@@ -185,13 +231,9 @@
</para>
- <screen>
- % <userinput>scons -Q</userinput>
- cc -o f1.os -c f1.c
- cc -o f2.os -c f2.c
- cc -o f3.os -c f3.c
- cc -o libfoo.so -shared f1.os f2.os f3.os
- </screen>
+ <scons_output example="libraries_SharedLibrary" os="posix" suffix="1">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -199,15 +241,9 @@
</para>
- <screen>
- C:\><userinput>scons -Q</userinput>
- cl /Fof1.obj /c f1.c /nologo
- cl /Fof2.obj /c f2.c /nologo
- cl /Fof3.obj /c f3.c /nologo
- link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
- RegServerFunc(target, source, env)
- embedManifestDllCheck(target, source, env)
- </screen>
+ <scons_output example="libraries_SharedLibrary" os="win32" suffix="2">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -242,10 +278,24 @@
</para>
- <programlisting>
- Library('foo', ['f1.c', 'f2.c', 'f3.c'])
- Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
- </programlisting>
+ <scons_example name="libraries_ex2">
+ <file name="SConstruct" printme="1">
+Library('foo', ['f1.c', 'f2.c', 'f3.c'])
+Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.')
+ </file>
+ <file name="f1.c">
+int main() { printf("Hello, world!\n"); }
+ </file>
+ <file name="f2.c">
+int main() { printf("Hello, world!\n"); }
+ </file>
+ <file name="f3.c">
+int main() { printf("Hello, world!\n"); }
+ </file>
+ <file name="prog.c">
+int main() { printf("Hello, world!\n"); }
+ </file>
+ </scons_example>
<para>
@@ -263,16 +313,9 @@
</para>
- <screen>
- % <userinput>scons -Q</userinput>
- cc -o f1.o -c f1.c
- cc -o f2.o -c f2.c
- cc -o f3.o -c f3.c
- ar rc libfoo.a f1.o f2.o f3.o
- ranlib libfoo.a
- cc -o prog.o -c prog.c
- cc -o prog prog.o -L. -lfoo -lbar
- </screen>
+ <scons_output example="libraries_ex2" os="posix" suffix="1">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -281,16 +324,9 @@
</para>
- <screen>
- C:\><userinput>scons -Q</userinput>
- cl /Fof1.obj /c f1.c /nologo
- cl /Fof2.obj /c f2.c /nologo
- cl /Fof3.obj /c f3.c /nologo
- lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
- cl /Foprog.obj /c prog.c /nologo
- link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
- embedManifestExeCheck(target, source, env)
- </screen>
+ <scons_output example="libraries_ex2" os="win32" suffix="2">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -310,9 +346,9 @@
</para>
- <programlisting>
- Program('prog.c', LIBS='foo', LIBPATH='.')
- </programlisting>
+ <sconstruct>
+Program('prog.c', LIBS='foo', LIBPATH='.')
+ </sconstruct>
<para>
@@ -320,9 +356,9 @@
</para>
- <programlisting>
- Program('prog.c', LIBS=['foo'], LIBPATH='.')
- </programlisting>
+ <sconstruct>
+Program('prog.c', LIBS=['foo'], LIBPATH='.')
+ </sconstruct>
<para>
@@ -349,10 +385,15 @@
</para>
- <programlisting>
- Program('prog.c', LIBS = 'm',
- LIBPATH = ['/usr/lib', '/usr/local/lib'])
- </programlisting>
+ <scons_example name="libraries_ex3">
+ <file name="SConstruct" printme="1">
+Program('prog.c', LIBS = 'm',
+ LIBPATH = ['/usr/lib', '/usr/local/lib'])
+ </file>
+ <file name="prog.c">
+int main() { printf("prog.c\n"); }
+ </file>
+ </scons_example>
<para>
@@ -364,9 +405,9 @@
</para>
- <programlisting>
- LIBPATH = '/usr/lib:/usr/local/lib'
- </programlisting>
+ <sconstruct>
+LIBPATH = '/usr/lib:/usr/local/lib'
+ </sconstruct>
<para>
@@ -374,9 +415,9 @@
</para>
- <programlisting>
- LIBPATH = 'C:\\lib;D:\\lib'
- </programlisting>
+ <sconstruct>
+LIBPATH = 'C:\\lib;D:\\lib'
+ </sconstruct>
<para>
@@ -397,11 +438,9 @@
</para>
- <screen>
- % <userinput>scons -Q</userinput>
- cc -o prog.o -c prog.c
- cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm
- </screen>
+ <scons_output example="libraries_ex3" os="posix" suffix="1">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<para>
@@ -410,12 +449,9 @@
</para>
- <screen>
- C:\><userinput>scons -Q</userinput>
- cl /Foprog.obj /c prog.c /nologo
- link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
- embedManifestExeCheck(target, source, env)
- </screen>
+ <scons_output example="libraries_ex3" os="win32" suffix="2">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
<!-- The link command is too wide in the PDF version.
There are some other examples of this throughout the document. -->
@@ -428,3 +464,5 @@
</para>
</section>
+
+</chapter>
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-10 11:18:27 +0000