Building and Using Libraries

1. Building and Using Libraries CISC/QCSE 810

2. Libraries • libraries exist for many common scientific tasks • linear algebra – BLAS/ATLAS, LAPACK • optimization – OPT++, TAO • Fourier transforms – FFTW, FFTPACK • image processing - Imagemagick • data management – MySQL • programming aids – Boost • GUIs – Microsoft, Xwindows • Tons more in C, or C++, or Java…

3. How you would use a library

4. Example: Imagemagick • combination of library and executables • contains routines for image processing

5. Obtaining the Source • Libraries are binary files • Not transferable from OS to OS • Not necessarily optimized for a particular system • Typical to need to recompile on most Unix-based • Look for "source" or "tarball" ".tar.gz"

6. TAR files • TAR (Tape ARchive) files are most common Unix-based way to pass around directories of source code • Think "zip", but for unix • Unix utility with staggering number of options

7. Common TAR scenarios • Unpacking a gzipped tar file (.tar.gz) • tar xvzf <filename> • x – extract, v – verbose, z – gzipped, • f – file to act on • List files in a gzipped tar file • tar tvf <filename> • Create a tar file • tar cvf mfile.tar <files to include>

8. Imagemagick • Located at • www.imagemagick.org/script/install-source.hph#unix • Find the file • ImageMagick.tar.gz • Download it to your local drive • move to a directory without spaces in Cygwin e.g. /cygdrive/c • Untar • tar xvzf ImageMagick.tar.gz

9. Read the Readme! • There are standard steps many libraries use for building • ./configure • make • make test • make install • but that may not be the case for yours • always look for installation instructions

10. This will take awhile… • Configuring and compiling libraries can be a process of minutes to hours to overnight (hopefully not longer!) • Have something else to do…

11. Assuming it worked • If you successfully compiled and installed the library, you should now have • header file(s) (.h) somewhere accessible • a library file (.a) somewhere accessible • Those extensions are for C, C++ libraries in Unix

12. Next Step: building a program • You now want to try to link your own source files to the library • Start with a worked example from the library writers! • If that doesn't work, you know it's a configuration/linking problem

13. Imagemagick • Comes with a thumbnail-generating program as a model • Save as wand.c

14. Compiling against a library • Look for –I flags in gcc command • these add a search directory for "include" files • your source will have to "#include<library>" before you can use a library function • ImageMagick 'make install' puts header files in /usr/include and subdirectories

15. Linking against a library • Next step to is link the objects into an executable • Look for flags • -L: add a search directory for library files • -l: adds a library to the executable • -lpng links code to libpng.a library file • Most libraries found in /usr/lib or /usr/local/lib

16. Library Realities • Building a library can be one of the most frustrating computer experiences • you didn't write it • whoever did may not have had your system at hand (or in mind) • problems will tend to be at most esoteric level (compiler, OS, make, etc. behaving slightly differently than expected) • Library writers are experienced C coders, while you may not be

17. Hope is not lost • Google is your best friend • search for the exact error message • someone else has probably had it • search for your OS in the library's web site • most problems are often due to OS-specific issues • Be patient • a library could save you weeks to months of coding and testing; a few days to install isn't too much to ask

18. Your next task • Find a library that might be of use to you (FFT, image processing, genetic algorithms, optimization), and build their example code OR • Build some source code and link it into MATLAB (or Java)