ICU-7132 add section with recommended build options
X-SVN-Rev: 26615
This commit is contained in:
Markus Scherer
parent
aedb406d05
commit
df6548d8bf
@ -44,6 +44,8 @@
|
||||
<ul >
|
||||
<li><a href="#HowToBuildSupported">Supported Platforms</a></li>
|
||||
|
||||
<li><a href="#RecBuild">Recommended Build Options</a></li>
|
||||
|
||||
<li><a href="#HowToBuildWindows">Windows</a></li>
|
||||
|
||||
<li><a href="#HowToBuildCygwin">Cygwin</a></li>
|
||||
@ -796,6 +798,144 @@
|
||||
there recently</dd>
|
||||
</dl>
|
||||
|
||||
<h3><a name="RecBuild" href="#RecBuild" id=
|
||||
"RecBuild">Recommended Build Options</a></h3>
|
||||
|
||||
<p>Depending on the platform and the type of installation,
|
||||
we recommend a small number of modifications and build options.</p>
|
||||
<ul>
|
||||
<li><b>Namespace:</b> By default, unicode/uversion.h has
|
||||
"using namespace icu;" which defeats much of the purpose of the namespace.
|
||||
(This is for historical reasons: Originally, ICU4C did not use namespaces,
|
||||
and some compilers did not support them. The default "using" statement
|
||||
preserves source code compatibility.)<br>
|
||||
We recommend you turn this off via <code>-DU_USING_ICU_NAMESPACE=0</code>
|
||||
or by modifying unicode/uversion.h:
|
||||
<pre>Index: source/common/unicode/uversion.h
|
||||
===================================================================
|
||||
--- source/common/unicode/uversion.h (revision 26606)
|
||||
+++ source/common/unicode/uversion.h (working copy)
|
||||
@@ -180,7 +180,8 @@
|
||||
# define U_NAMESPACE_QUALIFIER U_ICU_NAMESPACE::
|
||||
|
||||
# ifndef U_USING_ICU_NAMESPACE
|
||||
-# define U_USING_ICU_NAMESPACE 1
|
||||
+ // Set to 0 to force namespace declarations in ICU usage.
|
||||
+# define U_USING_ICU_NAMESPACE 0
|
||||
# endif
|
||||
# if U_USING_ICU_NAMESPACE
|
||||
U_NAMESPACE_USE
|
||||
</pre>
|
||||
ICU call sites then either qualify ICU types explicitly,
|
||||
for example <code>icu::UnicodeString</code>,
|
||||
or do <code>using icu::UnicodeString;</code> where appropriate.</li>
|
||||
<li><b>Hardcode the default charset to UTF-8:</b> On platforms where
|
||||
the default charset is always UTF-8,
|
||||
like MacOS X and some Linux distributions,
|
||||
we recommend hardcoding ICU's default charset to UTF-8.
|
||||
This means that some implementation code becomes simpler and faster,
|
||||
and statically linked ICU libraries become smaller.
|
||||
(See the <a href="http://icu-project.org/apiref/icu4c/utypes_8h.html#0a33e1edf3cd23d9e9c972b63c9f7943">U_CHARSET_IS_UTF8</a>
|
||||
API documentation for more details.)<br>
|
||||
You can <code>-DU_CHARSET_IS_UTF8=1</code> or modify unicode/utypes.h:
|
||||
<pre>Index: source/common/unicode/utypes.h
|
||||
===================================================================
|
||||
--- source/common/unicode/utypes.h (revision 26606)
|
||||
+++ source/common/unicode/utypes.h (working copy)
|
||||
@@ -160,7 +160,7 @@
|
||||
* @see UCONFIG_NO_CONVERSION
|
||||
*/
|
||||
#ifndef U_CHARSET_IS_UTF8
|
||||
-# define U_CHARSET_IS_UTF8 0
|
||||
+# define U_CHARSET_IS_UTF8 1
|
||||
#endif
|
||||
|
||||
/*===========================================================================*/
|
||||
</pre></li>
|
||||
<li><b>.dat file:</b> By default, the ICU data is built into
|
||||
a shared library (DLL). This is convenient because it requires no
|
||||
install-time or runtime configuration,
|
||||
but the library is platform-specific and cannot be modified.
|
||||
A .dat package file makes the opposite trade-off:
|
||||
Platform-portable (except for endianness and charset family, which
|
||||
can be changed with the icupkg tool)
|
||||
and modifiable (also with the icupkg tool).
|
||||
If a path is set, then single data files (e.g., .res files)
|
||||
can be copied to that location to provide new locale data
|
||||
or conversion tables etc.<br>
|
||||
The only drawback with a .dat package file is that the application
|
||||
needs to provide ICU with the file system path to the package file
|
||||
(e.g., by calling <code>u_setDataDirectory()</code>)
|
||||
or with a pointer to the data (<code>udata_setCommonData()</code>)
|
||||
before other ICU API calls.
|
||||
This is usually easy if ICU is used from an application where
|
||||
<code>main()</code> takes care of such initialization.
|
||||
It may be hard if ICU is shipped with
|
||||
another shared library (such as the Xerces-C++ XML parser)
|
||||
which does not control <code>main()</code>.<br>
|
||||
See the <a href="http://userguide.icu-project.org/icudata">User Guide ICU Data</a>
|
||||
chapter for more details.<br>
|
||||
If possible, we recommend building the .dat package.
|
||||
Specify <code>--with-data-packaging=archive</code>
|
||||
on the configure command line, as in<br>
|
||||
<code>runConfigureICU Linux --with-data-packaging=archive</code><br>
|
||||
(Read the configure script's output for further instructions.
|
||||
On Windows, the Visual Studio build generates both the .dat package
|
||||
and the data DLL.)<br>
|
||||
Be sure to install and use the tiny stubdata library
|
||||
rather than the large data DLL.</li>
|
||||
<li><b>Static libraries:</b> It may make sense to build the ICU code
|
||||
into static libraries (.a) rather than shared libraries (.so/.dll).
|
||||
Static linking reduces the overall size of the binary by removing
|
||||
code that is never called.<br>
|
||||
Example configure command line:<br>
|
||||
<code>runConfigureICU Linux --enable-static --disable-shared</code></li>
|
||||
<li><b>Out-of-source build:</b> It is usually desirable to keep the ICU
|
||||
source file tree clean and have build output files written to
|
||||
a different location. This is called an "out-of-source build".
|
||||
Simply invoke the configure script from the target location:
|
||||
<pre>~/icu$ svn export http://source.icu-project.org/repos/icu/icu/trunk
|
||||
~/icu$ mkdir trunk-dev
|
||||
~/icu$ cd trunk-dev
|
||||
~/icu/trunk-dev$ ../trunk/source/runConfigureICU Linux
|
||||
~/icu/trunk-dev$ make check</pre></li>
|
||||
</ul>
|
||||
<h4>ICU as a System-Level Library</h4>
|
||||
<p>If ICU is installed as a system-level library, there are further
|
||||
opportunities and restrictions to consider.
|
||||
For details, see the <em>Using ICU as an Operating System Level Library</em>
|
||||
section of the <a href="http://userguide.icu-project.org/design">User Guide ICU Architectural Design</a> chapter.</p>
|
||||
<ul>
|
||||
<li><b>Data path:</b> For a system-level library, it is best to load
|
||||
ICU data from the .dat package file because the file system path
|
||||
to the .dat package file can be hardcoded.
|
||||
Set <code>-DICU_DATA_DIR=/path/to/icu/data</code> when building
|
||||
the ICU code. (Used by source/common/putil.c.)<br>
|
||||
Consider also setting <code>-DICU_NO_USER_DATA_OVERRIDE</code>
|
||||
if you do not want the "ICU_DATA" environment variable to be used.
|
||||
(An application can still override the data path via
|
||||
<code>u_setDataDirectory()</code> or
|
||||
<code>udata_setCommonData()</code>.</li>
|
||||
<li><b>Hide draft API:</b> API marked with <code>@draft</code>
|
||||
is new and not yet stable. Applications must not rely on unstable
|
||||
APIs from a system-level library.
|
||||
Define <code>U_HIDE_DRAFT_API</code>, <code>U_HIDE_INTERNAL_API</code>
|
||||
and <code>U_HIDE_SYSTEM_API</code>
|
||||
by modifying unicode/utypes.h before installing it.</li>
|
||||
<li><b>Only C APIs:</b> Applications must not rely on C++ APIs from a
|
||||
system-level library because binary C++ compatibility
|
||||
across library and compiler versions is very hard to achieve.
|
||||
Most ICU C++ APIs are in header files that contain a comment with
|
||||
<code>\brief C++ API</code>.
|
||||
Consider not installing these header files.</li>
|
||||
<li><b>Disable renaming:</b> By default, ICU library entry point names
|
||||
have an ICU version suffix. Turn this off for a system-level installation,
|
||||
to enable upgrading ICU without breaking applications. For example:<br>
|
||||
<code>runConfigureICU Linux --disable-renaming</code><br>
|
||||
The public header files from this configuration must be installed
|
||||
for applications to include and get the correct entry point names.</li>
|
||||
</ul>
|
||||
|
||||
<h3><a name="HowToBuildWindows" href="#HowToBuildWindows" id=
|
||||
"HowToBuildWindows">How To Build And Install On Windows</a></h3>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user