diff options
Diffstat (limited to 'doc/user/libraries.in')
| -rw-r--r-- | doc/user/libraries.in | 445 |
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> |