diff options
author | Luca Falavigna <dktrkranz@debian.org> | 2010-01-02 20:56:27 +0100 |
---|---|---|
committer | Luca Falavigna <dktrkranz@debian.org> | 2010-01-02 20:56:27 +0100 |
commit | 72c578fd4b0b4a5a43e18594339ac4ff26c376dc (patch) | |
tree | cadaf3abe37a1066ceae933bc8fe7b75c85f56d2 /doc/reference/Library.xml | |
parent | 548ed1064f327bccc6e538806740d41ea2d928a1 (diff) |
Imported Upstream version 1.2.0.d20091224upstream/1.2.0.d20091224
Diffstat (limited to 'doc/reference/Library.xml')
-rw-r--r-- | doc/reference/Library.xml | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/doc/reference/Library.xml b/doc/reference/Library.xml new file mode 100644 index 0000000..19a3e96 --- /dev/null +++ b/doc/reference/Library.xml @@ -0,0 +1,152 @@ +<!-- + + Copyright (c) 2001, 2002, 2003 Steven Knight + + 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. + +--> + +<!-- + +=head2 The C<Library> method + +The C<Library> method arranges to create the specified library from the +specified object files. It is invoked as follows: + + Library $env <library name>, <source or object files>; + +The library name will have the value of the C<SUFLIB> construction +variable appended (by default, C<.lib> on Win32 systems, C<.a> on Unix +systems) if the suffix is not already present. + +Source files may be specified in place of objects files-,-the C<Objects> +method will be invoked to arrange the conversion of all the files into +object files, and hence all the observations about the C<Objects> method, +above, apply to this method also. + +The actual creation of the library will be handled by an external +command which results from expanding the C<ARCOM> construction variable, +with C<%E<lt>> set to the library members (in the order presented), +and C<%E<gt>> to the library to be created. (See the section above +on construction variable expansion for details.) The user may set +variables in the construction environment which will affect the +operation of the command. These include C<AR>, the archive program +to use, C<ARFLAGS>, which can be used to modify the flags given to +the program specified by C<AR>, and C<RANLIB>, the name of a archive +index generation program, if needed (if the particular need does not +require the latter functionality, then C<ARCOM> must be redefined to not +reference C<RANLIB>). + +The C<Library> method allows the same library to be specified in multiple +method invocations. All of the contributing objects from all the invocations +(which may be from different directories) are combined and generated by a +single archive command. Note, however, that if you prune a build so that +only part of a library is specified, then only that part of the library will +be generated (the rest will disappear!). + +--> + + <section> + <title>Linking With a Library</title> + + <programlisting> + env = Environment(CC = 'gcc', + LIBS = 'world') + env.Program('hello.c') + </programlisting> + + <literallayout> + % <userinput>scons</userinput> + gcc -c hello.c -o hello.o + gcc -c world.c -o world.o + gcc -o hello hello.o -lworld + </literallayout> + + </section> + + <section> + <title>Creating a Library</title> + + <programlisting> + env = Environment(CC = 'gcc', + LIBS = 'world') + env.Program('hello.c') + env.Library('world.c') + </programlisting> + + <literallayout> + % <userinput>scons</userinput> + gcc -c hello.c -o hello.o + gcc -c world.c -o world.o + ar r libworld.a world.o + ar: creating libworld.a + ranlib libworld.a + gcc -o hello hello.o libworld.a + </literallayout> + + </section> + +<!-- + +A key simplification of Cons is the idea of a B<construction environment>. A +construction environment is an B<object> characterized by a set of key/value +pairs and a set of B<methods>. In order to tell Cons how to build something, +you invoke the appropriate method via an appropriate construction +environment. Consider the following example: + + + + $env = new cons( + CC => 'gcc', + LIBS => 'libworld.a' + ); + + Program $env 'hello', 'hello.c'; + +In this case, rather than using the default construction environment, as is, +we have overridden the value of C<CC> so that the GNU C Compiler equivalent +is used, instead. Since this version of B<Hello, World!> requires a library, +F<libworld.a>, we have specified that any program linked in this environment +should be linked with that library. If the library exists already, well and +good, but if not, then we'll also have to include the statement: + + + + Library $env 'libworld', 'world.c'; + +Now if you type C<cons hello>, the library will be built before the program +is linked, and, of course, C<gcc> will be used to compile both modules: + + + + % cons hello + +--> + + <section> + <title>The &Library; Builder</title> + + <para> + + X + + </para> + + </section> |