boostorg/regex
1
0
Fork 1
mirror of https://github.com/boostorg/regex.git synced 2025-06-30 14:20:58 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
d08bfeff255f7c49aeaa87d97e983bc7eb226ac0
regex/doc/html/boost_regex/install.html
John Maddock d08bfeff25 Add checked constructors to the Unicode iterators that need them. 
Update icu support code to use the new checking-constructors.
Update tests to check the full Unicode character range (as of Unicode V6).
Add minimal docs describing the iterators.

[SVN r73271]
2011-07-21 10:01:09 +00:00

434 lines
26 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Building and Installing the Library</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="Boost.Regex">
<link rel="up" href="../index.html" title="Boost.Regex">
<link rel="prev" href="configuration/tuning.html" title="Algorithm Tuning">
<link rel="next" href="introduction_and_overview.html" title="Introduction and Overview">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="configuration/tuning.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="introduction_and_overview.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_regex.install"></a><a class="link" href="install.html" title="Building and Installing the Library">Building and Installing the Library</a>
</h2></div></div></div>
<p>
When you extract the library from its zip file, you must preserve its internal
directory structure (for example by using the -d option when extracting). If
you didn't do that when extracting, then you'd better stop reading this, delete
the files you just extracted, and try again!
</p>
<p>
This library should not need configuring before use; most popular compilers/standard
libraries/platforms are already supported "as is". If you do experience
configuration problems, or just want to test the configuration with your compiler,
then the process is the same as for all of boost; see the <a href="../../../../config/index.html" target="_top">configuration
library documentation</a>.
</p>
<p>
The library will encase all code inside namespace boost.
</p>
<p>
Unlike some other template libraries, this library consists of a mixture of
template code (in the headers) and static code and data (in cpp files). Consequently
it is necessary to build the library's support code into a library or archive
file before you can use it, instructions for specific platforms are as follows:
</p>
<a name="boost_regex.install.building_with_bjam"></a><h5>
<a name="boost_regex.install.building_with_bjam-heading"></a>
<a class="link" href="install.html#boost_regex.install.building_with_bjam">Building with bjam</a>
</h5>
<p>
This is now the preferred method for building and installing this library,
please refer to the <a href="../../../../../more/getting_started.html" target="_top">getting
started guide</a> for more information.
</p>
<a name="boost_regex.install.building_with_unicode_and_icu_support"></a><h5>
<a name="boost_regex.install.building_with_unicode_and_icu_support-heading"></a>
<a class="link" href="install.html#boost_regex.install.building_with_unicode_and_icu_support">Building
With Unicode and ICU Support</a>
</h5>
<p>
Boost.Regex is now capable of performing a configuration check to test whether
ICU is already installed in your compiler's search paths. When you build you
should see a message like this:
</p>
<pre class="programlisting"><span class="identifier">Performing</span> <span class="identifier">configuration</span> <span class="identifier">checks</span>
<span class="special">-</span> <span class="identifier">has_icu</span> <span class="identifier">builds</span> <span class="special">:</span> <span class="identifier">yes</span>
</pre>
<p>
Whick means that ICU has been found, and support for it will be enabled in
the library build.
</p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
If you don't want the regex library to use ICU then build with the "--disable-icu"
command line option.
</p></td></tr>
</table></div>
<p>
If instead you see:
</p>
<pre class="programlisting"><span class="identifier">Performing</span> <span class="identifier">configuration</span> <span class="identifier">checks</span>
<span class="special">-</span> <span class="identifier">has_icu</span> <span class="identifier">builds</span> <span class="special">:</span> <span class="identifier">no</span>
</pre>
<p>
Then ICU was not found and support for it will not be compiled into the library.
If you think that it should have been found, then you will need to take a look
at the contents of the file <span class="emphasis"><em>boost-root/bin.v2/config.log</em></span>
for the actual error messages obtained when the build carried out the configuration
check. You will then need to fix these errors by ensuring your compiler gets
invoked with the correct options, for example:
</p>
<pre class="programlisting">bjam include=some-include-path --toolset=toolset-name install</pre>
<p>
will add "some-include-path" to your compilers header include path,
or if ICU has been built with non-standard names for it's binaries, then:
</p>
<pre class="programlisting">bjam -sICU_LINK="linker-options-for-icu" --toolset=toolset-name install</pre>
<p>
Will use <span class="emphasis"><em>"linker-options-for-icu"</em></span> when linking
the library rather than the default ICU binary names.
</p>
<p>
You might also need to use the options "cxxflags=-option" and "linkflags=-option"
to set compiler and linker specific options.
</p>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
Configuration results are cached - if you try rebuilding with different compiler
options then add an "-a" to the bjam command line to force all
targets to be rebuilt.
</p></td></tr>
</table></div>
<p>
If ICU is not already in your compiler's path, but instead headers, libraries
and binaries are located at <span class="emphasis"><em>path-to-icu/include</em></span>, <span class="emphasis"><em>path-to-icu/lib</em></span>
and <span class="emphasis"><em>path-to-icu/bin</em></span> respectively then you need to set
the environment variable <code class="computeroutput"><span class="identifier">ICU_PATH</span></code>
to point to the root directory of your ICU installation: this typically happens
if you're building with MSVC. For example if ICU was installed to <code class="computeroutput"><span class="identifier">c</span><span class="special">:\</span><span class="identifier">download</span><span class="special">\</span><span class="identifier">icu</span></code> you
might use:
</p>
<pre class="programlisting">bjam -sICU_PATH=c:\download\icu --toolset=toolset-name install</pre>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
ICU is a C++ library just like Boost is, as such your copy of ICU must have
been built with the same C++ compiler (and compiler version) that you are
using to build Boost. Boost.Regex will not work correctly unless you ensure
that this is the case: it is up to you to ensure that the version of ICU
you are using is binary compatible with the toolset you use to build Boost.
</p></td></tr>
</table></div>
<p>
And finally, if you want to build/test with multiple compiler versions, all
with different ICU builds, then the only way to achieve that currently is to
modify your user-config.jam so that each toolset has the necessary compiler/linker
options set so that ICU is found automatically by the configuration step (providing
the ICU binaries use the standard names, all you have to add is the appropriate
header-include and linker-search paths).
</p>
<a name="boost_regex.install.building_via_makefiles"></a><h5>
<a name="boost_regex.install.building_via_makefiles-heading"></a>
<a class="link" href="install.html#boost_regex.install.building_via_makefiles">Building via makefiles</a>
</h5>
<a name="boost_regex.install.borland_c___builder_"></a><h6>
<a name="boost_regex.install.borland_c___builder_-heading"></a>
<a class="link" href="install.html#boost_regex.install.borland_c___builder_">Borland C++ Builder:</a>
</h6>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Open up a console window and change to the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;\</span><span class="identifier">libs</span><span class="special">\</span><span class="identifier">regex</span><span class="special">\</span><span class="identifier">build</span></code> directory.
</li>
<li class="listitem">
Select the appropriate makefile (bcb4.mak for C++ Builder 4, bcb5.mak for
C++ Builder 5, and bcb6.mak for C++ Builder 6).
</li>
<li class="listitem">
Invoke the makefile (pass the full path to your version of make if you
have more than one version installed, the makefile relies on the path to
make to obtain your C++ Builder installation directory and tools) for example:
</li>
</ul></div>
<pre class="programlisting">make -fbcb5.mak</pre>
<p>
The build process will build a variety of .lib and .dll files (the exact number
depends upon the version of Borland's tools you are using) the .lib and dll
files will be in a sub-directory called bcb4 or bcb5 depending upon the makefile
used. To install the libraries into your development system use:
</p>
<pre class="programlisting">make -fbcb5.mak install</pre>
<p>
library files will be copied to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">BCROOT</span><span class="special">&gt;/</span><span class="identifier">lib</span></code> and the dll's to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">BCROOT</span><span class="special">&gt;/</span><span class="identifier">bin</span></code>, where <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">BCROOT</span><span class="special">&gt;</span></code>
corresponds to the install path of your Borland C++ tools.
</p>
<p>
You may also remove temporary files created during the build process (excluding
lib and dll files) by using:
</p>
<pre class="programlisting">make -fbcb5.mak clean</pre>
<p>
Finally when you use Boost.Regex it is only necessary for you to add the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;</span></code> root director to your list of include directories
for that project. It is not necessary for you to manually add a .lib file to
the project; the headers will automatically select the correct .lib file for
your build mode and tell the linker to include it. There is one caveat however:
the library can not tell the difference between VCL and non-VCL enabled builds
when building a GUI application from the command line, if you build from the
command line with the 5.5 command line tools then you must define the pre-processor
symbol _NO_VCL in order to ensure that the correct link libraries are selected:
the C++ Builder IDE normally sets this automatically. Hint, users of the 5.5
command line tools may want to add a -D_NO_VCL to bcc32.cfg in order to set
this option permanently.
</p>
<p>
If you would prefer to do a dynamic link to the regex libraries when using
the dll runtime then define BOOST_REGEX_DYN_LINK (you must do this if you want
to use Boost.Regex in multiple dll's), otherwise Boost.Regex will be statically
linked by default.
</p>
<p>
If you want to suppress automatic linking altogether (and supply your own custom
build of the lib) then define BOOST_REGEX_NO_LIB.
</p>
<p>
If you are building with C++ Builder 6, you will find that <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
can not be used in a pre-compiled header (the actual problem is in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">locale</span><span class="special">&gt;</span></code> which gets included by <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>),
if this causes problems for you, then try defining BOOST_NO_STD_LOCALE when
building, this will disable some features throughout boost, but may save you
a lot in compile times!
</p>
<a name="boost_regex.install.microsoft_visual_c___6__7__7_1_and_8"></a><h5>
<a name="boost_regex.install.microsoft_visual_c___6__7__7_1_and_8-heading"></a>
<a class="link" href="install.html#boost_regex.install.microsoft_visual_c___6__7__7_1_and_8">Microsoft
Visual C++ 6, 7, 7.1 and 8</a>
</h5>
<p>
You need version 6 or later of MSVC to build this library. If you are using
VC5 then you may want to look at one of the previous releases of this library.
</p>
<p>
Open up a command prompt, which has the necessary MSVC environment variables
defined (for example by using the batch file Vcvars32.bat installed by the
Visual Studio installation), and change to the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;\</span><span class="identifier">libs</span><span class="special">\</span><span class="identifier">regex</span><span class="special">\</span><span class="identifier">build</span> <span class="identifier">directory</span></code>.
</p>
<p>
Select the correct makefile - vc6.mak for "vanilla" Visual C++ 6
or vc6-stlport.mak if you are using STLPort.
</p>
<p>
Invoke the makefile like this:
</p>
<pre class="programlisting">nmake -fvc6.mak</pre>
<p>
You will now have a collection of lib and dll files in a "vc6" subdirectory,
to install these into your development system use:
</p>
<pre class="programlisting">nmake -fvc6.mak install</pre>
<p>
The lib files will be copied to your <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">VC6</span><span class="special">&gt;\</span><span class="identifier">lib</span></code> directory and the dll files to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">VC6</span><span class="special">&gt;\</span><span class="identifier">bin</span></code>, where <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">VC6</span><span class="special">&gt;</span></code> is
the root of your Visual C++ 6 installation.
</p>
<p>
You can delete all the temporary files created during the build (excluding
lib and dll files) using:
</p>
<pre class="programlisting">nmake -fvc6.mak clean </pre>
<p>
If you want to build with ICU support, then you need to pass the path to your
ICU directory to the makefile, for example with:
</p>
<pre class="programlisting">nmake ICU_PATH=c:\open-source\icu -fvc71.mak install</pre>
<p>
Finally when you use Boost.Regex it is only necessary for you to add the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;</span></code> root directory to your list of include
directories for that project. It is not necessary for you to manually add a
.lib file to the project; the headers will automatically select the correct
.lib file for your build mode and tell the linker to include it.
</p>
<p>
Note that if you want to dynamically link to the regex library when using the
dynamic C++ runtime, define BOOST_REGEX_DYN_LINK when building your project.
</p>
<p>
If you want to add the source directly to your project then define BOOST_REGEX_NO_LIB
to disable automatic library selection.
</p>
<p>
There are several important caveats to remember when using Boost.Regex with
Microsoft's Compiler:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
There have been some reports of compiler-optimization bugs affecting this
library, (particularly with VC6 versions prior to service patch 5) the
workaround is to build the library using /Oityb1 rather than /O2. That
is to use all optimization settings except /Oa. This problem is reported
to affect some standard library code as well ( in fact I'm not sure if
the problem is with the regex code or the underlying standard library),
so it's probably worthwhile applying this workaround in normal practice
in any case.
</li>
<li class="listitem">
If you have replaced the C++ standard library that comes with VC6, then
when you build the library you must ensure that the environment variables
"INCLUDE" and "LIB" have been updated to reflect the
include and library paths for the new library - see vcvars32.bat (part
of your Visual Studio installation) for more details.
</li>
<li class="listitem">
If you are building with the full STLPort v4.x, then use the vc6-stlport.mak
file provided and set the environment variable STLPORT_PATH to point to
the location of your STLPort installation (Note that the full STLPort libraries
appear not to support single-thread static builds).
</li>
<li class="listitem">
If you are building your application with /Zc:wchar_t then you will need
to modify the makefile to add /Zc:wchar_t before building the library.
</li>
</ul></div>
<a name="boost_regex.install.gcc_2_95_and_later_"></a><h6>
<a name="boost_regex.install.gcc_2_95_and_later_-heading"></a>
<a class="link" href="install.html#boost_regex.install.gcc_2_95_and_later_">GCC(2.95 and later)</a>
</h6>
<p>
You can build with gcc using the normal boost Jamfile in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">regex</span><span class="special">/</span><span class="identifier">build</span></code>, alternatively
there is a conservative makefile for the g++ compiler. From the command prompt
change to the &lt;boost&gt;/libs/regex/build directory and type:
</p>
<pre class="programlisting">make -fgcc.mak </pre>
<p>
At the end of the build process you should have a gcc sub-directory containing
release and debug versions of the library (libboost_regex.a and libboost_regex_debug.a).
When you build projects that use regex++, you will need to add the boost install
directory to your list of include paths and add &lt;boost&gt;/libs/regex/build/gcc/libboost_regex.a
to your list of library files.
</p>
<p>
There is also a makefile to build the library as a shared library:
</p>
<pre class="programlisting">make -fgcc-shared.mak</pre>
<p>
which will build libboost_regex.so and libboost_regex_debug.so.
</p>
<p>
Both of the these makefiles support the following environment variables:
</p>
<p>
ICU_PATH: tells the makefile to build with Unicode support, set to the path
where your ICU installation is located, for example with: make ICU_PATH=/usr/local
install -fgcc.mak
</p>
<p>
CXXFLAGS: extra compiler options - note that this applies to both the debug
and release builds.
</p>
<p>
INCLUDES: additional include directories.
</p>
<p>
LDFLAGS: additional linker options.
</p>
<p>
LIBS: additional library files.
</p>
<p>
For the more adventurous there is a configure script in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">config</span></code>;
see the <a href="../../../../config/index.html" target="_top">config library documentation</a>.
</p>
<a name="boost_regex.install.sun_workshop_6_1"></a><h6>
<a name="boost_regex.install.sun_workshop_6_1-heading"></a>
<a class="link" href="install.html#boost_regex.install.sun_workshop_6_1">Sun Workshop 6.1</a>
</h6>
<p>
There is a makefile for the sun (6.1) compiler (C++ version 3.12). From the
command prompt change to the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">regex</span><span class="special">/</span><span class="identifier">build</span></code> directory
and type:
</p>
<pre class="programlisting">dmake -f sunpro.mak </pre>
<p>
At the end of the build process you should have a sunpro sub-directory containing
single and multithread versions of the library (libboost_regex.a, libboost_regex.so,
libboost_regex_mt.a and libboost_regex_mt.so). When you build projects that
use Boost.Regex, you will need to add the boost install directory to your list
of include paths and add <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">&gt;/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">regex</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">sunpro</span><span class="special">/</span></code> to
your library search path.
</p>
<p>
Both of the these makefiles support the following environment variables:
</p>
<p>
CXXFLAGS: extra compiler options - note that this applies to both the single
and multithreaded builds.
</p>
<p>
INCLUDES: additional include directories.
</p>
<p>
LDFLAGS: additional linker options.
</p>
<p>
LIBS: additional library files.
</p>
<p>
LIBSUFFIX: a suffix to mangle the library name with (defaults to nothing).
</p>
<p>
This makefile does not set any architecture specific options like -xarch=v9,
you can set these by defining the appropriate macros, for example:
</p>
<pre class="programlisting">dmake CXXFLAGS="-xarch=v9" LDFLAGS="-xarch=v9" LIBSUFFIX="_v9" -f sunpro.mak</pre>
<p>
will build v9 variants of the regex library named libboost_regex_v9.a etc.
</p>
<a name="boost_regex.install.makefiles_for_other_compilers"></a><h6>
<a name="boost_regex.install.makefiles_for_other_compilers-heading"></a>
<a class="link" href="install.html#boost_regex.install.makefiles_for_other_compilers">Makefiles
for Other compilers</a>
</h6>
<p>
There is a generic makefile (generic.mak ) provided in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">-</span><span class="identifier">root</span><span class="special">&gt;/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">regex</span><span class="special">/</span><span class="identifier">build</span></code> - see that makefile for details of
environment variables that need to be set before use.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 1998-2010 John Maddock<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="configuration/tuning.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="introduction_and_overview.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink