blob: acc6ee13d67a7f1c77dd0220f476e05de1c83fd2 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Getting started</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../boost_dll.html" title="Chapter 14. Boost.DLL">
<link rel="prev" href="../boost_dll.html" title="Chapter 14. Boost.DLL">
<link rel="next" href="tutorial.html" title="Tutorial">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../boost_dll.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_dll.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_dll.getting_started"></a><a class="link" href="getting_started.html" title="Getting started">Getting started</a>
</h2></div></div></div>
<p>
Boost.DLL is a header only library. To start with the library you only need
to include <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">dll</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> header.
After that you are free to import and export functions and variables. Importing
code requires linking with <code class="computeroutput"><span class="identifier">boost_filesystem</span></code>
and <code class="computeroutput"><span class="identifier">boost_system</span></code> libraries.
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">;</span>
<span class="comment">// `extern "C"` - specifies C linkage: forces the compiler to export function/variable by a pretty (unmangled) C name.</span>
<span class="preprocessor">#define</span> <span class="identifier">API</span> <span class="keyword">extern</span> <span class="string">"C"</span> <span class="identifier">BOOST_SYMBOL_EXPORT</span>
</pre>
<p>
</p>
<div class="informaltable">
<a name="boost_dll.getting_started.starting"></a><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Import (code that uses DLL/DSL):
</p>
</th>
<th>
<p>
Export (DLL/DSL sources):
</p>
</th>
<th>
<p>
Functions description:
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="comment">// Importing function.</span>
<span class="keyword">auto</span> <span class="identifier">cpp11_func</span> <span class="special">=</span> <span class="identifier">dll</span><span class="special">::</span><span class="identifier">import</span><span class="special"><</span><span class="keyword">int</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&&)>(</span>
<span class="identifier">path_to_shared_library</span><span class="special">,</span> <span class="string">"i_am_a_cpp11_function"</span>
<span class="special">);</span>
</pre>
<p>
</p>
</td>
<td>
<p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="keyword">namespace</span> <span class="identifier">some_namespace</span> <span class="special">{</span>
<span class="identifier">API</span> <span class="keyword">int</span> <span class="identifier">i_am_a_cpp11_function</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&&</span> <span class="identifier">param</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
<span class="comment">// ^-------------------- function name to use in dll::import<></span>
<span class="special">}</span>
</pre>
<p>
</p>
</td>
<td>
<p>
<code class="computeroutput"><a class="link" href="../boost/dll/import.html" title="Function import">import<T>(...)</a></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="comment">// Importing variable.</span>
<span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">cpp_var</span> <span class="special">=</span> <span class="identifier">dll</span><span class="special">::</span><span class="identifier">import</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span>
<span class="identifier">path_to_shared_library</span><span class="special">,</span> <span class="string">"cpp_variable_name"</span>
<span class="special">);</span>
</pre>
<p>
</p>
</td>
<td>
<p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="keyword">namespace</span> <span class="identifier">your_project_namespace</span> <span class="special">{</span>
<span class="identifier">API</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">cpp_variable_name</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
</td>
<td>
<p>
<code class="computeroutput"><a class="link" href="../boost/dll/import.html" title="Function import">import<T>(...)</a></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="comment">// Importing function by alias name</span>
<span class="keyword">auto</span> <span class="identifier">cpp_func</span> <span class="special">=</span> <span class="identifier">dll</span><span class="special">::</span><span class="identifier">import_alias</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&)>(</span>
<span class="identifier">path_to_shared_library</span><span class="special">,</span> <span class="string">"pretty_name"</span>
<span class="special">);</span>
</pre>
<p>
</p>
</td>
<td>
<p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="keyword">namespace</span> <span class="identifier">some_namespace</span> <span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">i_am_function_with_ugly_name</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span> <span class="identifier">param</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">// When you have no control over function sources or wish to specify another name.</span>
<span class="identifier">BOOST_DLL_ALIAS</span><span class="special">(</span><span class="identifier">some_namespace</span><span class="special">::</span><span class="identifier">i_am_function_with_ugly_name</span><span class="special">,</span> <span class="identifier">pretty_name</span><span class="special">)</span>
</pre>
<p>
</p>
</td>
<td>
<p>
<code class="computeroutput"><a class="link" href="../boost/dll/import_alias.html" title="Function import_alias">import_alias<T>(...)</a></code>
</p>
<p>
<code class="computeroutput"><a class="link" href="../BOOST_DLL_ALIAS.html" title="Macro BOOST_DLL_ALIAS">BOOST_DLL_ALIAS</a></code>
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
It is safe to use imported variable or function because the variables returned
from <code class="computeroutput"><a class="link" href="../boost/dll/import.html" title="Function import">import<T>(...)</a></code>
and <code class="computeroutput"><a class="link" href="../boost/dll/import_alias.html" title="Function import_alias">import_alias<T>(...)</a></code>
functions internally hold a reference to the shared library.
</p>
<p>
<code class="computeroutput">BOOST_SYMBOL_EXPORT</code> is just
a macro from Boost.Config that expands into the <code class="computeroutput"><span class="identifier">__declspec</span><span class="special">(</span><span class="identifier">dllexport</span><span class="special">)</span></code> or <code class="computeroutput"><span class="identifier">__attribute__</span><span class="special">((</span><span class="identifier">visibility</span><span class="special">(</span><span class="string">"default"</span><span class="special">)))</span></code>. You are free to use your own macro for
exports.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
On Linux/POSIX/MacOS link with library "dl". "-fvisibility=hidden"
flag is also recommended.
</p></td></tr>
</table></div>
<p>
If you need a low level API <code class="computeroutput"><a class="link" href="../boost/dll/shared_library.html" title="Class shared_library">boost::dll::shared_library</a></code>
will suit you. If you want to load a library, just construct that class with
a path to the library as a parameter:
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">dll</span><span class="special">::</span><span class="identifier">shared_library</span> <span class="identifier">lib</span><span class="special">(</span><span class="string">"/test/boost/application/libtest_library.so"</span><span class="special">);</span>
</pre>
<p>
Now you can easily import symbols from that library using the <code class="computeroutput"><span class="identifier">get</span></code> and <code class="computeroutput"><span class="identifier">get_alias</span></code>
member functions:
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">plugin_constant</span> <span class="special">=</span> <span class="identifier">lib</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">>(</span><span class="string">"integer_variable"</span><span class="special">);</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span><span class="special"><</span><span class="keyword">int</span><span class="special">()></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">lib</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="keyword">int</span><span class="special">()>(</span><span class="string">"function_returning_int"</span><span class="special">);</span>
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">lib</span><span class="special">.</span><span class="identifier">get_alias</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="string">"alias_to_int_variable"</span><span class="special">);</span>
</pre>
<p>
In case of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">dll</span><span class="special">::</span><span class="identifier">shared_library</span></code>
it is safe to use imported symbols only until <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">dll</span><span class="special">::</span><span class="identifier">shared_library</span></code> instance is not destroyed.
</p>
<p>
Query libraries using <code class="computeroutput"><a class="link" href="../boost/dll/library_info.html" title="Class library_info">boost::dll::library_info</a></code>
and get symbol infos using <code class="computeroutput"><a class="link" href="../boost/dll/symbol_location.html" title="Function symbol_location">boost::dll::symbol_location</a></code>,
<code class="computeroutput"><a class="link" href="../boost/dll/this_line_location.html" title="Function this_line_location">boost::dll::this_line_location</a></code>
and <code class="computeroutput"><a class="link" href="../boost/dll/program_location.html" title="Function program_location">boost::dll::program_location</a></code>.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2014 Renato Tegon Forti, Antony Polukhin<br>Copyright © 2015 Antony Polukhin<br>Copyright © 2016 Antony Polukhin, Klemens Morgenstern<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../boost_dll.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_dll.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
