This file contains information is for creating a single .o style library 
object file and then using it in other programs.  

    In general, libraries are created from many library source files, and are 
    either built as archive files (libmine.a) that are statically linked into 
    executables that use them, or as shared object files (libmine.so) that are
    dynamically linked into executables that use them.   To link in libraries
    of these types, use the gcc command line options: 
        -L<path to file containing library> -l<library name> 

    For example, if I have a library named libmine.so in /home/newhall/lib/
    then I'd do the following to link it into my program:
         gcc -o myprog myprog.c  -L/home/newhall/lib -lmine 

    You may also need to specify and include path so the compiler can
    find the library header file:  -I /home/newhall/include

    See gcc documentation for information on how to build .a and .so files.
-----------------------------------------------------------------------------

1. USING AND LINKING LIBRARY CODE
   ------------------------------

To use a Library that is not linked into your program automatically by
the compiler, you need to (1) include the library's header file in your
C source file (test.c in the example below), and (2) tell the compiler to
link in the code from the library .o file into your executable file:

    step 1: Add an include line (#include "somelib.h") in a program 
            source file (e.g., test.c).

    step 2: Link the program's .c file with the library object file 
	    (i.e. specify the somelib.o file as a command line argument 
	    to gccx): 

	% gccx  -o myprog test.c somelib.o
 
    The resulting executable file (myprog) will contain machine code 
    for all the functions defined in test.c plus any mylib library 
    functions that are called by 

-----------------------------------------------------------------------------

2. CREATING AND USING YOUR OWN LIBRARY CODE
   -----------------------------------------
   To create a Library of code you need to do the following:

        (1) create an INTERFACE to your library:  mylib.h

        (2) create an IMPLEMENTATION of your library: mylib.c

        (3) create a LIBRARY OBJECT FILE that can be linked with
            programs that want to use our library code

        (4) USE the library in other C code: 
		(a) #include "mylib.h"
		(b) link in the libary code into a.out file 

(1) INTERFACE: the header file to your library should contain "boiler plate" 
    code (#ifndef ... #endif) around the header file's contents.  This 
    ensures that the preprocessor only includes the mylib.h file one time.

#ifndef _MYLIB_H_
#define _MYLIB_H_

function prototypes and comments for all functions exported by your library

for example:

    extern int foo(float y, float z);   // a very bad function name

#endif


(2) IMPLEMENTATION: create a mylib.c file that #includes "mylib.h" and 
    contains the implementation of every function in your library.
    
    #include "mylib.h"

    ...

    int foo(float y, float z) { 
	...
    }

(3) create a LIBRARY OBJECT FILE that can be linked into other programs
    that use your library (use the -c option to gccx to tell it just
    to create an object file (a .o file) rather than an executable:

	% gccx -o mylib.o -c mylib.c


(4) USE the library in other programs:

    step 1: Add an include line (#include "mylib.h") in a program 
            source file (e.g., test.c).

    step 2: Link the program's .c file with the library object file 
	    (i.e. specify the mylib.o file as a command line argument to gccx): 

	% gccx  test.c mylib.o
 
    The resulting a.out out will contain machine code for all the functions 
    defined in test.c plus any mylib library functions that are called by 
    the test.c code.