~barry/ubuntu/precise/boost1.46/debian-merge

<li><a class="reference internal" href="#build-a-simple-program-using-boost" id="id23">4   Build a Simple Program Using Boost</a><ul class="auto-toc">

<li><a class="reference internal" href="#errors-and-warnings" id="id24">4.1   Errors and Warnings</a></li>

</ul>

</li>

<li><a class="reference internal" href="#prepare-to-use-a-boost-library-binary" id="id25">5   Prepare to Use a Boost Library Binary</a><ul class="auto-toc">

<li><a class="reference internal" href="#easy-build-and-install" id="id26">5.1   Easy Build and Install</a></li>

<li><a class="reference internal" href="#or-build-custom-binaries" id="id27">5.2   Or, Build Custom Binaries</a><ul class="auto-toc">

<li><a class="reference internal" href="#identify-your-toolset" id="id29">5.2.2   Identify Your Toolset</a></li>

<li><a class="reference internal" href="#select-a-build-directory" id="id30">5.2.3   Select a Build Directory</a></li>

<li><a class="reference internal" href="#invoke-bjam" id="id31">5.2.4   Invoke <tt class="docutils literal">bjam</tt></a></li>

</ul>

</li>

<li><a class="reference internal" href="#expected-build-output" id="id32">5.3   Expected Build Output</a></li>

<li><a class="reference internal" href="#in-case-of-build-errors" id="id33">5.4   In Case of Build Errors</a></li>

</ul>

</li>

<li><a class="reference internal" href="#link-your-program-to-a-boost-library" id="id34">6   Link Your Program to a Boost Library</a><ul class="auto-toc">

<li><a class="reference internal" href="#library-naming" id="id35">6.1   Library Naming</a></li>

<li><a class="reference internal" href="#test-your-program" id="id36">6.2   Test Your Program</a></li>

</ul>

</li>

<li><a class="reference internal" href="#conclusion-and-further-resources" id="id37">7   Conclusion and Further Resources</a></li>

<li><a class="reference internal" href="#get-boost" id="id19">1   Get Boost</a></li>

<li><a class="reference internal" href="#the-boost-distribution" id="id20">2   The Boost Distribution</a></li>

<li><a class="reference internal" href="#header-only-libraries" id="id21">3   Header-Only Libraries</a></li>

<li><a class="reference internal" href="#build-a-simple-program-using-boost" id="id22">4   Build a Simple Program Using Boost</a><ul class="auto-toc">

<li><a class="reference internal" href="#errors-and-warnings" id="id23">4.1   Errors and Warnings</a></li>

</ul>

</li>

<li><a class="reference internal" href="#prepare-to-use-a-boost-library-binary" id="id24">5   Prepare to Use a Boost Library Binary</a><ul class="auto-toc">

<li><a class="reference internal" href="#easy-build-and-install" id="id25">5.1   Easy Build and Install</a></li>

<li><a class="reference internal" href="#or-build-custom-binaries" id="id26">5.2   Or, Build Custom Binaries</a><ul class="auto-toc">

<li><a class="reference internal" href="#install-boost-build" id="id27">5.2.1   Install Boost.Build</a></li>

<li><a class="reference internal" href="#identify-your-toolset" id="id28">5.2.2   Identify Your Toolset</a></li>

<li><a class="reference internal" href="#select-a-build-directory" id="id29">5.2.3   Select a Build Directory</a></li>

<li><a class="reference internal" href="#invoke-bjam" id="id30">5.2.4   Invoke <tt class="docutils literal">bjam</tt></a></li>

</ul>

</li>

<li><a class="reference internal" href="#expected-build-output" id="id31">5.3   Expected Build Output</a></li>

<li><a class="reference internal" href="#in-case-of-build-errors" id="id32">5.4   In Case of Build Errors</a></li>

</ul>

</li>

<li><a class="reference internal" href="#link-your-program-to-a-boost-library" id="id33">6   Link Your Program to a Boost Library</a><ul class="auto-toc">

<li><a class="reference internal" href="#library-naming" id="id34">6.1   Library Naming</a></li>

<li><a class="reference internal" href="#test-your-program" id="id35">6.2   Test Your Program</a></li>

</ul>

</li>

<li><a class="reference internal" href="#conclusion-and-further-resources" id="id36">7   Conclusion and Further Resources</a></li>

</ul>

</div>

<h1><a class="toc-backref" href="#id20">1   Get Boost</a></h1>

