1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
3 /
4 / Distributed under the Boost Software License, Version 1.0. (See accompanying
5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 /]
7
8[section:using Using, Building, and Configuring Boost.Asio]
9
10[heading Supported Platforms]
11
12The following platform and compiler combinations are regularly tested:
13
14* Linux using g++ 4.6 or later
15* Linux using clang 3.4 or later
16* FreeBSD using g++ 9 or later
17* macOS using Xcode 10 or later
18* Win32 using Visual C++ 11.0 (Visual Studio 2012) or later
19* Win64 using Visual C++ 11.0 (Visual Studio 2012) or later
20
21The following platforms may also work:
22
23* AIX
24* Android
25* HP-UX
26* iOS
27* NetBSD
28* OpenBSD
29* QNX Neutrino
30* Solaris
31* Tru64
32* Win32 using MinGW.
33* Win32 using Cygwin. (`__USE_W32_SOCKETS` must be defined.)
34
35[heading Dependencies]
36
37The following libraries must be available in order to link programs that use
38Boost.Asio:
39
40* Boost.System for the `boost::system::error_code` and
41`boost::system::system_error` classes.
42
43* Boost.Coroutine (optional) if you use [link boost_asio.reference.spawn
44`spawn()`] to launch coroutines.
45
46* Boost.Regex (optional) if you use any of the [link
47boost_asio.reference.read_until `read_until()`] or [link
48boost_asio.reference.async_read_until `async_read_until()`] overloads that take
49a `boost::regex` parameter.
50
51* [@http://www.openssl.org OpenSSL] (optional) if you use Boost.Asio's SSL
52support.
53
54Furthermore, some of the examples also require the Boost.Thread,
55Boost.Date_Time or Boost.Serialization libraries.
56
57[note With MSVC or Borland C++ you may want to add `-DBOOST_DATE_TIME_NO_LIB`
58and `-DBOOST_REGEX_NO_LIB` to your project settings to disable autolinking of
59the Boost.Date_Time and Boost.Regex libraries respectively. Alternatively, you
60may choose to build these libraries and link to them.]
61
62[heading Building Boost Libraries]
63
64You may build the subset of Boost libraries required to use Boost.Asio and its
65examples by running the following command from the root of the Boost download
66package:
67
68[pre
69  b2 --with-system --with-thread --with-date_time --with-regex --with-serialization stage
70]
71
72This assumes that you have already built `b2`. Consult the Boost.Build
73documentation for more details.
74
75[/
76
77[heading Compiling Programs With Boost.Asio]
78
79Consider the following minimal Boost.Asio program [^simple.cpp]:
80
81  #include <boost/asio.hpp>
82  #include <iostream>
83  #include <ostream>
84
85  int main()
86  {
87    boost::asio::ip::tcp::iostream s("www.boost.org", "http");
88
89    s << "GET / HTTP/1.0\r\n";
90    s << "Host: www.boost.org\r\n";
91    s << "\r\n" << std::flush;
92
93    std::cout << s.rdbuf();
94
95    return 0;
96  }
97
98The following compiler commands may be used to build the program (note that the
99name of the `boost_system` library may vary depending on the compiler version):
100
101[table
102  [
103    [OS]
104    [Compiler]
105    [Command]
106  ]
107  [
108    [FreeBSD]
109    [g++]
110    [[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib -lboost_system-gcc]]
111  ]
112  [
113    [Linux]
114    [g++]
115    [[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib -lboost_system-gcc41]]
116  ]
117  [
118    [macOS]
119    [g++]
120    [[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system]]
121  ]
122  [
123    [Solaris]
124    [g++]
125    [[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system -lsocket -lnsl -lpthread]]
126  ]
127  [
128    [Windows]
129    [MSVC 9.0]
130    [[^cl /EHsc /GR /MT /I['boost_root] /D_WIN32_WINNT=0x500 simple.cpp /link /libpath:['boost_root]/stage/lib]]
131  ]
132]
133
134]
135
136[heading Optional separate compilation]
137
138By default, Boost.Asio is a header-only library. However, some developers may
139prefer to build Boost.Asio using separately compiled source code. To do this,
140add `#include <boost/asio/impl/src.hpp>` to one (and only one) source file in a
141program, then build the program with `BOOST_ASIO_SEPARATE_COMPILATION` defined
142in the project\/compiler settings. Alternatively, `BOOST_ASIO_DYN_LINK` may be
143defined to build a separately-compiled Boost.Asio as part of a shared library.
144
145If using Boost.Asio's SSL support, you will also need to add `#include
146<boost/asio/ssl/impl/src.hpp>`.
147
148[heading Macros]
149
150The macros listed in the table below may be used to control the interface,
151functionality, and behaviour of Boost.Asio.
152
153[table
154  [[Macro][Description]]
155  [
156    [`BOOST_ASIO_NO_DEPRECATED`]
157    [
158      Disables Boost.Asio's deprecated interfaces and functionality.
159
160      See [link boost_asio.net_ts Networking TS Compatibility] for a list of older
161      interfaces that have been deprecated, and their replacements.
162    ]
163  ]
164  [
165    [`BOOST_ASIO_NO_TS_EXECUTORS`]
166    [
167      Disables Boost.Asio's support for the Networking TS executor model.
168
169      By default, Boost.Asio simultaneously supports both Networking TS-style
170      executors, and executors that adhere to the proposed standard executor
171      model. This macro may be used to limit support to the proposed standard
172      executors only. See [link boost_asio.std_executors Proposed Standard
173      Executors] for more information.
174    ]
175  ]
176  [
177    [`BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT`]
178    [
179      Specifies that [link boost_asio.reference.any_io_executor `any_io_executor`]
180      refer to the Networking TS-style polymorphic wrapper.
181
182      The `any_io_executor` type alias is the default runtime-polymorphic
183      executor for all I/O objects. This type alias points to the [link
184      boost_asio.reference.execution__any_executor `execution::any_executor<>`]
185      template with a set of supportable properties specified for use with I/O.
186
187      This new name may break existing code that directly uses the old
188      Networking TS-style polymorphic wrapper, [link boost_asio.reference.executor
189      `executor`]. If required for backward compatibility,
190      `BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT` changes the `any_io_executor` type
191      alias to instead point to the `executor` polymorphic wrapper.
192
193      See [link boost_asio.std_executors Proposed Standard Executors] for more
194      information.
195    ]
196  ]
197  [
198    [`BOOST_ASIO_NO_DYNAMIC_BUFFER_V1`]
199    [
200      Disables support for the [link boost_asio.reference.DynamicBuffer_v1
201      `DynamicBuffer_v1`] type requirements.
202
203      By default, dynamic buffer operations such as [link boost_asio.reference.read
204      `read`], [link boost_asio.reference.async_read `async_read`], [link
205      boost_asio.reference.read_until `read_until`], [link
206      boost_asio.reference.async_read_until `async_read_until`], [link
207      boost_asio.reference.write `write`], and [link boost_asio.reference.async_write
208      `async_write`] support both the `DynamicBuffer_v1` and the [link
209      boost_asio.reference.DynamicBuffer_v2 `DynamicBuffer_v2`] type requirements
210      for dynamic buffers.
211
212      When `BOOST_ASIO_NO_DYNAMIC_BUFFER_V1` is defined, all support for
213      `DynamicBuffer_v1` types and functions is #ifdef-ed out. Support for
214      using [link boost_asio.reference.basic_streambuf `basic_streambuf`] with the
215      `read`, `async_read`, `read_until`, `async_read_until`, `write`, and
216      `async_write` functions is also disabled as a consequence.
217    ]
218  ]
219  [
220    [`BOOST_ASIO_ENABLE_BUFFER_DEBUGGING`]
221    [
222      Enables Boost.Asio's buffer debugging support, which can help identify when
223      invalid buffers are used in read or write operations (e.g. if a
224      std::string object being written is destroyed before the write operation
225      completes).
226
227      When using Microsoft Visual C++ 11.0 or later, this macro is defined
228      automatically if the compiler's iterator debugging support is enabled,
229      unless `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
230
231      When using g++, this macro is defined automatically if standard library
232      debugging is enabled (`_GLIBCXX_DEBUG` is defined), unless
233      `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
234    ]
235  ]
236  [
237    [`BOOST_ASIO_DISABLE_BUFFER_DEBUGGING`]
238    [
239      Explictly disables Boost.Asio's buffer debugging support.
240    ]
241  ]
242  [
243    [`BOOST_ASIO_ENABLE_HANDLER_TRACKING`]
244    [
245      Enables Boost.Asio's [link boost_asio.overview.core.handler_tracking Handler
246      Tracking] debugging facility.
247    ]
248  ]
249  [
250    [`BOOST_ASIO_DISABLE_DEV_POLL`]
251    [
252      Explicitly disables [^/dev/poll] support on Solaris, forcing the use of
253      a `select`-based implementation.
254    ]
255  ]
256  [
257    [`BOOST_ASIO_DISABLE_EPOLL`]
258    [
259      Explicitly disables `epoll` support on Linux, forcing the use of a
260      `select`-based implementation.
261    ]
262  ]
263  [
264    [`BOOST_ASIO_DISABLE_EVENTFD`]
265    [
266      Explicitly disables `eventfd` support on Linux, forcing the use of a
267      pipe to interrupt blocked epoll/select system calls.
268    ]
269  ]
270  [
271    [`BOOST_ASIO_DISABLE_KQUEUE`]
272    [
273      Explicitly disables `kqueue` support on macOS and BSD variants,
274      forcing the use of a `select`-based implementation.
275    ]
276  ]
277  [
278    [`BOOST_ASIO_DISABLE_IOCP`]
279    [
280      Explicitly disables I/O completion ports support on Windows, forcing the
281      use of a `select`-based implementation.
282    ]
283  ]
284  [
285    [`BOOST_ASIO_DISABLE_THREADS`]
286    [
287      Explicitly disables Boost.Asio's threading support, independent of whether
288      or not Boost as a whole supports threads.
289    ]
290  ]
291  [
292    [`BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN`]
293    [
294      By default, Boost.Asio will automatically define `WIN32_LEAN_AND_MEAN` when
295      compiling for Windows, to minimise the number of Windows SDK header files
296      and features that are included. The presence of
297      `BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN` prevents `WIN32_LEAN_AND_MEAN` from
298      being defined.
299    ]
300  ]
301  [
302    [`BOOST_ASIO_NO_NOMINMAX`]
303    [
304      By default, Boost.Asio will automatically define `NOMINMAX` when
305      compiling for Windows, to suppress the definition of the `min()` and
306      `max()` macros. The presence of `BOOST_ASIO_NO_NOMINMAX` prevents
307      `NOMINMAX` from being defined.
308    ]
309  ]
310  [
311    [`BOOST_ASIO_NO_DEFAULT_LINKED_LIBS`]
312    [
313      When compiling for Windows using Microsoft Visual C++ or Borland C++, Boost.Asio
314      will automatically link in the necessary Windows SDK libraries for sockets
315      support (i.e. [^ws2_32.lib] and [^mswsock.lib], or [^ws2.lib] when
316      building for Windows CE). The `BOOST_ASIO_NO_DEFAULT_LINKED_LIBS` macro
317      prevents these libraries from being linked.
318    ]
319  ]
320  [
321    [`BOOST_ASIO_ENABLE_CANCELIO`]
322    [
323      Enables use of the `CancelIo` function on older versions of Windows. If
324      not enabled, calls to `cancel()` on a socket object will always fail with
325      `asio::error::operation_not_supported` when run on Windows XP, Windows
326      Server 2003, and earlier versions of Windows. When running on Windows
327      Vista, Windows Server 2008, and later, the `CancelIoEx` function is
328      always used.
329
330      The `CancelIo` function has two issues that should be considered before
331      enabling its use:
332
333      * It will only cancel asynchronous operations that were initiated in the
334        current thread.
335
336      * It can appear to complete without error, but the request
337        to cancel the unfinished operations may be silently ignored by the
338        operating system. Whether it works or not seems to depend on the
339        drivers that are installed.
340
341      For portable cancellation, consider using one of the following
342      alternatives:
343
344      * Disable asio's I/O completion port backend by defining
345        BOOST_ASIO_DISABLE_IOCP.
346
347      * Use the socket object's close() function to simultaneously
348        cancel the outstanding operations and close the socket.
349    ]
350  ]
351  [
352    [`BOOST_ASIO_NO_TYPEID`]
353    [
354      Disables uses of the `typeid` operator in Boost.Asio. Defined
355      automatically if `BOOST_NO_TYPEID` is defined.
356    ]
357  ]
358  [
359    [`BOOST_ASIO_HASH_MAP_BUCKETS`]
360    [
361      Determines the number of buckets in Boost.Asio's internal `hash_map`
362      objects. The value should be a comma separated list of prime numbers, in
363      ascending order. The `hash_map` implementation will automatically
364      increase the number of buckets as the number of elements in the map
365      increases.
366
367      Some examples:
368
369      * Defining `BOOST_ASIO_HASH_MAP_BUCKETS` to `1021` means that the
370        `hash_map` objects will always contain 1021 buckets, irrespective of
371        the number of elements in the map.
372
373      * Defining `BOOST_ASIO_HASH_MAP_BUCKETS` to `53,389,1543` means that the
374        `hash_map` objects will initially contain 53 buckets. The number of
375        buckets will be increased to 389 and then 1543 as elements are added to
376        the map.
377    ]
378  ]
379  [
380    [`BOOST_ASIO_USE_BOOST_DATE_TIME_FOR_SOCKET_IOSTREAM`]
381    [
382      Changes [link boost_asio.reference.basic_socket_streambuf
383      `basic_socket_streambuf`] and [link boost_asio.reference.basic_socket_iostream
384      `basic_socket_iostream`] to use the old Boost.Date_Time interface, rather
385      than chrono.
386    ]
387  ]
388  [
389    [`BOOST_ASIO_SEPARATE_COMPILATION`]
390    [
391      Uses separately compiled source code for Boost.Asio's implementation.
392
393      See [link boost_asio.using.optional_separate_compilation above] for further
394      information.
395    ]
396  ]
397  [
398    [`BOOST_ASIO_DYN_LINK`]
399    [
400      Uses separately compiled source code for Boost.Asio's implementation,
401      with symbols exported for inclusion as part of a shared library.
402
403      See [link boost_asio.using.optional_separate_compilation above] for further
404      information.
405    ]
406  ]
407  [
408    [`BOOST_ASIO_DISABLE_VISIBILITY`]
409    [
410      Disables all symbol visibility pragmas.
411
412      Note: If symbols are hidden, extra care must be taken to ensure that Boost.Asio
413      types are not passed across shared library API boundaries.
414    ]
415  ]
416]
417
418[include platform_macros.qbk]
419
420[heading Mailing List]
421
422A mailing list specifically for Boost.Asio may be found on
423[@http://sourceforge.net/mail/?group_id=122478 SourceForge.net]. Newsgroup
424access is provided via [@http://dir.gmane.org/gmane.comp.lib.boost.asio.user
425Gmane].
426
427[heading Wiki]
428
429Users are encouraged to share examples, tips and FAQs on the Boost.Asio wiki,
430which is located at [@http://think-async.com/Asio/].
431
432[endsect]
433