]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. Copyright David Abrahams 2006. Distributed under the Boost |
2 | .. Software License, Version 1.0. (See accompanying | |
3 | .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
4 | ||
5 | ============================================= | |
6 | |(logo)|__ Getting Started on Unix Variants | |
7 | ============================================= | |
8 | ||
9 | .. meta:: | |
10 | :description: Getting Started with Boost on Unix Variants (including Linux and MacOS) | |
11 | ||
12 | .. |(logo)| image:: ../../boost.png | |
13 | :alt: Boost | |
14 | :class: boost-logo | |
15 | ||
16 | __ ../../index.htm | |
17 | ||
18 | .. section-numbering:: | |
19 | ||
20 | .. maybe we don't need this | |
21 | .. Admonition:: A note to Cygwin_ and MinGW_ users | |
22 | ||
23 | If you plan to build from the Cygwin_ bash shell, you're in the | |
24 | right place. If you plan to use your tools from the Windows | |
25 | command prompt, you should follow the instructions for `getting | |
26 | started on Windows`_. Other command shells, such as MinGW_\ 's | |
27 | MSYS, are not supported—they may or may not work. | |
28 | ||
29 | .. _`Getting Started on Windows`: windows.html | |
30 | .. _Cygwin: http://www.cygwin.com | |
31 | .. _MinGW: http://mingw.org | |
32 | ||
33 | .. Contents:: Index | |
34 | ||
35 | Get Boost | |
36 | ========= | |
37 | ||
38 | The most reliable way to get a copy of Boost is to download a | |
39 | distribution from SourceForge_: | |
40 | ||
41 | .. _SourceForge: `sf-download`_ | |
42 | ||
43 | 1. Download |boost.tar.bz2|_. | |
44 | ||
45 | 2. In the directory where you want to put the Boost installation, | |
46 | execute | |
47 | ||
48 | .. parsed-literal:: | |
49 | ||
50 | tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2 | |
51 | ||
52 | .. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2`` | |
53 | ||
54 | .. _`boost.tar.bz2`: `sf-download`_ | |
55 | ||
56 | .. Admonition:: Other Packages | |
57 | ||
58 | RedHat, Debian, and other distribution packagers supply Boost | |
59 | library packages, however you may need to adapt these | |
60 | instructions if you use third-party packages, because their | |
61 | creators usually choose to break Boost up into several packages, | |
62 | reorganize the directory structure of the Boost distribution, | |
63 | and/or rename the library binaries. [#packagers]_ If you have | |
64 | any trouble, we suggest using an official Boost distribution | |
65 | from SourceForge_. | |
66 | ||
67 | .. include:: detail/distro.rst | |
68 | ||
69 | .. include:: detail/header-only.rst | |
70 | ||
71 | .. include:: detail/build-simple-head.rst | |
72 | ||
73 | Now, in the directory where you saved ``example.cpp``, issue the | |
74 | following command: | |
75 | ||
76 | .. parsed-literal:: | |
77 | ||
78 | c++ -I |root| example.cpp -o example | |
79 | ||
80 | To test the result, type: | |
81 | ||
82 | .. parsed-literal:: | |
83 | ||
84 | echo 1 2 3 | ./example | |
85 | ||
86 | .. include:: detail/errors-and-warnings.rst | |
87 | ||
88 | .. include:: detail/binary-head.rst | |
89 | ||
90 | Easy Build and Install | |
91 | ---------------------- | |
92 | ||
93 | Issue the following commands in the shell (don't type ``$``; that | |
94 | represents the shell's prompt): | |
95 | ||
96 | .. parsed-literal:: | |
97 | ||
98 | **$** cd |root| | |
99 | **$** ./bootstrap.sh --help | |
100 | ||
101 | Select your configuration options and invoke ``./bootstrap.sh`` again | |
102 | without the ``--help`` option. Unless you have write permission in | |
103 | your system's ``/usr/local/`` directory, you'll probably want to at | |
104 | least use | |
105 | ||
106 | .. parsed-literal:: | |
107 | ||
108 | **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix* | |
109 | ||
110 | to install somewhere else. Also, consider using the | |
111 | ``--show-libraries`` and ``--with-libraries=``\ *library-name-list* options to limit the | |
112 | long wait you'll experience if you build everything. Finally, | |
113 | ||
114 | .. parsed-literal:: | |
115 | ||
116 | **$** ./b2 install | |
117 | ||
118 | will leave Boost binaries in the ``lib/`` subdirectory of your | |
119 | installation prefix. You will also find a copy of the Boost | |
120 | headers in the ``include/`` subdirectory of the installation | |
121 | prefix, so you can henceforth use that directory as an ``#include`` | |
122 | path in place of the Boost root directory. | |
123 | ||
124 | |next|__ | |
125 | ||
126 | __ `Link Your Program to a Boost Library`_ | |
127 | ||
128 | Or, Build Custom Binaries | |
129 | ------------------------- | |
130 | ||
131 | If you're using a compiler other than your system's default, you'll | |
132 | need to use Boost.Build_ to create binaries. | |
133 | ||
134 | You'll also | |
135 | use this method if you need a nonstandard build variant (see the | |
136 | `Boost.Build documentation`_ for more details). | |
137 | ||
138 | .. include:: detail/build-from-source-head.rst | |
139 | ||
140 | For example, your session might look like this: | |
141 | ||
142 | .. parsed-literal:: | |
143 | ||
144 | $ cd ~/|boost_ver| | |
145 | $ b2 **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage | |
146 | ||
147 | That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”. | |
148 | ||
149 | .. include:: detail/build-from-source-tail.rst | |
150 | ||
151 | .. include:: detail/link-head.rst | |
152 | ||
153 | There are two main ways to link to libraries: | |
154 | ||
155 | A. You can specify the full path to each library: | |
156 | ||
157 | .. parsed-literal:: | |
158 | ||
159 | $ c++ -I |root| example.cpp -o example **\\** | |
160 | **~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a** | |
161 | ||
162 | B. You can separately specify a directory to search (with ``-L``\ | |
163 | *directory*) and a library name to search for (with ``-l``\ | |
164 | *library*, [#lowercase-l]_ dropping the filename's leading ``lib`` and trailing | |
165 | suffix (``.a`` in this case): | |
166 | ||
167 | .. parsed-literal:: | |
168 | ||
169 | $ c++ -I |root| example.cpp -o example **\\** | |
170 | **-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36** | |
171 | ||
172 | As you can see, this method is just as terse as method A for one | |
173 | library; it *really* pays off when you're using multiple | |
174 | libraries from the same directory. Note, however, that if you | |
175 | use this method with a library that has both static (``.a``) and | |
176 | dynamic (``.so``) builds, the system may choose one | |
177 | automatically for you unless you pass a special option such as | |
178 | ``-static`` on the command line. | |
179 | ||
180 | In both cases above, the bold text is what you'd add to `the | |
181 | command lines we explored earlier`__. | |
182 | ||
183 | __ `build a simple program using boost`_ | |
184 | ||
185 | Library Naming | |
186 | -------------- | |
187 | ||
188 | .. include:: detail/library-naming.rst | |
189 | ||
190 | .. include:: detail/test-head.rst | |
191 | ||
192 | If you linked to a shared library, you may need to prepare some | |
193 | platform-specific settings so that the system will be able to find | |
194 | and load it when your program is run. Most platforms have an | |
195 | environment variable to which you can add the directory containing | |
196 | the library. On many platforms (Linux, FreeBSD) that variable is | |
197 | ``LD_LIBRARY_PATH``, but on MacOS it's ``DYLD_LIBRARY_PATH``, and | |
198 | on Cygwin it's simply ``PATH``. In most shells other than ``csh`` | |
199 | and ``tcsh``, you can adjust the variable as follows (again, don't | |
200 | type the ``$``\ —that represents the shell prompt): | |
201 | ||
202 | .. parsed-literal:: | |
203 | ||
204 | **$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ } | |
205 | **$** export *VARIABLE_NAME* | |
206 | ||
207 | On ``csh`` and ``tcsh``, it's | |
208 | ||
209 | .. parsed-literal:: | |
210 | ||
211 | **$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ } | |
212 | ||
213 | Once the necessary variable (if any) is set, you can run your | |
214 | program as follows: | |
215 | ||
216 | .. parsed-literal:: | |
217 | ||
218 | **$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt | |
219 | ||
220 | The program should respond with the email subject, “Will Success | |
221 | Spoil Rock Hunter?” | |
222 | ||
223 | .. include:: detail/conclusion.rst | |
224 | ||
225 | ------------------------------ | |
226 | ||
227 | .. [#packagers] If developers of Boost packages would like to work | |
228 | with us to make sure these instructions can be used with their | |
229 | packages, we'd be glad to help. Please make your interest known | |
230 | to the `Boost developers' list`_. | |
231 | ||
232 | .. _Boost developers' list: http://www.boost.org/more/mailing_lists.htm#main | |
233 | ||
234 | .. [#lowercase-l] That option is a dash followed by a lowercase “L” | |
235 | character, which looks very much like a numeral 1 in some fonts. | |
236 | ||
237 | .. |build-type-complete| replace:: `` `` | |
238 | ||
239 | .. include:: detail/common-footnotes.rst | |
240 | .. include:: detail/release-variables.rst | |
241 | .. include:: detail/common-unix.rst | |
242 | .. include:: detail/links.rst |