The following platform and compiler combinations are regularly tested:
The following platforms may also work:
__USE_W32_SOCKETS
must be defined.)
The following libraries must be available in order to link programs that use Asio:
spawn()
to launch coroutines.
read_until()
or async_read_until()
overloads that take a boost::regex
parameter.
Furthermore, some of the examples also require Boost.Date_Time or Boost.Serialization libraries.
Note | |
---|---|
With MSVC or Borland C++ you may want to add |
By default, Asio is a header-only library. However, some developers may prefer
to build Asio using separately compiled source code. To do this, add #include <asio/impl/src.hpp>
to
one (and only one) source file in a program, then build the program with ASIO_SEPARATE_COMPILATION
defined in the
project/compiler settings. Alternatively, ASIO_DYN_LINK
may be defined to build a separately-compiled Asio as part of a shared library.
If using Asio's SSL support, you will also need to add #include
<asio/ssl/impl/src.hpp>
.
Some debugger extensions for use with Asio may be found at https://github.com/chriskohlhoff/asio-debugger-extensions.
If the boost directory (e.g. the directory called boost_1_34_1
)
is in the same directory as the asio source kit, then you may configure asio
by simply going:
./configure
in the root directory of the asio source kit. Note that configure will always use the most recent boost version it knows about (i.e. 1.34.1) in preference to earlier versions, if there is more than one version present.
If the boost directory is in some other location, then you need to specify this directory when running configure:
./configure --with-boost=path_to_boost
When specifying the boost directory in this way you should ensure that you use an absolute path.
To build the examples, simply run make
in the root directory of the asio source kit. To also build and run the unit
tests, to confirm that asio is working correctly, run make
check
.
To build using the MSVC 9.0 (or later) command line compiler, perform the following steps in a Command Prompt window:
boost_1_34_1
)
is not in the same directory as the asio source kit, then specify the location
of boost by running a command similar to set BOOSTDIR=path_to_boost
.
Ensure that you specify an absolute path.
src
directory.
nmake -f Makefile.msc
.
nmake -f Makefile.msc check
to run a suite of tests to confirm
that asio is working correctly.
To build using the MinGW g++ compiler from the command line, perform the following steps in a Command Prompt window:
boost_1_34_1
)
is not in the same directory as the asio source kit, then specify the location
of boost by running a command similar to set BOOSTDIR=path_to_boost
.
Ensure that you specify an absolute path using forward slashes
(i.e. c:/projects/boost_1_34_1
rather than c:\projects\boost_1_34_1
).
src
directory.
make -f Makefile.mgw
.
make -f Makefile.mgw check
to run a suite of tests to confirm
that asio is working correctly.
Note | |
---|---|
The above instructions do not work when building inside MSYS. If you want
to build using MSYS, you should use |
The macros listed in the table below may be used to control the interface, functionality, and behaviour of Asio.
Macro |
Description |
---|---|
|
Disables Asio's deprecated interfaces and functionality. See Networking TS Compatibility for a list of older interfaces that have been deprecated, and their replacements. |
|
Disables Asio's support for the Networking TS executor model. By default, Asio simultaneously supports both Networking TS-style executors, and executors that adhere to the proposed standard executor model. This macro may be used to limit support to the proposed standard executors only. See Proposed Standard Executors for more information. |
|
Specifies that
The
This new name may break existing code that directly uses the old
Networking TS-style polymorphic wrapper, See Proposed Standard Executors for more information. |
|
Disables support for the
By default, dynamic buffer operations such as
When |
|
Enables 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
When using g++, this macro is defined automatically if standard library
debugging is enabled ( |
|
Explictly disables Asio's buffer debugging support. |
|
Enables Asio's Handler Tracking debugging facility. |
|
Explicitly disables |
|
Explicitly disables |
|
Explicitly disables |
|
Explicitly disables |
|
Explicitly disables I/O completion ports support on Windows, forcing
the use of a |
|
Explicitly disables Asio's threading support, independent of whether or not Boost supports threads. |
|
By default, Asio will automatically define |
|
By default, Asio will automatically define |
|
When compiling for Windows using Microsoft Visual C++ or Borland
C++, Asio will automatically link in the necessary Windows SDK libraries
for sockets support (i.e. |
|
Enables use of the
The
|
|
Disables uses of the |
|
Determines the number of buckets in asio's internal Some examples:
|
|
Changes |
|
Uses separately compiled source code for Asio's implementation. See above for further information. |
|
Uses separately compiled source code for Asio's implementation, with symbols exported for inclusion as part of a shared library. See above for further information. |
|
Disables all symbol visibility pragmas. Note: If symbols are hidden, extra care must be taken to ensure that Asio types are not passed across shared library API boundaries. |
Asio automatically defines preprocessor macros corresponding to the detected
available features on a particular compiler and target platform. These macros
are named with the prefix ASIO_HAS_
,
and are listed in the table below.
Many of these macros also have a corresponding ASIO_DISABLE_
macro that may be used to explicitly disable the feature.
In general, ASIO_HAS_
macros
should not be explicitly defined by the user, except when absolutely required
as a workaround for the latest version of a compiler or platform. For older
compiler/platform combinations where a specific ASIO_HAS_
macro is not automatically defined, testing may have shown that a claimed feature
isn't sufficiently conformant to be compatible with Asio's needs.
Macro |
Description |
Macro to disable feature |
---|---|---|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Boost align library. |
|
|
Boost array library. |
|
|
Boost assert macro. |
|
|
Boost bind function. |
|
|
Boost support for chrono. |
|
|
Boost.Config library is available. |
|
|
Boost support for the Context library's fibers. |
|
|
Boost support for the Coroutine library. |
|
|
Boost support for the DateTime library. |
|
|
Boost limits header. |
|
|
Boost regex library. |
|
|
Boost support for source_location and system errors. |
|
|
Boost throw_exception function. |
|
|
Boost's BOOST_WORKAROUND macro. |
|
|
Some form of chrono library is available. |
|
|
Clang / libc++ detection. |
|
|
Support concepts on compilers known to allow them. |
|
|
Support SFINAE use of constant expressions on compilers known to allow it. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Support the co_await keyword on compilers known to allow it. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Solaris: /dev/poll. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Linux: epoll, eventfd, timerfd and io_uring. |
|
|
Linux: epoll, eventfd, timerfd and io_uring. |
|
|
Files. |
|
|
Can use getaddrinfo() and getnameinfo(). |
|
|
Handler hooking. Disabled for ancient Borland C++ and gcc compilers. |
|
|
Windows: IO Completion Ports. |
|
|
Linux: io_uring is used instead of epoll. |
|
|
Mac OS X, FreeBSD, NetBSD, OpenBSD: kqueue. |
|
|
UNIX domain sockets. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Kernel support for MSG_NOSIGNAL. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Support noexcept on function types on compilers known to allow it. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Pipes. |
|
|
POSIX: stream-oriented file descriptors. |
|
|
POSIX threads. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Support return type deduction on compilers known to allow it. |
|
|
Microsoft Visual C++'s secure C runtime library. |
|
|
Serial ports. |
|
|
Support SFINAEd template variables on compilers known to allow it. |
|
|
Can use sigaction() instead of signal(). |
|
|
Can use signal(). |
|
|
Standard library support for snprintf. |
|
|
Standard library has a source_location that we can use. |
|
|
Support for POSIX ssize_t typedef. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for aligned allocation. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for std::any. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Support concepts on compilers known to allow them. |
|
|
Standard library support for coroutines. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for std::experimental::source_location. |
|
|
Standard library support for std::experimental::string_view. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for std::index_sequence. |
|
|
Standard library has invoke_result (which supersedes result_of). |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for std::string_view. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for std::to_address. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Standard library support for std::variant. |
|
|
Standard library has a string_view that we can use. |
|
|
Threads. |
|
|
Support for the __thread keyword extension, or equivalent. |
|
|
Linux: epoll, eventfd, timerfd and io_uring. |
|
|
On POSIX (and POSIX-like) platforms we need to include unistd.h in order to get access to the various platform feature macros, e.g. to be able to test for threads support. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Support template variables on compilers known to allow it. |
|
|
Support for capturing parameter packs in lambdas. |
|
|
Always enabled. Retained for backwards compatibility in user code. |
|
|
Windows: object handles. |
|
|
Windows: OVERLAPPED wrapper. |
|
|
Windows: random access handles. |
|
|
Windows: stream handles. |
|
|
Enable workarounds for lack of working expression SFINAE. |
|
A mailing list specifically for Asio may be found on SourceForge.net. Newsgroup access is provided via Gmane.