diff options
Diffstat (limited to 'doc/user/libraries.xml')
| -rw-r--r-- | doc/user/libraries.xml | 451 |
1 files changed, 451 insertions, 0 deletions
diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml new file mode 100644 index 0000000..e3821ce --- /dev/null +++ b/doc/user/libraries.xml @@ -0,0 +1,451 @@ +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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> + + <programlisting> + Library('foo', ['f1.c', 'f2.c', 'f3.c']) + </programlisting> + + <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> + + <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> + + <para> + + On a Windows system, + a build of the above example would look like: + + </para> + + <screen> + C:\><userinput>scons -Q</userinput> + + scons: warning: No installed VCs + File "<stdin>", line 67, in __call__ + + scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly + File "<stdin>", line 67, in __call__ + 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> + + <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> + + <programlisting> + Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o']) + </programlisting> + + <para> + + And SCons realizes that only the source code files + must be compiled into object files + before creating the final library: + + </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> + + <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> + + <programlisting> + StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + </programlisting> + + <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> + + <programlisting> + SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + </programlisting> + + <para> + + The output on POSIX: + + </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> + + <para> + + And the output on Windows: + + </para> + + <screen> + C:\><userinput>scons -Q</userinput> + + scons: warning: No installed VCs + File "<stdin>", line 67, in __call__ + + scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly + File "<stdin>", line 67, in __call__ + 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) + </screen> + + <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> + + <programlisting> + Library('foo', ['f1.c', 'f2.c', 'f3.c']) + Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.') + </programlisting> + + <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> + + <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> + + <para> + + On a Windows system, + a build of the above example would look like: + + </para> + + <screen> + C:\><userinput>scons -Q</userinput> + + scons: warning: No installed VCs + File "<stdin>", line 67, in __call__ + + scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly + File "<stdin>", line 67, in __call__ + 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 + </screen> + + <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> + + <programlisting> + Program('prog.c', LIBS='foo', LIBPATH='.') + </programlisting> + + <para> + + is equivalent to: + + </para> + + <programlisting> + Program('prog.c', LIBS=['foo'], LIBPATH='.') + </programlisting> + + <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> + + <programlisting> + Program('prog.c', LIBS = 'm', + LIBPATH = ['/usr/lib', '/usr/local/lib']) + </programlisting> + + <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> + + <programlisting> + LIBPATH = '/usr/lib:/usr/local/lib' + </programlisting> + + <para> + + or a semi-colon on Windows systems: + + </para> + + <programlisting> + LIBPATH = 'C:\\lib;D:\\lib' + </programlisting> + + <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> + + <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> + + <para> + + On a Windows system, + a build of the above example would look like: + + </para> + + <screen> + C:\><userinput>scons -Q</userinput> + + scons: warning: No installed VCs + File "<stdin>", line 67, in __call__ + + scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly + File "<stdin>", line 67, in __call__ + cl /Foprog.obj /c prog.c /nologo + link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj + </screen> + <!-- 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> |