<!--

  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>