<h1><a class="toc-backref" href="#id19">1   Get Boost</a></h1>

<p>The most reliable way to get a copy of Boost is to download a

distribution from <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041">SourceForge</a>:</p>

distribution from <a class="reference external" href="http://www.boost.org/users/history/version_1_46_1.html">SourceForge</a>:</p>

<li><p class="first">Download <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041"><tt class="docutils literal">boost_1_46_0</tt><tt class="docutils literal">.tar.bz2</tt></a>.</p>

<li><p class="first">Download <a class="reference external" href="http://www.boost.org/users/history/version_1_46_1.html"><tt class="docutils literal">boost_1_46_1</tt><tt class="docutils literal">.tar.bz2</tt></a>.</p>

</li>

<li><p class="first">In the directory where you want to put the Boost installation,

execute</p>

tar --bzip2 -xf <em>/path/to/</em><tt class="docutils literal">boost_1_46_0</tt>.tar.bz2

tar --bzip2 -xf <em>/path/to/</em><tt class="docutils literal">boost_1_46_1</tt>.tar.bz2

</pre>

</li>

</ol>

reorganize the directory structure of the Boost distribution,

and/or rename the library binaries.<a class="footnote-reference" href="#packagers" id="id2"><sup>1</sup></a> If you have

any trouble, we suggest using an official Boost distribution

from <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041">SourceForge</a>.</p>

from <a class="reference external" href="http://www.boost.org/users/history/version_1_46_1.html">SourceForge</a>.</p>

</div>

</div>

<h1><a class="toc-backref" href="#id21">2   The Boost Distribution</a></h1>

<h1><a class="toc-backref" href="#id20">2   The Boost Distribution</a></h1>

<p>This is a sketch of the resulting directory structure:</p>

<strong>boost_1_46_0</strong><strong>/</strong> .................<em>The “boost root directory”</em>

<strong>boost_1_46_1</strong><strong>/</strong> .................<em>The “boost root directory”</em>

<strong>index.htm</strong> .........<em>A copy of www.boost.org starts here</em>

<strong>boost</strong><strong>/</strong> .........................<em>All Boost Header files</em>

136

</div>

137

<p>It's important to note the following:</p>

138

139

<li><p class="first">The path to the <strong>boost root directory</strong> (often <tt class="docutils literal">/usr/local/</tt><tt class="docutils literal">boost_1_46_0</tt>) is

139

<li><p class="first">The path to the <strong>boost root directory</strong> (often <tt class="docutils literal">/usr/local/</tt><tt class="docutils literal">boost_1_46_1</tt>) is

140

sometimes referred to as <tt class="docutils literal">$BOOST_ROOT</tt> in documentation and

141

mailing lists .</p>

142

</li>

166

167

</div>

168

169

<h1><a class="toc-backref" href="#id22">3   Header-Only Libraries</a></h1>

169

<h1><a class="toc-backref" href="#id21">3   Header-Only Libraries</a></h1>

170

<p>The first thing many people want to know is, “how do I build

171

Boost?” The good news is that often, there's nothing to build.</p>

172

213

214

</div>

215

216

<h1><a class="toc-backref" href="#id23">4   Build a Simple Program Using Boost</a></h1>

216

<h1><a class="toc-backref" href="#id22">4   Build a Simple Program Using Boost</a></h1>

217

<p>To keep things simple, let's start by using a header-only library.

218

The following program reads a sequence of integers from standard

219

input, uses Boost.Lambda to multiply each number by three, and

237

<p>Now, in the directory where you saved <tt class="docutils literal">example.cpp</tt>, issue the

238

following command:</p>

239

240

c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_46_0</tt> example.cpp -o example

240

c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_46_1</tt> example.cpp -o example

241

</pre>

242

<p>To test the result, type:</p>

243

247

248

249

250

<h2><a class="toc-backref" href="#id24">4.1   Errors and Warnings</a></h2>

250

<h2><a class="toc-backref" href="#id23">4.1   Errors and Warnings</a></h2>

251

<p>Don't be alarmed if you see compiler warnings originating in Boost

252

headers. We try to eliminate them, but doing so isn't always

253

practical.<a class="footnote-reference" href="#warnings" id="id5"><sup>3</sup></a> <strong>Errors are another matter</strong>. If you're

260

</div>

261

</div>

262

263

<h1><a class="toc-backref" href="#id25">5   Prepare to Use a Boost Library Binary</a></h1>

