Building External Element Libraries

MUCH OF THIS INFORMATION IS OBSOLETE - NEW DOCUMENTATION IS UNDER DEVELOPMENT

While SST comes with a significant number of built-in element libraries, it is useful to be able to develop custom element libraries external to SST, and use them inside SST-based simulations. This page documents the process for building Element Libraries outside of the SST source tree. For information regarding how to design and create Element Libraries (inside or external to SST), please see Integrate your Element with SST.

SST Package Configuration

When SST was installed, a pkg-config configuration file was generated and installed under $prefix/lib/pkgconfig. If SST was installed into /usr/local/ or /usr/, then this file should be easily found by pkg-config. If SST was installed into another directory, that path should be appended to your $PKG_CONFIG_PATH environment variable.

export PKG_CONFIG_PATH=/path/to/SST/lib/pkgconfig:${PKG_CONFIG_PATH}

If pkg-config is not installed on your system, then you will need to note the directory where the libraries were installed, $prefix/lib/ and $prefix/lib/sst/; as well as the header directories, $prefix/include/ and $prefix/include/sst/.

Compilation flags

Compilation Flags

Your source code should be compiled with the flags given by pkg-config --cflags for SST, as well as a flag to create position-independent code. This is typically -fPIC, and is usually required when compiling a shared library.

Linking Flags

When linking the shared library, the flags given by pkg-config --libs should be used, as well as any flags needed by your compiler to create a shared library. For GCC and Clang, the following would be sufficient: -shared -fno-common.

Running

Once you have built your element library, it needs to be somewhere that SST can find it in order to use it. By default, SST looks in $prefix/lib/sst/ for element libraries, and then the rest of the standard library paths, as defined by your system. This can include paths referenced in the $LD_LIBRARY_PATH environment variable. In addition, SST can take an argument --add-lib-path <path> to add search paths.

For example, if your library was built in the current directory, you could run:

$ sst --add-lib-path `pwd` myConfig.py

Sample Makefile

The following makefile assumes that the SST package configuration file can be found by pkg-config, and is compiling myLibrary.cc into libmyLibrary.so.


LDFLAGS=-shared -fno-common ${shell pkg-config SST-4.0 --libs}
CXXFLAGS=-g -O2 -fPIC ${shell pkg-config SST-4.0 --cflags}


.PHONY: clean all

all: libmyLibrary.so

libmyLibrary.so: myLibrary.o
    ${CXX} ${CPPFLAGS} ${LDFLAGS} $< -o $@

clean:
    ${RM} *.o libmyLibrary.so