Saturday, July 2, 2011

Creating and Using C++ shared libraries using g++

It's been an eventful couple of months. I worked my first 90+ hour week, will be moving for a second time, and learned a heck of a lot about C++.
In this post, I will explain in simplified terms, how to create your own C++ shared Library.

It took me a couple hours to figure it out. It's not exactly straightforward, but neither is it overly complex.

I assume that you, the reader, have experience writing C++ classes and headers. 

Step 1: Create your library

Before you go and build a gigantic, powerful library, it is better to create something simple to start, then build upon it. I used a header file in addition to my c++ class file.
I'd recommend writing a simple class with just a constructor, deconstructor, and a method that outputs something like "Hello World" using cout.

Libraries do NOT contain a main() method.

Step 2: Compile your library

The following code will compile your .cpp file as a shared library. Replace the file names and library names with your own.
Be sure to name your library lib[name].so.
It needs the lib prefix and .so suffix. If you have multiple version of your library, the suffix can be .so.1, .so.1.0, .so.1.0.5, etc. as long as one with .so exists.
 g++ -Wall -shared -fPIC -o ~/libs/ libmylibrary.cpp

The format goes like this: g++ [options] [library placement on filesystem] [file(s) that make up library] 

I also had a ~/libs/ folder created so I could compile and install as user. If you want system-wide access, run the command as root and use "-o /usr/local/lib/".

Step 3: Test your library

Now the fun part:
Create a test file (test.cpp) with just a main() method.

You will have to include the library in the file like so:
#include "libmylibrary.h"

If you are using a namespace in your library, be sure to use it or prefix any methods or constructors with it.

In your main() method, create an instance of the object, call its method(s), and delete it at the end. An example would be so:

ExampleObj * myobj = new ExampleObject();
delete myobj;

Now the best part: Compiling your program and linking it to your library. Do so with this command:

g++ main.cpp -o ~/bin/libtest -L$HOME/libs -lmylibrary

A couple IMPORTANT things to note here:

  • ~/bin/ is a directory I created. You may have to change location or create the directory yourself
  • The -l command which links the library has omitted the "lib" prefix, so it is mylibrary instead of libmylibrary.
That last point is what really fooled me for a while. 

That's all for c++ libraries. I hope this helps.


You may have to add the following around the body of your header file.

This goes after the include statements, but before the namespace/class declarations

#ifdef __cplusplus
extern "C"

And after end of namespace/class declarations, but before final #endif tag:

#ifdef __cplusplus

This should fix some c++ specific issues you may encounter.


Sabino said...

This kind of post that go straight to the problem are the best. Well written.

!=42 said...

Very good post. Would be good to have the simple example files you tested with. +1!!

Winston Siu said...

simple yet very useful

Melvyn Drag said...

Thanks for the clear example!

Debashish said...

I don't want to use extern C because I have overloaded functions. How to proceed?