263

<h1><a class="toc-backref" href="#id24">5   Prepare to Use a Boost Library Binary</a></h1>

264

<p>If you want to use any of the separately-compiled Boost libraries,

265

you'll need to acquire library binaries.</p>

266

267

<h2><a class="toc-backref" href="#id26">5.1   Easy Build and Install</a></h2>

267

<h2><a class="toc-backref" href="#id25">5.1   Easy Build and Install</a></h2>

268

<p>Issue the following commands in the shell (don't type <tt class="docutils literal">$</tt>; that

269

represents the shell's prompt):</p>

270

271

<strong>$</strong> cd <em>path/to/</em><tt class="docutils literal">boost_1_46_0</tt>

271

<strong>$</strong> cd <em>path/to/</em><tt class="docutils literal">boost_1_46_1</tt>

272

<strong>$</strong> ./bootstrap.sh --help

273

</pre>

274

<p>Select your configuration options and invoke <tt class="docutils literal">./bootstrap.sh</tt> again

292

293

</div>

294

295

<h2><a class="toc-backref" href="#id27">5.2   Or, Build Custom Binaries</a></h2>

295

<h2><a class="toc-backref" href="#id26">5.2   Or, Build Custom Binaries</a></h2>

296

<p>If you're using a compiler other than your system's default, you'll

297

need to use <a class="reference external" href="../../tools/build/index.html">Boost.Build</a> to create binaries.</p>

298

<p>You'll also

306

307

308

309

310

<h3><a class="toc-backref" href="#id27">5.2.1   Install Boost.Build</a></h3>

309

311

<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> is a text-based system for developing, testing, and

310

installing software. To use it, you'll need an executable called

311

312

313

314

315

<p><tt class="docutils literal">bjam</tt> is the command-line tool that drives the Boost Build

316

system. To build Boost binaries, you'll invoke <tt class="docutils literal">bjam</tt> from the

317

Boost root.</p>

318

<p>We suggest you <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941">download a pre-built <tt class="docutils literal">bjam</tt> executable</a> for your platform.

319

Alternatively, you can build <tt class="docutils literal">bjam</tt> yourself using <a class="reference external" href="../../doc/html/jam/building.html">these

320

instructions</a>.</p>

321

<p>Move the <tt class="docutils literal">bjam</tt> executable into a directory in your PATH. You can

322

see the list of directories in your PATH, separated by colons,

323

by typing “<tt class="docutils literal">echo $PATH</tt>” at the command prompt.</p>

312

installing software. First, you'll need to build and

313

install it. To do this:</p>

314

315

<li>Go to the directory <tt class="docutils literal">tools</tt><tt class="docutils literal">/</tt><tt class="docutils literal">build</tt><tt class="docutils literal">/</tt><tt class="docutils literal">v2</tt><tt class="docutils literal">/</tt>.</li>

316

<li>Run <tt class="docutils literal">bootstrap.bat</tt></li>

317

<li>Run <tt class="docutils literal">bjam install <span class="pre">--prefix=</span></tt><em>PREFIX</em> where <em>PREFIX</em> is

318

the directory where you want Boost.Build to be installed</li>

319

<li>Add <em>PREFIX</em><tt class="docutils literal">/</tt><tt class="docutils literal">bin</tt> to your PATH environment variable.</li>

320

</ol>

324

321

</div>

325

322

326

<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id29">5.2.2   Identify Your Toolset</a></h3>

323

<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id28">5.2.2   Identify Your Toolset</a></h3>

327

324

<p>First, find the toolset corresponding to your compiler in the

328

325

following table (an up-to-date list is always available <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html">in the

329

326

Boost.Build documentation</a>).</p>

330

327

331

328

332

329

<p class="last">If you previously chose a toolset for the purposes of

333

<a class="reference external" href="../../doc/html/jam/building.html">building bjam</a>, you should assume it won't work and instead

330

<a class="reference external" href="../../doc/html/bbv2/installation.html">building bjam</a>, you should assume it won't work and instead

334

331

choose newly from the table below.</p>

335

332

</div>

336

333

422

419

<tt class="docutils literal"><span class="pre">borland-5.4.3</span></tt>. <tt class="docutils literal"> </tt></p>

423

420

</div>

424

421

425

<span id="id11"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id30">5.2.3   Select a Build Directory</a></h3>

422

<span id="id10"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id29">5.2.3   Select a Build Directory</a></h3>

426

423

<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while

427

424

building into the <strong>build directory</strong>. If your Boost root

428

425

directory is writable, this step isn't strictly necessary: by

430

427

purpose in your current working directory.</p>

431

428

</div>

432

429

433

<h3><a class="toc-backref" href="#id31">5.2.4   Invoke <tt class="docutils literal">bjam</tt></a></h3>

430

<h3><a class="toc-backref" href="#id30">5.2.4   Invoke <tt class="docutils literal">bjam</tt></a></h3>

434

431

<p>Change your current directory to the Boost root directory and

435

432

invoke <tt class="docutils literal">bjam</tt> as follows:</p>

436

433

437

bjam <strong>--build-dir=</strong><a class="reference internal" href="#id11"><em>build-directory</em></a> <strong>toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <tt class="docutils literal"> </tt> stage

434

bjam <strong>--build-dir=</strong><a class="reference internal" href="#id10"><em>build-directory</em></a> <strong>toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <tt class="docutils literal"> </tt> stage

438

435

</pre>

439

436

<p>For a complete description of these and other invocation options,

440

437

please see the <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html">Boost.Build documentation</a>.</p>

441

438

<p>For example, your session might look like this:</p>

442

439

443

$ cd ~/<tt class="docutils literal">boost_1_46_0</tt>

440

$ cd ~/<tt class="docutils literal">boost_1_46_1</tt>

444

441

$ bjam <strong>--build-dir=</strong>/tmp/build-boost <strong>toolset=</strong>gcc stage

445

442

</pre>

446

443

<p>That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “<tt class="docutils literal"><span class="pre">--build-type=complete</span></tt>”.</p>

479

476

</div>

480

477

</div>

481

478

482

<h2><a class="toc-backref" href="#id32">5.3   Expected Build Output</a></h2>

479

<h2><a class="toc-backref" href="#id31">5.3   Expected Build Output</a></h2>

483

480

<p>During the process of building Boost libraries, you can expect to

484

481

see some messages printed on the console. These may include</p>

485

482

<ul>

503

500

</ul>

504

501

</div>

505

502

506

<h2><a class="toc-backref" href="#id33">5.4   In Case of Build Errors</a></h2>

503

<h2><a class="toc-backref" href="#id32">5.4   In Case of Build Errors</a></h2>

507

504

<p>The only error messages you see when building Boost—if any—should

508

505

be related to the IOStreams library's support of zip and bzip2

509

506

formats as described <a class="reference external" href="../../libs/iostreams/doc/installation.html">here</a>. Install the relevant development

520

517

</div>

521

518

</div>

522

519

523

<h1><a class="toc-backref" href="#id34">6   Link Your Program to a Boost Library</a></h1>

520

<h1><a class="toc-backref" href="#id33">6   Link Your Program to a Boost Library</a></h1>

524

521

<p>To demonstrate linking with a Boost binary library, we'll use the

525

522

following simple program that extracts the subject lines from

526

523

emails. It uses the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> library, which has a

556

553

557

554

<li><p class="first">You can specify the full path to each library:</p>

558

555

559

$ c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_46_0</tt> example.cpp -o example <strong>\</strong>

556

$ c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_46_1</tt> example.cpp -o example <strong>\</strong>

560

557

<strong>~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a</strong>

561

558

</pre>

562

559

</li>

563

<li><p class="first">You can separately specify a directory to search (with <tt class="docutils literal"><span class="pre">-L</span></tt><em>directory</em>) and a library name to search for (with <tt class="docutils literal"><span class="pre">-l</span></tt><em>library</em>,<a class="footnote-reference" href="#lowercase-l" id="id15"><sup>2</sup></a> dropping the filename's leading <tt class="docutils literal">lib</tt> and trailing

560

<li><p class="first">You can separately specify a directory to search (with <tt class="docutils literal"><span class="pre">-L</span></tt><em>directory</em>) and a library name to search for (with <tt class="docutils literal"><span class="pre">-l</span></tt><em>library</em>,<a class="footnote-reference" href="#lowercase-l" id="id14"><sup>2</sup></a> dropping the filename's leading <tt class="docutils literal">lib</tt> and trailing

564

561

suffix (<tt class="docutils literal">.a</tt> in this case):</p>

565

562

566

$ c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_46_0</tt> example.cpp -o example <strong>\</strong>

563

$ c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_46_1</tt> example.cpp -o example <strong>\</strong>

567

564

<strong>-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36</strong>

568

565

</pre>

569

566

<p>As you can see, this method is just as terse as method A for one

578

575

<p>In both cases above, the bold text is what you'd add to <a class="reference internal" href="#build-a-simple-program-using-boost">the

579

576

command lines we explored earlier</a>.</p>

580

577

581

<h2><a class="toc-backref" href="#id35">6.1   Library Naming</a></h2>

578

<h2><a class="toc-backref" href="#id34">6.1   Library Naming</a></h2>

582

579

583

580

584

581

593

590

<dd><em>Prefix</em>: except on Microsoft Windows, every Boost library

594

591

name begins with this string. On Windows, only ordinary static

595

592

libraries use the <tt class="docutils literal">lib</tt> prefix; import libraries and DLLs do

596

not.<a class="footnote-reference" href="#distinct" id="id17"><sup>4</sup></a></dd>

593

not.<a class="footnote-reference" href="#distinct" id="id16"><sup>4</sup></a></dd>

597

594

<dt><tt class="docutils literal">boost_regex</tt></dt>

598

595

<dd><em>Library name</em>: all boost library filenames begin with <tt class="docutils literal">boost_</tt>.</dd>

599

596

636

633

<td>python-debugging=on</td>

637

634

</tr>

638

635

639

<td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id18"><sup>5</sup></a></td>

636

<td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id17"><sup>5</sup></a></td>

640

637

<td>variant=debug</td>

641

638

</tr>

642

639

674

671

675

672

</div>

676

673

677

<h2><a class="toc-backref" href="#id36">6.2   Test Your Program</a></h2>

674

<h2><a class="toc-backref" href="#id35">6.2   Test Your Program</a></h2>

678

675

<p>To test our subject extraction, we'll filter the following text

679

676

file. Copy it out of your browser and save it as <tt class="docutils literal">jayne.txt</tt>:</p>

680

677

714

711

</div>

715

712

</div>

716

713

717

<h1><a class="toc-backref" href="#id37">7   Conclusion and Further Resources</a></h1>

714

<h1><a class="toc-backref" href="#id36">7   Conclusion and Further Resources</a></h1>

718

715

<p>This concludes your introduction to Boost and to integrating it

719

716

with your programs. As you start using Boost in earnest, there are

720

717

surely a few additional points you'll wish we had covered. One day

725

722

mailing list</a>.</p>

726

723

727

724

<li><a class="reference external" href="../../tools/build/v2/index.html">Boost.Build reference manual</a></li>

728

<li><a class="reference external" href="../../tools/build/v2/engine/index.html">Boost.Jam reference manual</a></li>

729

725

<li><a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#users">Boost Users' mailing list</a></li>

730

726

<li><a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a></li>

731

<li><a class="reference external" href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2">Boost.Build Wiki</a></li>

732

727

<li><a class="reference external" href="../../libs/index.html">Index of all Boost library documentation</a></li>

733

728

</ul>

734

729

751

746

752

747

753

748

754

<tr><td class="label"><a class="fn-backref" href="#id15">[2]</a></td><td>That option is a dash followed by a lowercase “L”

749

<tr><td class="label"><a class="fn-backref" href="#id14">[2]</a></td><td>That option is a dash followed by a lowercase “L”

755

750

character, which looks very much like a numeral 1 in some fonts.</td></tr>

756

751

</tbody>

757

752

</table>

772

767

773

768

774

769

775

<tr><td class="label"><a class="fn-backref" href="#id17">[4]</a></td><td>This convention distinguishes the static version of

770

<tr><td class="label"><a class="fn-backref" href="#id16">[4]</a></td><td>This convention distinguishes the static version of

776

771

a Boost library from the import library for an

777

772

identically-configured Boost DLL, which would otherwise have the

778

773

same name.</td></tr>

781

776

782

777

783

778

784

<tr><td class="label"><a class="fn-backref" href="#id18">[5]</a></td><td>These libraries were compiled without optimization

779

<tr><td class="label"><a class="fn-backref" href="#id17">[5]</a></td><td>These libraries were compiled without optimization

785

780

or inlining, with full debug symbols enabled, and without

786

781

<tt class="docutils literal">NDEBUG</tt> <tt class="docutils literal">#define</tt>d. Although it's true that sometimes

787

782

these choices don't affect binary compatibility with other

Older »