1. © Janice Regan, CMPT 102, Sept. 2006 0 CMPT 102 Introduction to Scientific Computer Programming Building User Libraries

2. © Janice Regan, CMPT 102, Sept. 2006 1 Using C libraries: example  To tell the compiler the C standard input and output library is to be used in your code (stdio) you must start your program with the preprocessor command #include  Remember the preprocessor runs before the compiler.  It finds the file stdio.h, which contains all the necessary declarations of variables and functions needed to use the functions in the standard IO library.  It replaces the line of code above with the contents of the stdio.h file before the compiler begins to compile your program.

3. © Janice Regan, CMPT 102, Sept. 2006 2 Using user C Libraries: example  To tell the compiler to use your own library libsorts.a or libsorts.so you must use a preprocessor command before the other code in your main program #include “sorts.h” OR #include “/home/jregan/include/sorts.h”  The preprocessor runs before the compiler.  It finds the file sorts.h which contains all the necessary declarations of variables and functions needed to use the functions in the sorts library.  It replaces the line of code above with the contents of the sorts.h file before the compiler begins to compile your program.

4. © Janice Regan, CMPT 102, Sept. 2006 3 How to choose ? #include “sorts.h” OR #include “/home/jregan/include/sorts.h”  The first include statement will look for the file sorts.h in the directory in which the code containing the statement above is compiled and run  The second include statement will look for the file sorts.h in the directory indicated by the path. Therefore, the code using the included file can be compiled and used anywhere.

5. © Janice Regan, CMPT 102, Sept. 2006 4 Where should libraries be  C system libraries are found in several places including /usr/lib in a Linux system  When use say #include the <> indicate that the these libraries can be found in the directories that hold all the C language libraries (like /usr/lib in a Linux system)  If you look at these libraries you will see that they come in two types  Libname.a  Libname.so

6. © Janice Regan, CMPT 102, Sept. 2006 5 Types of Libraries (1)  libname.a  These libraries are called static libraries  When you link your program, the object file for the whole library is added to the executable for your program.  If you use many libraries, or any large libraries you executable can become very large

7. © Janice Regan, CMPT 102, Sept. 2006 6 Types of Libraries (2)  libname.so  These libraries are called shared libraries  A single shared copy of the compiled executable for the library is made. The object file from the library is not added to your own executable when it is linked, only a reference to the location of the shared executable for the library is added.  If you use many libraries, or any large libraries using shared libraries rather than static libraries will reduce the size of your executable

8. © Janice Regan, CMPT 102, Sept. 2006 7 When are static libraries better?  If you distribute your executable to other machines The shared library must also be present on all systems you distribute the executable to. If the shared library is not available on the machine you moved your executable to, or if it is in a different place, the executable will not be able to find the shared library or run Static libraries may be appropriate when you know you want to move executables between machines

9. © Janice Regan, CMPT 102, Sept. 2006 8 Building your own library  You need to write three different files to build and use a library. Consider a library containing several sorting functions  Need a header file (include file) sorts.h  Need an implementation file sorts.c  Need a main function, (and/or sortmain.c other functions) that use the functions in the sort library

10. © Janice Regan, CMPT 102, Sept. 2006 9 Header files  What belongs in a header file  Definitions of simple variables that are specific to the library. Example: the maximum size of the arrays of data to be sorted #define MAX_ARRAY_INDEX 700  Definitions of any structures or other user defined data types specific to the library.  A function declaration for each of the functions in the library. For example extern void InsertionSort( int Array[ ], int arrayLen); The extern keyword is used to indicate that the definitions of the function is in a different file from the declaration

11. © Janice Regan, CMPT 102, Sept. 2006 10 Header files: comments  In addition to the items discussed on the previous slide  A block of comments describing the purpose of the library should be the first thing in the header file  A block of comments describing the purpose of each function should precede the function declaration for that function. This block of comments should inform the user of the function of any constraints she is responsible for

12. © Janice Regan, CMPT 102, Sept. 2006 11 Implementation file  The implementation file contains  A block of comments indicating the purpose of the library. A library should contain only functions needed for a particular purpose  #include directives for any C system libraries used by the functions in the library  #include “sorts.h”  For each function in the library A block of comments indicating the purpose and usage of the function The function definition (the code for the function)

13. © Janice Regan, CMPT 102, Sept. 2006 12 Building your library (1)  First you need to compile your implementation file  You want to make an object file corresponding to your implementation file (sorts.c)  You do not want to link this object file with any other libraries or with the main function yet  To compile your implementation file gcc –c –o sorts.o sorts.c Note that if you are still debugging sorts.c you should add the –Wall option so that you can see warnings that will help you

14. © Janice Regan, CMPT 102, Sept. 2006 13 Building your library (2)  Next you want to transform your object (sorts.o) into a library.  If you want to make a static library (sorts.a) ar –sr libsorts.a sorts.o  If you want to make a shared library (sorts.so) gcc –shared –o sorts.so sorts.o

15. © Janice Regan, CMPT 102, Sept. 2006 14 Main function  Your main function, or some function that it calls (that is defined in the same file as the main function) will call one or more functions from the sorts library.  At the beginning of the file (before the start of the main program) in which the library is called the include directive below must be inserted #include “sorts.h”

16. © Janice Regan, CMPT 102, Sept. 2006 15 Compiling your main function  Your main function can be compiled and linked with your library as follows  These commands assume that the library is in directory /home/jregan/lib and the header file is in directory /home/jregan/include gcc –lm –I/home/jregan/include –L/home/jregan/lib –o sorts sortmain.c –lsorts  This assumes that you are using a shared library libsorts.so gcc -static –lm –I/home/jregan/include –o sorts sortmain.c /home/jregan/lib/libsorts.a  This assumes that you are using a static library

17. © Janice Regan, CMPT 102, Sept. 2006 16 Meaning of options  -I/home/jregan/include  Gives the path to the directory in which the header file is kept (-I/directoryname) The option is an upper case I  -L/home/jregan/include  Gives the path to the directory in which the library is kept. (-L/directoryname)  -static  Tells the compiler to use static libraries. In this case all libraries being used will be the static versions of the libraries, not just our own static library.