Getting started

| Home | Libraries | People | FAQ | More

## 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`

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`.