...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
If you want to load a library, just construct boost::dll::shared_library
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
.
For importing a single function or variable you may use a following one liners:
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<> }
|
|
// 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; }
|
|
// 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)
|
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. |