Mystery of the Shared Library - Solved!

The first technical problem to solve for the ONF submission was figuring out the naming and compiling of a shared library. The second was to link it with the application (SDN controller).

The secret sauce is the Makefile. Below are the instructions. The complete code is available here. Go ahead and test it out.

1. The naming: These names have very specific use while installing the library. Take notice.

major version: Anytime the API changes, the major version needs to increment. Numbering starts at zero.

minor version: Any upgrades to the library that does not have API changes increments the minor version. Numbering starts at zero.

name:  Pick the name you want to be used in the -l switch when linking this with the application.
In the github example, this is smalle.

library name: lib<name>.so
In the github example, this is libsmalle.so.

soname: lib<name>.so.<major ver>
In the github example, this is libsmalle.so.0

real name: lib<name>.so.<major ver>.<minor ver>
In the github example, this is libsmalle.so.0.0.

The library is compiled to create a file with the real name. The soname and library names are symlinks created at the time of installing the library.

2. GCC flags:
Sources are compiled to object files using CFLAGS with gcc. The must-have CFLAGS for a shared library are:
CFLAGS := -fPIC -Wl,-export-dynamic

fPIC - generates position independent code.The alternative is fpic which is not supported on all platforms.

-Wl,-export-dynamic - passes the export-dynamic flag to linker. This is required to support callbacks in the library.

The object files are linked to final library ELF with 'real name' as the filename. GCC with LDFLAGs achieve this. The necessary LDFLAGS for a shared library are: 

LDFLAGS := -shared -Wl,-soname,$(SONAME) 

3. Installing the library:

Copy the shared library file to /usr/local/lib and run ldconfig to install it. Add the path /usr/local/lib to environment variable LD_LIBRARY_PATH. Copy the library header to /usr/local/include. 

4. Linking to the library:

Compile the application with -l<name> and -I/usr/local/include.
Make sure you #include the header in the application code.

Reference:
http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html