ceph/src/boost/libs/dll/doc/getting_started.qbk

   1 [/
   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)
   6 /]
   7
   8 [section:getting_started Getting started]
   9
  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.
  11
  12 [import ../example/getting_started.cpp]
  13 [import ../example/getting_started_library.cpp]
  14
  15 ```
  16 using namespace boost;
  17
  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
  20 ```
  21 [table:starting
  22 [[ Import (code that uses DLL/DSL): ] [ Export (DLL/DSL sources): ] [ Functions description: ]]
  23 [
  24     [ [getting_started_imports_cpp11_function] ]
  25     [ [getting_started_exports_cpp11_function] ]
  26     [ [funcref boost::dll::import import<T>(...)] ]
  27 ][
  28     [ [getting_started_imports_cpp_variable] ]
  29     [ [getting_started_exports_cpp_variable] ]
  30     [ [funcref boost::dll::import import<T>(...)] ]
  31 ][
  32     [ [getting_started_imports_alias] ]
  33     [ [getting_started_exports_alias] ]
  34     [
  35         [funcref boost::dll::import_alias import_alias<T>(...)]
  36
  37         [macroref BOOST_DLL_ALIAS]
  38     ]
  39 ][/
  40     [ [getting_started_imports_c_function] ]
  41     [ [getting_started_exports_c_function] ]
  42     [ [funcref boost::dll::import import<T>(...) ] ]
  43 /][/
  44     [ [getting_started_imports_c_variable] ]
  45     [ [getting_started_exports_c_variable] ]
  46     [ [funcref boost::dll::import import<T>(...) ] ]
  47 /]]
  48
  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.
  51
  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.
  53
  54 [note On Linux/POSIX/MacOS link with library "dl". "-fvisibility=hidden" flag is also recommended.]
  55
  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:
  58 ```
  59 boost::dll::shared_library lib("/test/boost/application/libtest_library.so");
  60
  61 ```
  62 Now you can easily import symbols from that library using the `get` and `get_alias` member functions:
  63 ```
  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");
  67 ```
  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.
  70
  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].
  73
  74 [endsect]