1 C++ version of the libphonenumber project 2 ========================================= 3 4This library is a port of the Java version. 5 6This project uses some third-party code: 7 - src/phonenumbers/utf/ sources come from lib9 which is also used in Go. 8 9 10Installing the library on GNU/Linux 11----------------------------------- 12In recent Debian-based distributions you may be able to simply install the 13libphonenumber library directly. 14 15Installing 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 19Installing the source package: 20 - Use this if you wish to develop or debug the library: 21 $ sudo apt-get source libphonenumber 22 23The latest packages can be found on the Debian packages site: 24 https://packages.debian.org/search?searchon=names&keywords=libphonenumber 25 26 27Manually installing the library on GNU/Linux 28-------------------------------------------- 29You should only need these instructions if the above instructions do not work. 30 31The example command lines below assume that you have a Debian-based GNU/Linux 32distribution. Other distributions and packaging systems will differ. 33 34Quickstart: 35 - In recent Debian-based distributions, it should be sufficient 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 protobuf-compiler 40 41If any of these packages fails to install correctly, follow the instructions 42in the appropriate section below. 43 44Requirements: 45 - CMake build system 46 http://www.cmake.org 47 48 Installation: 49 $ sudo apt-get install cmake 50 51 Additionally it is recommended you install the ccmake configuration tool: 52 $ sudo apt-get install cmake-curses-gui 53 54 - Protocol Buffers 55 http://github.com/google/protobuf/ 56 Version 3.6.1 or more recent is required (this is available by default for 57 recent Debian-based GNU/Linux distributions). 58 59 You can check which version is available: 60 $ apt-cache show libprotobuf-dev 61 Package: libprotobuf-dev 62 Source: protobuf 63 Version: 3.6.1-9ubuntu1 <-- This must be >= 3.6.1 64 ... 65 66 Installation: 67 $ sudo apt-get install libprotobuf-dev 68 69 Note: if your GNU/Linux distribution doesn't provide the needed package, 70 please download and install it manually: 71 More details can be found at its official page: 72 https://github.com/protocolbuffers/protobuf 73 74 - Google Test 75 http://github.com/google/googletest 76 77 Installation: 78 $ sudo apt-get install libgtest-dev 79 80 - RE2 81 http://github.com/google/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 132Building and testing the library 133-------------------------------- 134 $ cd libphonenumber/cpp 135 $ mkdir build 136 $ cd build 137 $ cmake .. 138 $ make 139 $ ./libphonenumber_test 140 141 142Manually installing the library on Mac 143-------------------------------------- 144 145You can easily install dependencies on Mac using a package manager. In these 146instructions we use Homebrew (http://brew.sh). 147 148Install Homebrew package manager and use it to install dependencies: 149 $ /usr/bin/ruby -e "$(curl -fsSL \ 150 https://raw.githubusercontent.com/Homebrew/install/master/install)" 151 $ brew install boost cmake icu4c pkg-config protobuf wget 152 153See https://github.com/Homebrew/homebrew/issues/14099 - homebrew does not have 154gtest. We don't need to install gtest, we only copy sources. For example: 155 $ mkdir ~/googletest_clone 156 $ cd ~/googletest_clone 157 $ git clone https://github.com/google/googletest.git 158 159Get the libphonenumber source. For example: 160 $ mkdir ~/libphonenumber_clone 161 $ cd ~/libphonenumber_clone 162 $ git clone https://github.com/google/libphonenumber.git 163 164Build and test the library: 165 $ cd libphonenumber/cpp 166 $ mkdir build 167 $ cd build 168 Replace XXX in the commands below with the appropriate version number: 169 $ cmake \ 170 -DGTEST_SOURCE_DIR=~/googletest_clone/googletest/googletest/ \ 171 -DGTEST_INCLUDE_DIR=~/googletest_clone/googletest/googletest/include/ \ 172 -DICU_UC_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \ 173 -DICU_UC_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicuuc.dylib \ 174 -DICU_I18N_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \ 175 -DICU_I18N_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicui18n.dylib \ 176 -DUSE_STD_MAP=ON \ 177 .. 178 $ make 179 $ ./libphonenumber_test 180 181Optional: Deleting & uninstalling everything again: 182 $ cd 183 $ rm -rf ~/libphonenumber_clone ~/googletest_clone 184 185 openssl is a dependency of wget and installed with it by Homebrew. If you had 186 openssl before installing wget don't uninstall here. 187 $ brew uninstall boost cmake icu4c openssl pkg-config protobuf wget 188 189 $ /usr/bin/ruby -e "$(curl -fsSL \ 190 https://raw.githubusercontent.com/Homebrew/install/master/uninstall)" 191 192 Homebrew will have changed permissions at installation. See output of previous 193 command for how to change them back, for example: 194 $ sudo chmod 0755 /usr/local 195 $ sudo chgrp wheel /usr/local 196 197 198Troubleshooting CMake via ccmake 199-------------------------------- 200 Follow these instructions if the build steps above don't work for you. 201 202 - Incorrect protocol buffer library issues 203 If the build process complains that the version of protoc being used is too 204 old or that it cannot find the correct libprotobuf library, you may need to 205 change the library path of the project. 206 207 This issue should typically only occur in cases where you have two (or more) 208 versions of the protocol buffer libraries installed on your system. This 209 step assumes that you have already manually downloaded and installed the 210 protocol buffer libraries into /usr/local (as described above). 211 212 To make cmake use the manually installed version of the protocol buffer 213 libraries, install cmake-curses-gui and use ccmake as follows. 214 215 From within libphonenumber/cpp/build: 216 $ ccmake . 217 218 You should set the following values: 219 PROTOBUF_INCLUDE_DIR /usr/local/include 220 PROTOBUF_LIB /usr/local/lib/libprotobuf.dylib 221 PROTOC_BIN /usr/local/bin/protoc 222 223 Now press 'c' then 'g' to configure the new parameters and exit ccmake. 224 Finally regenerate the make files and rebuild via: 225 $ cmake .. 226 $ make 227 228 - Protoc binary not executing properly 229 If you still have issues with the protoc binary tool in /usr/local/bin not 230 running correctly (cannot find libprotobuf.so.x) then you may need to 231 configure the LD_LIBRARY_PATH. To do this, as a superuser, add the following 232 file: 233 /etc/ld.so.conf.d/libprotobuf.conf 234 235 with the contents: 236 # Use the manually installed version of the protocol buffer libraries. 237 /usr/local/lib 238 239 And then run: 240 $ sudo chmod 644 /etc/ld.so.conf.d/libprotobuf.conf 241 $ sudo ldconfig 242 243 - Incorrect ICU library issues 244 Similar to the protocol buffer library issue above, it is possible that your 245 build may fail if you have two conflicting versions of the ICU libraries 246 installed on your system. This step assumes that you have already manually 247 downloaded and installed a recent version of the ICU libraries into 248 /usr/local. 249 250 Install and run the ccmake tool (as described above) and set the following 251 values: 252 ICU_I18N_INCLUDE_DIR /usr/local/include 253 ICU_I18N_LIB /usr/local/lib/libicui18n.so 254 ICU_UC_INCLUDE_DIR /usr/local/include 255 ICU_UC_LIB /usr/local/lib/libicuuc.so 256 257 Now press 'c' then 'g' to configure the new parameters and exit ccmake. 258 Finally regenerate the make files and rebuild via: 259 $ cmake .. 260 $ make 261 262 263Building the library on Windows (Visual Studio) 264----------------------------------------------- 265We recommend that libphonenumber on Windows be built with Visual Studio 2015 266Update 2 (https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update2-vs) 267or later. 268 269This enables support of plain UTF-8 source files, for which you also need to specify 270the /utf-8 option in build files; see "New Options in VS2015 Update 2" at 271https://blogs.msdn.microsoft.com/vcblog/2016/02/22/new-options-for-managing-character-sets-in-the-microsoft-cc-compiler/, 272or a Chrome patch for an example: 273https://codereview.chromium.org/2488853002/diff/80001/build/config/compiler/BUILD.gn 274 275Without this version and the option, your compilation will have warnings when 276setting the codepage for non-Unicode applications on Windows to one of the CJK 277code pages, since libphonenumber has UTF-8 strings in source files. While these 278are only comments (as opposed to string literals) the warnings can be 279suppressed, but we reserve the right to introduce UTF-8 string literals. 280 281The library was tested with Visual Studio 2010. 282 283You will need to manually fetch and install the following dependencies: 284 - CMake (tested with v2.8.6): 285 http://cmake.org/cmake/resources/software.html 286 * Download and install the Win32 installer. 287 288 - Boost (tested with v1.44) from BoostPro: 289 http://www.boostpro.com/download/ 290 * Select all the variants and Boost DateTime and Boost Thread during the 291 installation process. 292 See Linux instructions for information about thread-safety. 293 294 - GTest (tested with v1.6.0): 295 http://code.google.com/p/googletest/downloads/list 296 * Open msvc/gtest-md.sln with Visual Studio and build the whole solution. 297 298 - ICU (MSVC binaries, tested with v4.8.1): 299 http://site.icu-project.org/download/48#ICU4C-Download 300 * Simply extract the archive. 301 302 - Protocol Buffers: 303 http://code.google.com/p/protobuf/downloads/list 304 * Open vsprojects/protobuf.sln with Visual Studio and build the whole 305 solution. 306 307Then run cmake-gui and specify the path to the libphonenumber's cpp directory 308and its build directory which must be created (e.g. cpp/build). 309 310When clicking on "Configure", specify the appropriate Visual Studio version 311(tested with 2010). 312 313Then CMake will need your help to locate the dependencies. You will have to set 314the following variables (this example assumes that you extracted the 315dependencies to C:/). 316 317GTEST_INCLUDE_DIR C:/gtest-1.6.0/include 318GTEST_LIB C:/gtest-1.6.0/msvc/gtest-md/Release/gtest.lib 319 320ICU_I18N_INCLUDE_DIR C:/icu/include 321ICU_I18N_LIB C:/icu/lib/icuin.lib 322 323ICU_UC_INCLUDE_DIR C:/icu/include 324ICU_UC_LIB C:/icu/lib/icuuc.lib 325 326PROTOBUF_INCLUDE_DIR C:/protobuf-3.6.1/src 327PROTOBUF_LIB C:/protobuf-3.6.1/vsprojects/Release/libprotobuf.lib 328PROTOC_BIN C:/protobuf-3.6.1/vsprojects/Release/protoc.exe 329 330Then you can click on "Configure" again. CMake should have located all the 331dependencies. 332Then click on "Generate" to generate the appropriate Visual Studio project. 333Then open cpp/build/libphonenumber.sln with Visual Studio and build the INSTALL 334target. 335 336As a result the library's headers and binaries should have been installed to 337C:/Program Files/libphonenumber/. 338Note that this path can be set by overriding the CMAKE_INSTALL_PREFIX variable 339with cmake-gui. 340 341 342Supported build parameters 343-------------------------- 344 Build parameters can be specified invoking CMake with '-DKEY=VALUE' or using a 345 CMake user interface (ccmake or cmake-gui). 346 347 USE_ALTERNATE_FORMATS = ON | OFF [ON] -- Use alternate formats for the phone 348 number matcher. 349 USE_BOOST = ON | OFF [ON] -- Use Boost. This is only needed in 350 multi-threaded environments that 351 are not Linux and Mac. 352 Libphonenumber relies on Boost for 353 non-POSIX (e.g. Windows) 354 multi-threading. 355 USE_ICU_REGEXP = ON | OFF [ON] -- Use ICU regexp engine. 356 USE_LITE_METADATA = ON | OFF [OFF] -- Generates smaller metadata that 357 doesn't include example numbers. 358 USE_RE2 = ON | OFF [OFF] -- Use RE2. 359 USE_STD_MAP = ON | OFF [OFF] -- Force the use of std::map. 360