doc/html/boost_tr1/usage.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Usage</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../boost_tr1.html" title="Chapter&#160;39.&#160;Boost.TR1">
  10 <link rel="prev" href="../boost_tr1.html" title="Chapter&#160;39.&#160;Boost.TR1">
  11 <link rel="next" href="config.html" title="Configuration">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="../boost_tr1.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_tr1.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="config.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="boost_tr1.usage"></a><a class="link" href="usage.html" title="Usage">Usage</a>
  29 </h2></div></div></div>
  30 <div class="toc"><dl class="toc">
  31 <dt><span class="section"><a href="usage.html#boost_tr1.usage.native">Whether to use Your Native TR1
  32       Library</a></span></dt>
  33 <dt><span class="section"><a href="usage.html#boost_tr1.usage.include_style">Header Include Style</a></span></dt>
  34 <dt><span class="section"><a href="usage.html#boost_tr1.usage.writing_code">Writing Code</a></span></dt>
  35 </dl></div>
  36 <p>
  37       There are two things you need to decide before using the Boost.TR1 library:
  38       whether to use your standard library's native TR1 implementation (if it has
  39       one), and which include style to use.
  40     </p>
  41 <div class="section">
  42 <div class="titlepage"><div><div><h3 class="title">
  43 <a name="boost_tr1.usage.native"></a><a class="link" href="usage.html#boost_tr1.usage.native" title="Whether to use Your Native TR1 Library">Whether to use Your Native TR1
  44       Library</a>
  45 </h3></div></div></div>
  46 <p>
  47         If your standard library implements the TR1, and you want to make use of
  48         it, rather than use the Boost equivalents, then you will need to take some
  49         explicit action to enable it: this may be a pre-processor define, a special
  50         compiler switch, or a different include path. You will need to consult your
  51         compilers documentation to find out which of these actions you need to take.
  52       </p>
  53 <p>
  54         Provided Boost is <a class="link" href="config.html" title="Configuration">correctly configured</a>,
  55         everything should now "just work", and code written to use Boost.TR1
  56         will include your standard library's native headers rather than the Boost
  57         ones.
  58       </p>
  59 </div>
  60 <div class="section">
  61 <div class="titlepage"><div><div><h3 class="title">
  62 <a name="boost_tr1.usage.include_style"></a><a class="link" href="usage.html#boost_tr1.usage.include_style" title="Header Include Style">Header Include Style</a>
  63 </h3></div></div></div>
  64 <p>
  65         There are two ways you can include the Boost.TR1 headers, for example if
  66         you are interested in shared_ptr then you can either use:
  67       </p>
  68 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">tr1</span><span class="special">/</span><span class="identifier">memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  69 </pre>
  70 <p>
  71         or:
  72       </p>
  73 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">memory</span><span class="special">&gt;</span>
  74 </pre>
  75 <p>
  76         The first option is the preferred method for other Boost libraries to use.
  77         The second option is standard-conforming, but requires that you add <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">install</span><span class="special">-</span><span class="identifier">path</span><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">tr1</span><span class="special">/</span><span class="identifier">tr1</span></code> to your compiler's include search path.
  78         Note that you must not copy the headers in boost/tr1/tr1 into a directory
  79         called "include", doing so will cause them to cease working.
  80       </p>
  81 <div class="sidebar">
  82 <div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
  83 <p>
  84         <span class="bold"><strong>Important Note #1</strong></span>
  85       </p>
  86 <p>
  87         The include path order is very important if you want this library to work
  88         correctly. If you get compiler errors then suspect the include paths. The
  89         correct order is:
  90       </p>
  91 <p>
  92         1) boost-root/boost/tr1/tr1<br> 2) boost-root<br> 3) Any other standard
  93         library replacements (STLport for example).<br> 4) Your regular standard
  94         library.<br>
  95       </p>
  96 </div>
  97 <div class="sidebar">
  98 <div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
  99 <p>
 100         <span class="bold"><strong>Important Note #2: GNU C++ Users</strong></span>
 101       </p>
 102 <p>
 103         Normally this library should "just work" with the GNU C++ compiler.
 104       </p>
 105 <p>
 106         However, if Boost is installed in <code class="computeroutput"><span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">include</span></code>
 107         then you may get an error message of the form:
 108       </p>
 109 <p>
 110 </p>
 111 <pre class="programlisting"><span class="identifier">In</span> <span class="identifier">file</span> <span class="identifier">included</span> <span class="identifier">from</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">tr1</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">:</span><span class="number">5</span><span class="special">,</span>
 112                  <span class="identifier">from</span> <span class="identifier">boost</span><span class="special">-</span><span class="identifier">failure</span><span class="special">.</span><span class="identifier">cxx</span><span class="special">:</span><span class="number">1</span><span class="special">:</span>
 113 <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">tr1</span><span class="special">/</span><span class="identifier">detail</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">:</span><span class="number">60</span><span class="special">:</span><span class="number">26</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">no</span> <span class="identifier">include</span> <span class="identifier">path</span> <span class="identifier">in</span> <span class="identifier">which</span> <span class="identifier">to</span> <span class="identifier">search</span> <span class="keyword">for</span> <span class="identifier">utility</span></pre>
 114 <p>
 115       </p>
 116 <p>
 117         In this case try defining the macro <code class="computeroutput"><span class="identifier">BOOST_TR1_DISABLE_INCLUDE_NEXT</span></code>
 118         when building, and if that doesn't work, define the macro <code class="computeroutput"><span class="identifier">BOOST_TR1_GCC_INCLUDE_PATH</span></code>
 119         to the name of the directory containing gcc's include files: this is likely
 120         to be something like "g++-v4" but unfortunately varies from distribution
 121         to distribution.
 122       </p>
 123 </div>
 124 <div class="sidebar">
 125 <div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
 126 <p>
 127         <span class="bold"><strong>Important Note #3: Borland C++ Users</strong></span>
 128       </p>
 129 <p>
 130         Borland's compiler has a particularly broken form of <code class="computeroutput"><span class="preprocessor">#include</span></code>,
 131         that will actually look for a file named <code class="computeroutput"><span class="identifier">array</span><span class="special">.</span><span class="identifier">h</span></code> if you
 132         <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">array</span><span class="special">&gt;</span></code>.
 133         In order to make this library work with Borland's compiler you will need
 134         to set up the include paths as follows:
 135       </p>
 136 <p>
 137         1) boost-root/boost/tr1/tr1/bcc32<br> 2) boost-root/boost/tr1/tr1<br>
 138         3) boost-root<br> 4) Any other standard library replacements (STLport for
 139         example).<br> 5) Your regular standard library.<br>
 140       </p>
 141 </div>
 142 <div class="sidebar">
 143 <div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
 144 <p>
 145         <span class="bold"><strong>Important Note #4: Sun C++ Users</strong></span>
 146       </p>
 147 <p>
 148         Sun's compiler has a particularly interesting form of <code class="computeroutput"><span class="preprocessor">#include</span></code>,
 149         that will actually look for a file named <code class="computeroutput"><span class="identifier">array</span><span class="special">.</span><span class="identifier">SUNWCCh</span></code>
 150         if you <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">array</span><span class="special">&gt;</span></code>.
 151         What's more it won't include a standard header file that it thinks it's already
 152         seen. In order to make this library work with Sun's compiler you can either
 153         pass the undocumented compiler switch <span class="emphasis"><em>"-Qoption ccfe -nosunwcch"</em></span>
 154         to the compiler, or else you will need to set up the include paths as follows:
 155       </p>
 156 <p>
 157         1) boost-root/boost/tr1/tr1/sun<br> 2) boost-root/boost/tr1/tr1<br> 3)
 158         boost-root<br> 4) Any other standard library replacements (STLport for
 159         example).<br> 5) Your regular standard library.<br>
 160       </p>
 161 </div>
 162 </div>
 163 <div class="section">
 164 <div class="titlepage"><div><div><h3 class="title">
 165 <a name="boost_tr1.usage.writing_code"></a><a class="link" href="usage.html#boost_tr1.usage.writing_code" title="Writing Code">Writing Code</a>
 166 </h3></div></div></div>
 167 <p>
 168         Regardless of how the includes are setup, user code written to work with
 169         Boost.TR1 is exactly the same as code written to use a native tr1 implementation.
 170         That is, references to classes and functions need to explicitly use the
 171         <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span></code> namespace or a <code class="computeroutput"><span class="keyword">using</span>
 172         <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span></code> statement.
 173         For example,
 174       </p>
 175 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="string">"hello"</span><span class="special">);</span>
 176 </pre>
 177 <p>
 178         or
 179       </p>
 180 <pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">;</span>
 181 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="string">"hello"</span><span class="special">);</span>
 182 </pre>
 183 </div>
 184 </div>
 185 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 186 <td align="left"></td>
 187 <td align="right"><div class="copyright-footer">Copyright &#169; 2005 John Maddock<p>
 188         Distributed under the Boost Software License, Version 1.0. (See accompanying
 189         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 190       </p>
 191 </div></td>
 192 </tr></table>
 193 <hr>
 194 <div class="spirit-nav">
 195 <a accesskey="p" href="../boost_tr1.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_tr1.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="config.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 196 </div>
 197 </body>
 198 </html>