• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2    Copyright 2014 Renato Tegon Forti, Antony Polukhin.
3    Copyright 2015-2019 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)
6/]
7
8[section:getting_started Getting started]
9
10Boost.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.
11
12If you want to load a library, just construct [classref boost::dll::shared_library] class with a path to the library as a parameter:
13```
14boost::dll::shared_library lib("/test/boost/application/libtest_library.so");
15
16```
17Now you can easily import symbols from that library using the `get` and `get_alias` member functions:
18```
19int plugin_constant = lib.get<const int>("integer_variable");
20boost::function<int()> f = lib.get<int()>("function_returning_int");
21int& i = lib.get_alias<int>("alias_to_int_variable");
22```
23In case of `boost::dll::shared_library` it is safe to use imported symbols only until `boost::dll::shared_library`
24instance is not destroyed.
25
26Query libraries using [classref boost::dll::library_info] and get symbol infos using [funcref boost::dll::symbol_location],
27[funcref boost::dll::this_line_location] and [funcref boost::dll::program_location].
28
29For importing a single function or variable you may use a following one liners:
30[import ../example/getting_started.cpp]
31[import ../example/getting_started_library.cpp]
32
33```
34using namespace boost;
35
36// `extern "C"` - specifies C linkage: forces the compiler to export function/variable by a pretty (unmangled) C name.
37#define API extern "C" BOOST_SYMBOL_EXPORT
38```
39[table:starting
40[[ Import (code that uses DLL/DSL): ] [ Export (DLL/DSL sources): ] [ Functions description: ]]
41[
42    [ [getting_started_imports_cpp11_function] ]
43    [ [getting_started_exports_cpp11_function] ]
44    [ [funcref boost::dll::import import<T>(...)] ]
45][
46    [ [getting_started_imports_cpp_variable] ]
47    [ [getting_started_exports_cpp_variable] ]
48    [ [funcref boost::dll::import import<T>(...)] ]
49][
50    [ [getting_started_imports_alias] ]
51    [ [getting_started_exports_alias] ]
52    [
53        [funcref boost::dll::import_alias import_alias<T>(...)]
54
55        [macroref BOOST_DLL_ALIAS]
56    ]
57][/
58    [ [getting_started_imports_c_function] ]
59    [ [getting_started_exports_c_function] ]
60    [ [funcref boost::dll::import import<T>(...) ] ]
61/][/
62    [ [getting_started_imports_c_variable] ]
63    [ [getting_started_exports_c_variable] ]
64    [ [funcref boost::dll::import import<T>(...) ] ]
65/]]
66
67It 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
68internally hold a reference to the shared library.
69
70[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.
71
72[note On Linux/POSIX/MacOS link with library "dl". "-fvisibility=hidden" flag is also recommended.]
73
74[endsect]
75