Building your own library of useful functions....

Software libraries
- The small - but hopefully clear and illustrative - example illustrates that you can develop new software very quickly if you can re-use some old softwares
- If you take a programming job full time, it often happens that you will take some old software to write new software
- It is than important to stream line the software re-use process
- The way to do this is organize your old software into software libraries
Header files
- Recall that C++ (and in a lesser extend C) requires that:
  
  Each object (variable or function) must FIRST be DEFINED or DECLARED BEFORE it can be USED
- See the following webpage for details: click here
- So when you build your own library of functions; and you want to use your functions in some (new) project, you will have to DEFINED or DECLARED EVERY function in your library...
  Obviously, you don't what to type this in each time.
- The common practice is to create one "HEADER file" for each object file (containing useful functions) or one header file for each library of functions.
  The header file will contain the function declarations along with other parameter definitions and possible variable declarations (yes, remember that you also need to declare variables in C++ before you can use them ?)
- Therefore, the typical things in a header file are:
  - Constant definitions (such as #define PI 3.1415)
  - Declaration of global variables (such as extern int myVar;)
    The global variables are defined outside any function - they will be discussed later: see click here
  - Declaration of functions (such as extern float f(float);)
    Function declarations are sometimes called "function prototypes".
How to organize your functions
There are 2 ways to organize your functions:
1. Using object files
2. Using library files

Organize your functions using object files

How to setup your function library
1. Create a directory to store your library file
  The typical name would be /home/username/lib
2. Pre-compile your functions into object file using the -c compile option
  We have seen this before. Suppose you have a number of functions in the file myLibFile1.C, you can pre-compile this file using:
```
  CC -c myLibFile1.C
 
```
3. Write a header file for the object file.

How to use your function library

Include the header files of your functions in the program source file using angular brackets:
#include <SomeHeaderFile> .... Your program...
Compile each source file using the -IdirectoryPath option to include your library directory
Typically, you would use:
CC -c -I/home/username/.../.../lib myFile1.C
Make sure you use the FULL pathname

After compiling all source files into corresponding object files using the command above, you must link all your object files along with all object files in lib that contain functions that you have used:

CC -o myProg myFile1.o myFile2.o ..... \ /home/username/.../.../lib/myLibFile1.o \ /home/username/.../.../lib/myLibFile2.o \ .... /home/username/.../.../lib/myLibFileN.o

Example:
- Save this object file (RectangleRule_Prec) in /home/username/lib: click here
- Save this header (RectangleRule_Prec) for the object file in the same directory /home/username/lib: click here
- Save this object file (RectangleRule) in /home/username/lib: click here
- Save this header (RectangleRule) for the object file in the same directory /home/username/lib: click here
- Save this program MAIN function in some other dirctory (say demo): click here
- You also need to save this f(x) function in demo to work: click here
- Compile:
  - CC -c rect-rule2b.C
    NOTE: f(x) does not use any library functions, so it does not need the -I option !
  - CC -c -I/home/username/lib rect-rule5.C
  - CC -o rect-rule5.o rect-rule2b.o \
    /home/username/lib/myLibFile1.o \
    /home/username/lib/myLibFile2.o

Organize your functions using LIBRARY files

How to setup your function library
1. Create a directory to store your source files
  You can use any directory name here....
2. Create a directory to store your library file(s)
  Again, the typical name would be /home/username/lib
3. Pre-compile your functions into object file using the -c compile option
  Example:
```
  CC -c myLibFile1.C
 
```
4. After you have compiled all your source files into object files, you can assemble all the object files into a library file using the following command:
  ar -rv libMyLib.a myLibFile1.o myLibFile2.o ...
  - ar is used to make "archives" or "library"
  - Option -r will replaces or adds files in archive. If archive file does not exist, a new archive file will be created.
  - Option -v will give "verbose" output (you can omit this option if you don't care for verbose output)
5. Write ONE SINGLE header file for every objects in the archive.
  In other words: write a header file that contains declarations in all the files (myFile1.o, myFile2.o, etc) that you used to create the library file.

How to use your function library

Include the header files of your functions in the program source file using angular brackets:
#include <SomeHeaderFile> .... Your program...
Compile each source file using the -IdirectoryPath option to include your library directory
Typically, you would use:
CC -c -I/home/username/.../.../lib myFile1.C
Make sure you use the FULL pathname

CC -o myProg \ (This renames output a.out) -L/home/username/.../.../lib \ (This adds to library path) myFile1.o myFile2.o ..... \ (These are the object files) -lMyLib (This is your library file)

Example:
- Save this object file (RectangleRule_Prec) in /home/username/lib: click here
- Save this object file (RectangleRule) in /home/username/lib: click here
- Create the library MyLib in /home/username/lib using this command:
  Normally, you would move the library file "libMyLib.a" to /home/username/lib, but since we built it in this directory, there is no need to move it...
- Save this header (RectangleRule+RectangleRule_Prec) for the file in the same directory /home/username/lib: click here
- Save this program MAIN function in some other dirctory (say demo): click here
  The difference between this MAIN function and the one shown before is the different header file included...
- You also need to save this f(x) function in demo to work: click here
- Compile:
  - CC -c rect-rule2b.C
    NOTE: f(x) does not use any library functions, so it does not need the -I option !
  - CC -c -I/home/username/lib rect-rule6.C
  - CC -o rect-rule6 -L/home/username/lib/ \
    rect-rule6.o rect-rule2b.o \
    -lMyLib