Skip to content

Latest commit

 

History

History
146 lines (100 loc) · 3.8 KB

README.md

File metadata and controls

146 lines (100 loc) · 3.8 KB
Raw

dynalo: dynamic loading of shared libraries

dynalo is a header-only library that provides a cross platform API for:

  • Loading and unloading a shared library (.so in Linux and .dll in Windows)
  • Getting a pointer to exported functions in the loaded shared library

API Summary

Everything is inside the dynalo namespace which is defined in the dynalo/dynalo.hpp header.

  • Load a shared library

    native::handle open(const std::string& dyn_lib_path);

  • Unload a shared library

    void close(native::handle lib_handle);

  • Look up a function in the shared library and return a pointer to it

    template <typename FunctionSignature>
FunctionSignature* get_function(native::handle lib_handle, const std::string& func_name);

  • Wrapper class (excerpt)

    class library
{
public:
    /// Loads a shared library using dynalo::open
    explicit library(const std::string& dyn_lib_path);

    /// Unloads the shared library using dynalo::close
    ~library();

    /// Returns a pointer to the @p func_name function using dynalo::get_function
    template <typename FunctionSignature>
    FunctionSignature* get_function(const std::string& func_name);
};

  • Generate a valid shared library file name

    • On Linux: Convert awesome to libawesome.so
    • On Windows: Convert awesome to awesome.dll
    std::string to_native_name(const std::string& lib_name);

Example

This is a simple example of a shared library that exports some functions and a program that dynamically loads the library then calls its exported functions.

See the test folder for details on how to compile.

Shared Library

  • shared.hpp

    // symbol_helper.hpp: helper macros that define the boiler plate for exporting functions
#define DYNALO_EXPORT_SYMBOLS
#include <dynalo/symbol_helper.hpp>

#include <cstdint>

DYNALO_EXPORT int32_t DYNALO_CALL add_integers(const int32_t a, const int32_t b);
DYNALO_EXPORT void DYNALO_CALL print_message(const char* message);

  • shared.cpp

    #include "shared.hpp"

#include <iostream>

DYNALO_EXPORT int32_t DYNALO_CALL add_integers(const int32_t a, const int32_t b)
{
    return a + b;
}

DYNALO_EXPORT void DYNALO_CALL print_message(const char* str)
{
    std::cout << "Hello [" << str << "]" << std::endl;
}

Dynamic Loading

  • loader.cpp

    #include <dynalo/dynalo.hpp>

#include <cstdint>
#include <sstream>

// usage: loader "path/to/lib/folder"
int main(int argc, char* argv[])
{
    dynalo::library lib(std::string(argv[1]) + "/" + dynalo::to_native_name("shared"));

    auto add_integers  = lib.get_function<int32_t(const int32_t, const int32_t)>("add_integers");
    auto print_message = lib.get_function<void(const char*)>("print_message");

    std::ostringstream oss;
    oss << "it works: " << add_integers(1, 2);

    print_message(oss.str().c_str());  // prints: Hello [it works: 3]
}

Dependencies

  • C++11 compiler: Mainly for the using and auto keywords. Open an issue or submit a PR if you need support for C++98)
  • Linux: libdl (link with -ldl)
  • Windows: kernel32.lib

Installation

Using CMake

# create and cd to the build folder
mkdir build
cd build

# configure
cmake [-DCMAKE_INSTALL_PREFIX="path/to/install/dir"] [-DCMAKE_BUILD_TYPE=(Debug|Release|...)] ..

# install
cmake --build . [--config (Debug|Release|...)] --target install

Manual Installation

dynalo is a header-only library. Therefore, you can simply copy the content of the include folder into your project. (just remember to link with the proper libs as mentioned in "Dependencies")