cpp/README

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