cpp/README

   1                   C++ version of the libphonenumber project
   2                   =========================================
   3
   4 This library is a port of the Java version.
   5
   6 This project uses some third-party code:
   7   - src/phonenumbers/utf/ sources come from lib9 which is also used in Go.
   8
   9
  10 Installing the library on GNU/Linux
  11 -----------------------------------
  12 In recent Debian-based distributions you may be able to simply install the
  13 libphonenumber library directly.
  14
  15 Installing the binary packages:
  16   - Use this if you just need to use or link against the library:
  17     $ sudo apt-get install libphonenumber6 libphonenumber6-dev
  18
  19 Installing the source package:
  20   - Use this if you wish to develop or debug the library:
  21     $ sudo apt-get source libphonenumber
  22
  23 The latest packages can be found on the Debian packages site:
  24   https://packages.debian.org/search?searchon=names&keywords=libphonenumber
  25
  26
  27 Manually installing the library on GNU/Linux
  28 --------------------------------------------
  29 You should only need these instructions if the above instructions do not work.
  30
  31 The example command lines below assume that you have a Debian-based GNU/Linux
  32 distribution. Other distributions and packaging systems will differ.
  33
  34 Quickstart:
  35   - In recent Debian-based distributions, it should be sufficent to run:
  36     $ sudo apt-get install \
  37       cmake cmake-curses-gui libprotobuf-dev libgtest-dev libre2-dev \
  38       libicu-dev libboost-dev libboost-thread-dev libboost-system-dev
  39
  40 If any of these packages fails to install correctly, follow the instructions
  41 in the appropriate section below.
  42
  43 Requirements:
  44   - CMake build system
  45     http://www.cmake.org
  46
  47     Installation:
  48     $ sudo apt-get install cmake
  49
  50     Additionally it is recommended you install the ccmake configuration tool:
  51     $ sudo apt-get install cmake-curses-gui
  52
  53   - Protocol Buffers
  54     http://code.google.com/p/protobuf/
  55     Version 2.4 or more recent is required (this is available by default for
  56     recent Debian-based GNU/Linux distributions).
  57
  58     You can check which version is available:
  59     $ apt-cache show libprotobuf-dev
  60     Package: libprotobuf-dev
  61     Source: protobuf
  62     Version: 2.5.0-9ubuntu1   <-- This must be >= 2.4.0
  63     ...
  64
  65     Installation:
  66     $ sudo apt-get install libprotobuf-dev
  67
  68     Note: if your GNU/Linux distribution doesn't provide the needed package,
  69           please download and install it manually:
  70     $ tar xjf protobuf-2.4.tar.bz2
  71     $ cd protobuf-2.4
  72     $ ./configure && make && sudo make install
  73
  74   - Google Test
  75     http://code.google.com/p/googletest/
  76
  77     Installation:
  78     $ sudo apt-get install libgtest-dev
  79
  80   - RE2
  81     http://code.google.com/p/re2/
  82
  83     Installation:
  84     $ sudo apt-get install libre2-dev
  85
  86     Note that some distributions (notably Ubuntu 10.4) may not include this,
  87     so you might need to download and install it manually.
  88
  89     Find and download the Debian packages for your system. For example:
  90     http://packages.ubuntu.com/utopic/libre2-1
  91     http://packages.ubuntu.com/utopic/libre2-dev
  92
  93     You need to download both the libre2-dev and libre2-1 packages.
  94     Once downloaded, install them with:
  95     $ sudo dpkg -i libre2*.deb
  96
  97     If you want to install it from source, it's available via Mercurial at:
  98     https://re2.googlecode.com/hg
  99     however precise instructions on building and installing are outside the
 100     scope of this document.
 101
 102   - ICU
 103     Installation:
 104     $ sudo apt-get install libicu-dev
 105
 106     Otherwise you need to download the source tarball for the latest version
 107     from:
 108       http://site.icu-project.org/download
 109     And then extract it via:
 110     $ tar xzf icu4c-*-src.tgz
 111
 112     Alternatively you can export the SVN repository to the current directory
 113     via:
 114     $ svn export http://source.icu-project.org/repos/icu/icu/tags/release-XX-y-z/
 115
 116     Having acquired the latest sources, make and install it via:
 117     $ cd icu/source
 118     $ ./configure && make && sudo make install
 119
 120   - Boost
 121     Version 1.40 or more recent is required if you need libphonenumber to be
 122     thread-safe. If you access libphonenumber from a single thread, you can
 123     avoid the Boost dependency by disabling the USE_BOOST CMake option (see
 124     Troubleshooting section below for information about ccmake).
 125
 126     You can install it very easily on a Debian-based GNU/Linux distribution:
 127     $ sudo apt-get install libboost-dev libboost-thread-dev libboost-system-dev
 128
 129     Note: Boost Thread is the only library needed at link time.
 130
 131
 132 Building the library
 133 --------------------
 134   $ cd libphonenumber/cpp
 135   $ mkdir build
 136   $ cd build
 137   $ cmake ..
 138   $ make
 139
 140
 141 Troubleshooting CMake via ccmake
 142 --------------------------------
 143   Follow these instructions if the build steps above don't work for you.
 144
 145   - Incorrect protocol buffer library issues
 146     If the build process complains that the version of protoc being used is too
 147     old or that it cannot find the correct libprotobuf library, you may need to
 148     change the library path of the project.
 149
 150     This issue should typically only occur in cases where you have two (or more)
 151     versions of the protocol buffer libraries installed on your system. This
 152     step assumes that you have already manually downloaded and installed the
 153     protocol buffer libraries into /usr/local (as described above).
 154
 155     To make cmake use the manually installed version of the protocol buffer
 156     libraries, install cmake-curses-gui and use ccmake as follows.
 157
 158     From within libphonenumber/cpp/build:
 159     $ ccmake .
 160
 161     You should set the following values:
 162       PROTOBUF_INCLUDE_DIR         /usr/local/include
 163       PROTOBUF_LIB                 /usr/local/lib/libprotobuf.so
 164       PROTOC_BIN                   /usr/local/bin/protoc
 165
 166     Now press 'c' then 'g' to configure the new parameters and exit ccmake.
 167     Finally regenerate the make files and rebuild via:
 168     $ cmake ..
 169     $ make
 170
 171   - Protoc binary not executing properly
 172     If you still have issues with the protoc binary tool in /usr/local/bin not
 173     running correctly (cannot find libprotobuf.so.x) then you may need to
 174     configure the LD_LIBRARY_PATH. To do this, as a superuser, add the following
 175     file:
 176       /etc/ld.so.conf.d/libprotobuf.conf
 177
 178     with the contents:
 179       # Use the manually installed version of the protocol buffer libraries.
 180       /usr/local/lib
 181
 182     And then run:
 183       $ sudo chmod 644 /etc/ld.so.conf.d/libprotobuf.conf
 184       $ sudo ldconfig
 185
 186   - Incorrect ICU library issues
 187     Similar to the protocol buffer library issue above, it is possible that your
 188     build may fail if you have two conflicting versions of the ICU libraries
 189     installed on your system. This step assumes that you have already manually
 190     downloaded and installed a recent version of the ICU libraries into
 191     /usr/local.
 192
 193     Install and run the ccmake tool (as described above) and set the following
 194     values:
 195       ICU_I18N_INCLUDE_DIR         /usr/local/include
 196       ICU_I18N_LIB                 /usr/local/lib/libicui18n.so
 197       ICU_UC_INCLUDE_DIR           /usr/local/include
 198       ICU_UC_LIB                   /usr/local/lib/libicuuc.so
 199
 200     Now press 'c' then 'g' to configure the new parameters and exit ccmake.
 201     Finally regenerate the make files and rebuild via:
 202     $ cmake ..
 203     $ make
 204
 205 Building the library on Windows (Visual Studio)
 206 -----------------------------------------------
 207 The library was tested with Visual Studio 2010.
 208
 209 You will need to manually fetch and install the following dependencies:
 210   - CMake (tested with v2.8.6):
 211     http://cmake.org/cmake/resources/software.html
 212     * Download and install the Win32 installer.
 213
 214   - Boost (tested with v1.44) from BoostPro:
 215     http://www.boostpro.com/download/
 216     * Select all the variants and Boost DateTime and Boost Thread during the
 217       installation process.
 218     See Linux instructions for information about thread-safety.
 219
 220   - GTest (tested with v1.6.0):
 221     http://code.google.com/p/googletest/downloads/list
 222     * Open msvc/gtest-md.sln with Visual Studio and build the whole solution.
 223
 224   - ICU (MSVC binaries, tested with v4.8.1):
 225     http://site.icu-project.org/download/48#ICU4C-Download
 226     * Simply extract the archive.
 227
 228   - Protocol Buffers:
 229     http://code.google.com/p/protobuf/downloads/list
 230     * Open vsprojects/protobuf.sln with Visual Studio and build the whole
 231       solution.
 232
 233 Then run cmake-gui and specify the path to the libphonenumber's cpp directory
 234 and its build directory which must be created (e.g. cpp/build).
 235
 236 When clicking on "Configure", specify the appropriate Visual Studio version
 237 (tested with 2010).
 238
 239 Then CMake will need your help to locate the dependencies. You will have to set
 240 the following variables (this example assumes that you extracted the
 241 dependencies to C:/).
 242
 243 GTEST_INCLUDE_DIR         C:/gtest-1.6.0/include
 244 GTEST_LIB                 C:/gtest-1.6.0/msvc/gtest-md/Release/gtest.lib
 245
 246 ICU_I18N_INCLUDE_DIR      C:/icu/include
 247 ICU_I18N_LIB              C:/icu/lib/icuin.lib
 248
 249 ICU_UC_INCLUDE_DIR        C:/icu/include
 250 ICU_UC_LIB                C:/icu/lib/icuuc.lib
 251
 252 PROTOBUF_INCLUDE_DIR      C:/protobuf-2.4.1/src
 253 PROTOBUF_LIB              C:/protobuf-2.4.1/vsprojects/Release/libprotobuf.lib
 254 PROTOC_BIN                C:/protobuf-2.4.1/vsprojects/Release/protoc.exe
 255
 256 Then you can click on "Configure" again. CMake should have located all the
 257 dependencies.
 258 Then click on "Generate" to generate the appropriate Visual Studio project.
 259 Then open cpp/build/libphonenumber.sln with Visual Studio and build the INSTALL
 260 target.
 261
 262 As a result the library's headers and binaries should have been installed to
 263 C:/Program Files/libphonenumber/.
 264 Note that this path can be set by overriding the CMAKE_INSTALL_PREFIX variable
 265 with cmake-gui.
 266
 267 Supported build parameters
 268 --------------------------
 269   Build parameters can be specified invoking CMake with '-DKEY=VALUE' or using a
 270   CMake user interface (ccmake or cmake-gui).
 271
 272   USE_ALTERNATE_FORMATS = ON | OFF [ON]  -- Use alternate formats for the phone
 273                                             number matcher.
 274   USE_BOOST             = ON | OFF [ON]  -- Use Boost. This is only needed in
 275                                             multi-threaded environments that
 276                                             are not Linux and Mac.
 277                                             Libphonenumber relies on Boost for
 278                                             non-POSIX (e.g. Windows)
 279                                             multi-threading.
 280   USE_ICU_REGEXP        = ON | OFF [ON]  -- Use ICU regexp engine.
 281   USE_LITE_METADATA     = ON | OFF [OFF] -- Generates smaller metadata that
 282                                             doesn't include example numbers.
 283   USE_RE2               = ON | OFF [OFF] -- Use RE2.
 284   USE_STD_MAP           = ON | OFF [OFF] -- Force the use of std::map.