Adding Libraries

This page covers how to add a new library package to the uClinux distribution. It does not go over how to write your own libraries as that is covered in the creating_libraries document.

Here we will be integrating a fictitious library named libfoo. The steps involved are:

• Add the library source code
• Create a makefile for the library source code
• Add the library to the uClinux menus
• Add the library to the uClinux makefiles
• Test!

First create a new subdirectory under the uClinux-dist/lib/ tree and unpack the source code into that.

rgetz@pinky:~/blackfin-trunk/uClinux-dist/> mkdir lib/libfoo/
rgetz@pinky:~/blackfin-trunk/uClinux-dist/> cd lib/libfoo/
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> wget http://downloads.libfoo.org/libfoo.tar.bz2
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> tar pxf ./libfoo.tar.bz2
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> rm ./libfoo.tar.bz2
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> ls -l
total 12
drwxr-xr-x 8 rgetz users 4096 2008-04-07 08:51 libfoo-1.2.13

All of the source files should now be in in the lib/libfoo/ directory.

If you are not familiar with makefiles, please read our make document.

The uClinux build system needs to know about four targets:

• all: compile the library
• clean: delete the compiled object files
• distclean: clean out all generated files
• romfs: install into the uClinux-dist/romfs/ dir

So you should add a Makefile (or customize an existing one) so that these targets are respected. There are three types of build systems, and the uClinux dist handles them all.

• ones that use autotools (like ./lib/libsdl/Makefile)
• ones that pretend to use autotools (like ./lib/libssl/Makefile)
• ones that don't use any auto configuration system (like ./lib/crypto++lib/Makefile)

rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> find ./ -name “config.sub”
./libfoo-1.2.13/config.sub
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> grep bfin ./libfoo-1.2.13/config.sub
        | bfin \
        | bfin-* | bs2000-* \
This is good - if it does not return this, you need to do copy the existing config.sub and config.guess from the ./tools dir to the source directory
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> cp ../../tools/config.sub ./libsdl/SDL-1.2.13/build-scripts/config.sub
Only copy config.guess if you needed to update config.sub
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> find ./ -name “config\.guess”
./libfoo-1.2.13/config.guess
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> cp ../../tools/config.guess ./libfoo-1.2.13/config.guess

rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> cp ../libsdl/Makefile ./Makefile
rgetz@pinky:~/blackfin-trunk/uClinux-dist/lib/libfoo/> vim ./Makefile

If your library will be installing files into the romfs dir, then there are two helper variables for you:

• $(ROMFSINST): script to install files
• $(ROMFSDIR): absolute path to uClinux-dist/romfs/

Some common tricks involve using the -e flag so that you only install the specified file when a configure feature is enabled:

romfs:
	$(ROMFSINST) -e CONFIG_LIB_LIBFOO_FORCE src/libfoo.so /lib/libfoo.so

Here we will only install the src/libfoo.so library into uClinux-dist/romfs/lib/libfoo.so if the CONFIG_LIB_LIBFOO_FORCE option has been selected.

Once you have added the source and the makefile, you can try it out to see if things are working properly.

uClinux-dist> make lib/libfoo_only

In order for your library to show up in the uClinux menu system, you'll need to teach the build system about it. Just pop open the uClinux-dist/lib/Kconfig.local file and go down to the Library Configuration option.

# Libraries that are in Blackfin dist but not upstream

comment "*** Additional Blackfin dist libs ***"

config LIB_AGG
        bool "Build agg"
        help
          Anti-Grain Geometry - A High Quality Rendering Engine for C++

          http://antigrain.com/

When you are adding your library, always try to add a help section, indicating where upstream is.

The last step here is to make sure when you run make, the uClinux build system will include your library when needed. Open up the uClinux-dist/lib/Makefile.local file and add lines such as:

dir_$(CONFIG_LIB_LIBFOO)       += libfoo

Make sure you place these lines with the others in the makefile.

Once you've made these changes, it's time for that fun part called testing.

First make sure the library shows up in the menuconfig system by running make config_menuconfig. Hopefully you should see something like:

Core Applications --->
  --- Force build (Normally built when required)
  [*] Build libfoo

Select your library and then exit out saving the config file.

Now make sure the compile step works by running make. If you get an error, go figure out what's wrong :).

Finally make sure the library was installed into the romfs dir. If the library does not install anything, you can of course skip this step.

If you want to also include a custom application that will be utilizing this new library, then you just need to: <hmm i should write this section once i figure this out>