Usage

Whether to use Your Native TR1 Library
Header Include Style
Writing Code

There are two things you need to decide before using the Boost.TR1 library: whether to use your standard library's native TR1 implementation (if it has one), and which include style to use.

Whether to use Your Native TR1 Library

If your standard library implements the TR1, and you want to make use of it, rather than use the Boost equivalents, then you will need to take some explicit action to enable it: this may be a pre-processor define, a special compiler switch, or a different include path. You will need to consult your compilers documentation to find out which of these actions you need to take.

Provided Boost is correctly configured, everything should now "just work", and code written to use Boost.TR1 will include your standard library's native headers rather than the Boost ones.

Header Include Style

There are two ways you can include the Boost.TR1 headers, for example if you are interested in shared_ptr then you can either use:

#include <boost/tr1/memory.hpp>

or:

#include <memory>

The first option is the preferred method for other Boost libraries to use. The second option is standard-conforming, but requires that you add boost-install-path/boost/tr1/tr1 to your compiler's include search path. Note that you must not copy the headers in boost/tr1/tr1 into a directory called "include", doing so will cause them to cease working.

Important Note #2: GNU C++ Users

Normally this library should "just work" with the GNU C++ compiler.

However, if Boost is installed in /usr/include then you may get an error message of the form:

In file included from /usr/include/boost/tr1/tuple.hpp:5,
                 from boost-failure.cxx:1:
/usr/include/boost/tr1/detail/config.hpp:60:26: error: no include path in which to search for utility

In this case try defining the macro BOOST_TR1_DISABLE_INCLUDE_NEXT when building, and if that doesn't work, define the macro BOOST_TR1_GCC_INCLUDE_PATH to the name of the directory containing gcc's include files: this is likely to be something like "g++-v4" but unfortunately varies from distribution to distribution.

Important Note #3: Borland C++ Users

Borland's compiler has a particularly broken form of #include, that will actually look for a file named array.h if you #include <array>. In order to make this library work with Borland's compiler you will need to set up the include paths as follows:

1) boost-root/boost/tr1/tr1/bcc32
2) boost-root/boost/tr1/tr1
3) boost-root
4) Any other standard library replacements (STLport for example).
5) Your regular standard library.

Important Note #4: Sun C++ Users

Sun's compiler has a particularly interesting form of #include, that will actually look for a file named array.SUNWCCh if you #include <array>. What's more it won't include a standard header file that it thinks it's already seen. In order to make this library work with Sun's compiler you can either pass the undocumented compiler switch "-Qoption ccfe -nosunwcch" to the compiler, or else you will need to set up the include paths as follows:

1) boost-root/boost/tr1/tr1/sun
2) boost-root/boost/tr1/tr1
3) boost-root
4) Any other standard library replacements (STLport for example).
5) Your regular standard library.

Writing Code

Regardless of how the includes are setup, user code written to work with Boost.TR1 is exactly the same as code written to use a native tr1 implementation. That is, references to classes and functions need to explicitly use the std::tr1 namespace or a using namespace std::tr1 statement. For example,

std::tr1::tuple<int, std::string> t = std::tr1::make_tuple(10, "hello");

using namespace std::tr1;
tuple<int, std::string> t = make_tuple(10, "hello");