Installation

Overview
Building with an IDE or Makefile
Building with Boost.Build

Overview

Most of Boost.Iostreams can be used simply by including appropriate headers. This is true, for instance, of all the core components — including stream, stream_buffer, filtering_stream and filtering_streambuf — and of about two thirds of the concrete Filters and Devices. Some components, however, are implemented in .cpp files; in addition, the regular expression filters depend on Boost.Regex, and the compressions filters rely on the third-party libraries zlib ([Gailly]) and libbz2 ([Seward]). To obatin zlib and libbz2, see the instructions here and here.

The components which are implemented in .cpp or which rely on external libraries can be built in two ways: by adding the appropriate .cpp files to your IDE project or makefile, or by using Boost.Build.

Building with an IDE or Makefile

The following table shows which headers contain components defined in .cpp files. If your application includes one of these headers, you'll need to add the corresponding .cpp files to you IDE project or makefile, and to define the preprocessor symbol BOOST_IOSTREAMS_NO_LIB. In addition, if the .cpp file depends on an external library, you'll have to build it from the source or link to a pre-built binary.

HeaderSource FileExternal Library
boost/iostreams/device/file_descriptor.hpp file_descriptor.cpp -
boost/iostreams/device/mapped_file.hpp mapped_file.cpp -
boost/iostreams/filter/bzip2.hpp bzip2.cpp libbz2
boost/iostreams/filter/gzip.hpp gzip.cpp, zlib.cpp zlib
boost/iostreams/filter/regex.hpp - Boost.Regex
boost/iostreams/filter/zlib.hpp zlib.cpp zlib

Building with Boost.Build

To build with Boost.Build, run bjam from the directory libs/iostreams/build, or from the Boost root directory. If you want to use the compression filters, you may need to set several Boost.Build variables indicating where the source files or pre-built binaries are located. These variables are summarized in the following table.

On most UNIX systems, it should not be necessary to set any of these variables, since the zlib and libbz2 headers and binaries are already installed in locations where they will be found automatically. On Windows, the zlib and bzip2 filters are disabled by default; to enable support for these filters, you will need to set variables indicating the location of the source files, if building from the source, or the location of the headers and binaries, if using pre-built binaries.

VariableInterpretationDefault
NO_COMPRESSION Disable support for compression filters. -
NO_BZIP2 Disable support for the bzip2 filters. 1 (Windows)
BZIP2_BINARY Name of the libbz2 binary, not including the file extension, or the "lib" prefix on UNIX. On Windows, if linking with a dynamic build of libbz2, specify the name of the import library. bz2 (UNIX)
libbz2 (Windows)
BZIP2_INCLUDE Path to the libbz2 headers, if they're not in a location where they'll be found automatically. BZIP2_SOURCE
BZIP2_LIBPATH Path to the libbz2 binary, if it's not in a location where it will be found automatically. On Windows, if linking with a dynamic build of libbz2, specify the path to the import library. -
BZIP2_SOURCE Path to the libbz2 source files, if they're not in a location where they'll be found automatically. -
NO_ZLIB Disable support for the zlib filters. 1 (Windows)
ZLIB_BINARY Name of the zlib binary, not including the file extension, or the "lib" prefix on UNIX. On Windows, if linking with a dynamic build of zlib, specify the name of the import library. z (UNIX)
zdll (Windows)
ZLIB_INCLUDE Path to the zlib headers, if they're not in a location where they'll be found automatically. ZLIB_SOURCE
ZLIB_LIBPATH Path to the zlib binary, if it's not in a location where it will be found automatically. On Windows, if linking with a dynamic build of zlib, specify the path to the import library. -
ZLIB_SOURCE Path to the zlib source files, if they're not in a location where they'll be found automatically. -