summaryrefslogtreecommitdiff
path: root/doc/user/libraries.in
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
commit140d836e9cd54fb67b969fd82ef7ed19ba574d40 (patch)
tree0df3e32ee39603d43f9b90fd2f2e1f7cce4249d4 /doc/user/libraries.in
parentcb3425abe0bc2d05caf401ca24b82a25a81f009d (diff)
Imported Upstream version 2.3.1upstream/2.3.1
Diffstat (limited to 'doc/user/libraries.in')
-rw-r--r--doc/user/libraries.in445
1 files changed, 0 insertions, 445 deletions
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
deleted file mode 100644
index d8a6b49..0000000
--- a/doc/user/libraries.in
+++ /dev/null
@@ -1,445 +0,0 @@
-<!--
-
- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-
- Permission is hereby granted, free of charge, to any person obtaining
- a copy of this software and associated documentation files (the
- "Software"), to deal in the Software without restriction, including
- without limitation the rights to use, copy, modify, merge, publish,
- distribute, sublicense, and/or sell copies of the Software, and to
- permit persons to whom the Software is furnished to do so, subject to
- the following conditions:
-
- The above copyright notice and this permission notice shall be included
- in all copies or substantial portions of the Software.
-
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
- KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
- WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
--->
-
- <para>
-
- It's often useful to organize large software projects
- by collecting parts of the software into one or more libraries.
- &SCons; makes it easy to create libraries
- and to use them in the programs.
-
- </para>
-
- <section>
- <title>Building Libraries</title>
-
- <para>
-
- You build your own libraries by specifying &b-link-Library;
- instead of &b-link-Program;:
-
- </para>
-
- <scons_example name="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>
-
- &SCons; uses the appropriate library prefix and suffix for your system.
- So on POSIX or Linux systems,
- the above example would build as follows
- (although &ranlib; may not be called on all systems):
-
- </para>
-
- <scons_output example="ex1" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- On a Windows system,
- a build of the above example would look like:
-
- </para>
-
- <scons_output example="ex1" os="win32">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- The rules for the target name of the library
- are similar to those for programs:
- if you don't explicitly specify a target library name,
- &SCons; will deduce one from the
- name of the first source file specified,
- and &SCons; will add an appropriate
- file prefix and suffix if you leave them off.
-
- </para>
-
- <section>
- <title>Building Libraries From Source Code or Object Files</title>
-
- <para>
-
- The previous example shows building a library from a
- list of source files.
- You can, however, also give the &b-link-Library; call
- object files,
- and it will correctly realize
- In fact, you can arbitrarily mix source code files
- and object files in the source list:
-
- </para>
-
- <scons_example name="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>
-
- And SCons realizes that only the source code files
- must be compiled into object files
- before creating the final library:
-
- </para>
-
- <scons_output example="objects" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- Of course, in this example, the object files
- must already exist for the build to succeed.
- See <xref linkend="chap-nodes"></xref>, below,
- for information about how you can
- build object files explicitly
- and include the built files in a library.
-
- </para>
-
- </section>
-
- <section>
- <title>Building Static Libraries Explicitly: the &b-StaticLibrary; Builder</title>
-
- <para>
-
- The &b-link-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 &b-link-StaticLibrary; function
- instead of &b-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
- &b-link-StaticLibrary; and &b-Library; functions.
-
- </para>
-
- </section>
-
- <section>
- <title>Building Shared (DLL) Libraries: the &b-SharedLibrary; Builder</title>
-
- <para>
-
- If you want to build a shared library (on POSIX systems)
- or a DLL file (on Windows systems),
- you use the &b-link-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">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- And the output on Windows:
-
- </para>
-
- <scons_output example="SharedLibrary" os="win32">
- <scons_output_command>scons -Q</scons_output_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>
- <title>Linking with Libraries</title>
-
- <para>
-
- Usually, you build a library
- because you want to link it with one or more programs.
- You link libraries with a program by specifying
- the libraries in the &cv-link-LIBS; construction variable,
- and by specifying the directory in which
- the library will be found in the
- &cv-link-LIBPATH; construction variable:
-
- <!-- In the preceding paragraph, the "$" notation for
- LIBS, LIBPATH etc. is used for the first time.
- Maybe some words of explanation would be nice. -->
-
- </para>
-
- <scons_example name="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>
-
- Notice, of course, that you don't need to specify a library
- prefix (like <literal>lib</literal>)
- or suffix (like <literal>.a</literal> or <literal>.lib</literal>).
- &SCons; uses the correct prefix or suffix for the current system.
-
- </para>
-
- <para>
-
- On a POSIX or Linux system,
- a build of the above example would look like:
-
- </para>
-
- <scons_output example="ex2" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- On a Windows system,
- a build of the above example would look like:
-
- </para>
-
- <scons_output example="ex2" os="win32">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- As usual, notice that &SCons; has taken care
- of constructing the correct command lines
- to link with the specified library on each system.
-
- </para>
-
- <para>
-
- Note also that,
- if you only have a single library to link with,
- you can specify the library name in single string,
- instead of a Python list,
- so that:
-
- </para>
-
- <sconstruct>
- Program('prog.c', LIBS='foo', LIBPATH='.')
- </sconstruct>
-
- <para>
-
- is equivalent to:
-
- </para>
-
- <sconstruct>
- Program('prog.c', LIBS=['foo'], LIBPATH='.')
- </sconstruct>
-
- <para>
-
- This is similar to the way that &SCons;
- handles either a string or a list to
- specify a single source file.
-
- </para>
-
- </section>
-
- <section>
- <title>Finding Libraries: the &cv-LIBPATH; Construction Variable</title>
-
- <para>
-
- By default, the linker will only look in
- certain system-defined directories for libraries.
- &SCons; knows how to look for libraries
- in directories that you specify with the
- &cv-link-LIBPATH; construction variable.
- &cv-LIBPATH; consists of a list of
- directory names, like so:
-
- </para>
-
- <scons_example name="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>
-
- Using a Python list is preferred because it's portable
- across systems. Alternatively, you could put all of
- the directory names in a single string, separated by the
- system-specific path separator character:
- a colon on POSIX systems:
-
- </para>
-
- <sconstruct>
- LIBPATH = '/usr/lib:/usr/local/lib'
- </sconstruct>
-
- <para>
-
- or a semi-colon on Windows systems:
-
- </para>
-
- <sconstruct>
- LIBPATH = 'C:\\lib;D:\\lib'
- </sconstruct>
-
- <para>
-
- (Note that Python requires that the backslash
- separators in a Windows path name
- be escaped within strings.)
-
- </para>
-
- <para>
-
- When the linker is executed,
- &SCons; will create appropriate flags
- so that the linker will look for
- libraries in the same directories as &SCons;.
- So on a POSIX or Linux system,
- a build of the above example would look like:
-
- </para>
-
- <scons_output example="ex3" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- On a Windows system,
- a build of the above example would look like:
-
- </para>
-
- <scons_output example="ex3" os="win32">
- <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. -->
-
- <para>
-
- Note again that &SCons; has taken care of
- the system-specific details of creating
- the right command-line options.
-
- </para>
-
- </section>