2 Copyright 2014 Renato Tegon Forti, Antony Polukhin.
3 Copyright 2015-2016 Antony Polukhin.
4 Distributed under the Boost Software License, Version 1.0.
5 (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8 [section:getting_started Getting started]
10 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.
12 [import ../example/getting_started.cpp]
13 [import ../example/getting_started_library.cpp]
16 using namespace boost;
18 // `extern "C"` - specifies C linkage: forces the compiler to export function/variable by a pretty (unmangled) C name.
19 #define API extern "C" BOOST_SYMBOL_EXPORT
22 [[ Import (code that uses DLL/DSL): ] [ Export (DLL/DSL sources): ] [ Functions description: ]]
24 [ [getting_started_imports_cpp11_function] ]
25 [ [getting_started_exports_cpp11_function] ]
26 [ [funcref boost::dll::import import<T>(...)] ]
28 [ [getting_started_imports_cpp_variable] ]
29 [ [getting_started_exports_cpp_variable] ]
30 [ [funcref boost::dll::import import<T>(...)] ]
32 [ [getting_started_imports_alias] ]
33 [ [getting_started_exports_alias] ]
35 [funcref boost::dll::import_alias import_alias<T>(...)]
37 [macroref BOOST_DLL_ALIAS]
40 [ [getting_started_imports_c_function] ]
41 [ [getting_started_exports_c_function] ]
42 [ [funcref boost::dll::import import<T>(...) ] ]
44 [ [getting_started_imports_c_variable] ]
45 [ [getting_started_exports_c_variable] ]
46 [ [funcref boost::dll::import import<T>(...) ] ]
49 It is safe to use imported variable or function because the variables returned from [funcref boost::dll::import import<T>(...)] and [funcref boost::dll::import_alias import_alias<T>(...)] functions
50 internally hold a reference to the shared library.
52 [macroref 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.
54 [note On Linux/POSIX/MacOS link with library "dl". "-fvisibility=hidden" flag is also recommended.]
56 If you need a low level API [classref boost::dll::shared_library] will suit you. If you want to load a library,
57 just construct that class with a path to the library as a parameter:
59 boost::dll::shared_library lib("/test/boost/application/libtest_library.so");
62 Now you can easily import symbols from that library using the `get` and `get_alias` member functions:
64 int plugin_constant = lib.get<const int>("integer_variable");
65 boost::function<int()> f = lib.get<int()>("function_returning_int");
66 int& i = lib.get_alias<int>("alias_to_int_variable");
68 In case of `boost::dll::shared_library` it is safe to use imported symbols only until `boost::dll::shared_library`
69 instance is not destroyed.
71 Query libraries using [classref boost::dll::library_info] and get symbol infos using [funcref boost::dll::symbol_location],
72 [funcref boost::dll::this_line_location] and [funcref boost::dll::program_location].