Getting started

Boost.DLL is a header only library. To start with the library you only need to include <boost/dll.hpp> header. After that you are free to import and export functions and variables. Importing code requires linking with boost_filesystem and boost_system libraries.

using namespace boost;

// `extern "C"` - specifies C linkage: forces the compiler to export function/variable by a pretty (unmangled) C name.
#define API extern "C" BOOST_SYMBOL_EXPORT

Import (code that uses DLL/DSL):	Export (DLL/DSL sources):	Functions description:
// Importing function. auto cpp11_func = dll::import<int(std::string&&)>( path_to_shared_library, "i_am_a_cpp11_function" );	namespace some_namespace { API int i_am_a_cpp11_function(std::string&& param) noexcept; // ^-------------------- function name to use in dll::import<> }	`import<T>(...)`
// Importing variable. shared_ptr<std::string> cpp_var = dll::import<std::string>( path_to_shared_library, "cpp_variable_name" );	namespace your_project_namespace { API std::string cpp_variable_name; }	`import<T>(...)`
// Importing function by alias name auto cpp_func = dll::import_alias<std::string(const std::string&)>( path_to_shared_library, "pretty_name" );	namespace some_namespace { std::string i_am_function_with_ugly_name(const std::string& param) noexcept; } // When you have no control over function sources or wish to specify another name. BOOST_DLL_ALIAS(some_namespace::i_am_function_with_ugly_name, pretty_name)	`import_alias<T>(...)` `BOOST_DLL_ALIAS`

Import (code that uses DLL/DSL):

Export (DLL/DSL sources):

Functions description:

// Importing function.
auto cpp11_func = dll::import<int(std::string&&)>(
        path_to_shared_library, "i_am_a_cpp11_function"
    );

namespace some_namespace {
    API int i_am_a_cpp11_function(std::string&& param) noexcept;
//          ^--------------------  function name to use in dll::import<>
}

import<T>(...)

// Importing  variable.
shared_ptr<std::string> cpp_var = dll::import<std::string>(
        path_to_shared_library, "cpp_variable_name"
    );

namespace your_project_namespace {
    API std::string cpp_variable_name;
}

import<T>(...)

// Importing function by alias name
auto cpp_func = dll::import_alias<std::string(const std::string&)>(
        path_to_shared_library, "pretty_name"
    );

namespace some_namespace {
    std::string i_am_function_with_ugly_name(const std::string& param) noexcept;
}

// When you have no control over function sources or wish to specify another name.
BOOST_DLL_ALIAS(some_namespace::i_am_function_with_ugly_name, pretty_name)

import_alias<T>(...)

BOOST_DLL_ALIAS

It is safe to use imported variable or function because the variables returned from import<T>(...) and import_alias<T>(...) functions internally hold a reference to the shared library.

BOOST_SYMBOL_EXPORT is just a macro from Boost.Config that expands into the __declspec(dllexport) or __attribute__((visibility("default"))). You are free to use your own macro for exports.

	Note
	On Linux/POSIX/MacOS link with library "dl". "-fvisibility=hidden" flag is also recommended.

If you need a low level API boost::dll::shared_library will suit you. If you want to load a library, just construct that class with a path to the library as a parameter:

boost::dll::shared_library lib("/test/boost/application/libtest_library.so");

Now you can easily import symbols from that library using the get and get_alias member functions:

int plugin_constant = lib.get<const int>("integer_variable");
boost::function<int()> f = lib.get<int()>("function_returning_int");
int& i = lib.get_alias<int>("alias_to_int_variable");

In case of boost::dll::shared_library it is safe to use imported symbols only until boost::dll::shared_library instance is not destroyed.

Query libraries using boost::dll::library_info and get symbol infos using boost::dll::symbol_location, boost::dll::this_line_location and boost::dll::program_location.