123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322 |
- [/
- / Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
- /
- / 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)
- /]
- [section:using Using Boost.Asio]
- [heading Supported Platforms]
- The following platform and compiler combinations are regularly tested:
- * Linux using g++ 4.1 or later
- * Linux using clang 3.2 or later
- * FreeBSD using g++ 4.1 or later
- * macOS using Xcode 8 or later
- * Win32 using Visual C++ 9.0 or later
- * Win32 using g++ 4.1 or later (MinGW)
- * Win64 using Visual C++ 9.0 or later
- The following platforms may also work:
- * AIX
- * Android
- * HP-UX
- * iOS
- * NetBSD
- * OpenBSD
- * QNX Neutrino
- * Solaris
- * Tru64
- * Win32 using Cygwin. (`__USE_W32_SOCKETS` must be defined.)
- [heading Dependencies]
- The following libraries must be available in order to link programs that use
- Boost.Asio:
- * Boost.System for the `boost::system::error_code` and
- `boost::system::system_error` classes.
- * Boost.Coroutine (optional) if you use [link boost_asio.reference.spawn
- `spawn()`] to launch coroutines.
- * Boost.Regex (optional) if you use any of the [link
- boost_asio.reference.read_until `read_until()`] or [link
- boost_asio.reference.async_read_until `async_read_until()`] overloads that take
- a `boost::regex` parameter.
- * [@http://www.openssl.org OpenSSL] (optional) if you use Boost.Asio's SSL
- support.
- Furthermore, some of the examples also require the Boost.Thread,
- Boost.Date_Time or Boost.Serialization libraries.
- [note With MSVC or Borland C++ you may want to add `-DBOOST_DATE_TIME_NO_LIB`
- and `-DBOOST_REGEX_NO_LIB` to your project settings to disable autolinking of
- the Boost.Date_Time and Boost.Regex libraries respectively. Alternatively, you
- may choose to build these libraries and link to them.]
- [heading Building Boost Libraries]
- You may build the subset of Boost libraries required to use Boost.Asio and its
- examples by running the following command from the root of the Boost download
- package:
- [pre
- b2 --with-system --with-thread --with-date_time --with-regex --with-serialization stage
- ]
- This assumes that you have already built `b2`. Consult the Boost.Build
- documentation for more details.
- [/
- [heading Compiling Programs With Boost.Asio]
- Consider the following minimal Boost.Asio program [^simple.cpp]:
- #include <boost/asio.hpp>
- #include <iostream>
- #include <ostream>
- int main()
- {
- boost::asio::ip::tcp::iostream s("www.boost.org", "http");
- s << "GET / HTTP/1.0\r\n";
- s << "Host: www.boost.org\r\n";
- s << "\r\n" << std::flush;
- std::cout << s.rdbuf();
- return 0;
- }
- The following compiler commands may be used to build the program (note that the
- name of the `boost_system` library may vary depending on the compiler version):
- [table
- [
- [OS]
- [Compiler]
- [Command]
- ]
- [
- [FreeBSD]
- [g++]
- [[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib -lboost_system-gcc]]
- ]
- [
- [Linux]
- [g++]
- [[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib -lboost_system-gcc41]]
- ]
- [
- [macOS]
- [g++]
- [[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system]]
- ]
- [
- [Solaris]
- [g++]
- [[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system -lsocket -lnsl -lpthread]]
- ]
- [
- [Windows]
- [MSVC 9.0]
- [[^cl /EHsc /GR /MT /I['boost_root] /D_WIN32_WINNT=0x500 simple.cpp /link /libpath:['boost_root]/stage/lib]]
- ]
- ]
- ]
- [heading Optional separate compilation]
- By default, Boost.Asio is a header-only library. However, some developers may
- prefer to build Boost.Asio using separately compiled source code. To do this,
- add `#include <boost/asio/impl/src.hpp>` to one (and only one) source file in a
- program, then build the program with `BOOST_ASIO_SEPARATE_COMPILATION` defined
- in the project\/compiler settings. Alternatively, `BOOST_ASIO_DYN_LINK` may be
- defined to build a separately-compiled Boost.Asio as part of a shared library.
- If using Boost.Asio's SSL support, you will also need to add `#include
- <boost/asio/ssl/impl/src.hpp>`.
- [heading Macros]
- The macros listed in the table below may be used to control the behaviour of
- Boost.Asio.
- [table
- [[Macro][Description]]
- [
- [`BOOST_ASIO_ENABLE_BUFFER_DEBUGGING`]
- [
- Enables Boost.Asio's buffer debugging support, which can help identify when
- invalid buffers are used in read or write operations (e.g. if a
- std::string object being written is destroyed before the write operation
- completes).
- When using Microsoft Visual C++ 11.0 or later, this macro is defined
- automatically if the compiler's iterator debugging support is enabled,
- unless `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
- When using g++, this macro is defined automatically if standard library
- debugging is enabled (`_GLIBCXX_DEBUG` is defined), unless
- `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_BUFFER_DEBUGGING`]
- [
- Explictly disables Boost.Asio's buffer debugging support.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_DEV_POLL`]
- [
- Explicitly disables [^/dev/poll] support on Solaris, forcing the use of
- a `select`-based implementation.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_EPOLL`]
- [
- Explicitly disables `epoll` support on Linux, forcing the use of a
- `select`-based implementation.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_EVENTFD`]
- [
- Explicitly disables `eventfd` support on Linux, forcing the use of a
- pipe to interrupt blocked epoll/select system calls.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_KQUEUE`]
- [
- Explicitly disables `kqueue` support on macOS and BSD variants,
- forcing the use of a `select`-based implementation.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_IOCP`]
- [
- Explicitly disables I/O completion ports support on Windows, forcing the
- use of a `select`-based implementation.
- ]
- ]
- [
- [`BOOST_ASIO_DISABLE_THREADS`]
- [
- Explicitly disables Boost.Asio's threading support, independent of whether
- or not Boost as a whole supports threads.
- ]
- ]
- [
- [`BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN`]
- [
- By default, Boost.Asio will automatically define `WIN32_LEAN_AND_MEAN` when
- compiling for Windows, to minimise the number of Windows SDK header files
- and features that are included. The presence of
- `BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN` prevents `WIN32_LEAN_AND_MEAN` from
- being defined.
- ]
- ]
- [
- [`BOOST_ASIO_NO_NOMINMAX`]
- [
- By default, Boost.Asio will automatically define `NOMINMAX` when
- compiling for Windows, to suppress the definition of the `min()` and
- `max()` macros. The presence of `BOOST_ASIO_NO_NOMINMAX` prevents
- `NOMINMAX` from being defined.
- ]
- ]
- [
- [`BOOST_ASIO_NO_DEFAULT_LINKED_LIBS`]
- [
- When compiling for Windows using Microsoft Visual C++ or Borland C++, Boost.Asio
- will automatically link in the necessary Windows SDK libraries for sockets
- support (i.e. [^ws2_32.lib] and [^mswsock.lib], or [^ws2.lib] when
- building for Windows CE). The `BOOST_ASIO_NO_DEFAULT_LINKED_LIBS` macro
- prevents these libraries from being linked.
- ]
- ]
- [
- [`BOOST_ASIO_ENABLE_CANCELIO`]
- [
- Enables use of the `CancelIo` function on older versions of Windows. If
- not enabled, calls to `cancel()` on a socket object will always fail with
- `asio::error::operation_not_supported` when run on Windows XP, Windows
- Server 2003, and earlier versions of Windows. When running on Windows
- Vista, Windows Server 2008, and later, the `CancelIoEx` function is
- always used.
- The `CancelIo` function has two issues that should be considered before
- enabling its use:
- * It will only cancel asynchronous operations that were initiated in the
- current thread.
- * It can appear to complete without error, but the request
- to cancel the unfinished operations may be silently ignored by the
- operating system. Whether it works or not seems to depend on the
- drivers that are installed.
- For portable cancellation, consider using one of the following
- alternatives:
- * Disable asio's I/O completion port backend by defining
- BOOST_ASIO_DISABLE_IOCP.
- * Use the socket object's close() function to simultaneously
- cancel the outstanding operations and close the socket.
- ]
- ]
- [
- [`BOOST_ASIO_NO_TYPEID`]
- [
- Disables uses of the `typeid` operator in Boost.Asio. Defined
- automatically if `BOOST_NO_TYPEID` is defined.
- ]
- ]
- [
- [`BOOST_ASIO_HASH_MAP_BUCKETS`]
- [
- Determines the number of buckets in Boost.Asio's internal `hash_map`
- objects. The value should be a comma separated list of prime numbers, in
- ascending order. The `hash_map` implementation will automatically
- increase the number of buckets as the number of elements in the map
- increases.
- Some examples:
- * Defining `BOOST_ASIO_HASH_MAP_BUCKETS` to `1021` means that the
- `hash_map` objects will always contain 1021 buckets, irrespective of
- the number of elements in the map.
- * Defining `BOOST_ASIO_HASH_MAP_BUCKETS` to `53,389,1543` means that the
- `hash_map` objects will initially contain 53 buckets. The number of
- buckets will be increased to 389 and then 1543 as elements are added to
- the map.
- ]
- ]
- ]
- [heading Mailing List]
- A mailing list specifically for Boost.Asio may be found on
- [@http://sourceforge.net/mail/?group_id=122478 SourceForge.net]. Newsgroup
- access is provided via [@http://dir.gmane.org/gmane.comp.lib.boost.asio.user
- Gmane].
- [heading Wiki]
- Users are encouraged to share examples, tips and FAQs on the Boost.Asio wiki,
- which is located at [@http://think-async.com/Asio/].
- [endsect]
|