| C++ version of the libphonenumber project |
| ========================================= |
| |
| This library is a port of the Java version. |
| |
| This project uses some third-party code: |
| - src/phonenumbers/utf/ sources come from lib9 which is also used in Go. |
| |
| |
| Installing the library on GNU/Linux |
| ----------------------------------- |
| In recent Debian-based distributions you may be able to simply install the |
| libphonenumber library directly. |
| |
| Installing the binary packages: |
| - Use this if you just need to use or link against the library: |
| $ sudo apt-get install libphonenumber8 libphonenumber-dev |
| |
| Installing the source package: |
| - Use this if you wish to develop or debug the library: |
| $ sudo apt-get source libphonenumber |
| |
| The latest packages can be found on the Debian packages site: |
| https://packages.debian.org/search?searchon=names&keywords=libphonenumber |
| |
| |
| Manually installing the library on GNU/Linux |
| -------------------------------------------- |
| You should only need these instructions if the above instructions do not work. |
| |
| The example command lines below assume that you have a Debian-based GNU/Linux |
| distribution. Other distributions and packaging systems will differ. |
| |
| Quickstart: |
| - In recent Debian-based distributions, it should be sufficient to run: |
| $ sudo apt-get install \ |
| cmake cmake-curses-gui libprotobuf-dev libgtest-dev libre2-dev \ |
| libicu-dev libboost-dev libboost-thread-dev libboost-system-dev \ |
| protobuf-compiler |
| |
| If any of these packages fails to install correctly, follow the instructions |
| in the appropriate section below. |
| |
| Requirements: |
| - CMake build system |
| http://www.cmake.org |
| |
| Installation: |
| $ sudo apt-get install cmake |
| |
| Additionally it is recommended you install the ccmake configuration tool: |
| $ sudo apt-get install cmake-curses-gui |
| |
| - Protocol Buffers |
| http://github.com/google/protobuf/ |
| Version 3.6.1 or more recent is required (this is available by default for |
| recent Debian-based GNU/Linux distributions). |
| |
| You can check which version is available: |
| $ apt-cache show libprotobuf-dev |
| Package: libprotobuf-dev |
| Source: protobuf |
| Version: 3.6.1-9ubuntu1 <-- This must be >= 3.6.1 |
| ... |
| |
| Installation: |
| $ sudo apt-get install libprotobuf-dev |
| |
| Note: if your GNU/Linux distribution doesn't provide the needed package, |
| please download and install it manually: |
| More details can be found at its official page: |
| https://github.com/protocolbuffers/protobuf |
| |
| - Google Test |
| http://github.com/google/googletest |
| |
| Installation: |
| $ sudo apt-get install libgtest-dev |
| |
| - RE2 |
| http://github.com/google/re2 |
| |
| Installation: |
| $ sudo apt-get install libre2-dev |
| |
| Note that some distributions (notably Ubuntu 10.4) may not include this, |
| so you might need to download and install it manually. |
| |
| Find and download the Debian packages for your system. For example: |
| http://packages.ubuntu.com/utopic/libre2-1 |
| http://packages.ubuntu.com/utopic/libre2-dev |
| |
| You need to download both the libre2-dev and libre2-1 packages. |
| Once downloaded, install them with: |
| $ sudo dpkg -i libre2*.deb |
| |
| If you want to install it from source, it's available via Mercurial at: |
| https://re2.googlecode.com/hg |
| however precise instructions on building and installing are outside the |
| scope of this document. |
| |
| - ICU |
| Installation: |
| $ sudo apt-get install libicu-dev |
| |
| Otherwise you need to download the source tarball for the latest version |
| from: |
| http://site.icu-project.org/download |
| And then extract it via: |
| $ tar xzf icu4c-*-src.tgz |
| |
| Alternatively you can export the SVN repository to the current directory |
| via: |
| $ svn export http://source.icu-project.org/repos/icu/icu/tags/release-XX-y-z/ |
| |
| Having acquired the latest sources, make and install it via: |
| $ cd icu/source |
| $ ./configure && make && sudo make install |
| |
| - A thread synchronization solution or more recent is required if you need |
| libphonenumber to be thread-safe. Supported solution are: |
| - Boost Version 1.40 or more recent |
| - Posix Thread. Linux or Apple (ios/mac) detection is automatic. On other |
| Posix environnement, uses -DUSE_POSIX_THREAD = ON |
| - C++ 2011 (and later) std::mutex. Uses -DUSE_STDMUTEX = ON to enable |
| automatic C++ 2011 detection (if you prefer Posix or Win32 solution). |
| - Windows Win32 synchronization API. |
| |
| If you access libphonenumber from a single thread, you don't need one of |
| these solution. |
| |
| You can install it very easily on a Debian-based GNU/Linux distribution: |
| $ sudo apt-get install libboost-dev libboost-thread-dev libboost-system-dev |
| |
| Note: Boost Thread is the only library needed at link time. |
| |
| |
| - abseil-cpp |
| As this dependency package might not be very common, we are downloading, |
| building and linking this library as part of the regular build process i.e |
| part of CMake/Make instructions. If you wish to install this C++ developer |
| library at your system level and avoid building every time, you can try |
| below instruction set. |
| |
| Installation: |
| - Official [installation guide](https://abseil.io/docs/cpp/tools/cmake-installs). |
| Something that we followed in Linux system. |
| $ git clone https://github.com/abseil/abseil-cpp.git --branch 273292d --single-branch |
| $ cd abseil-cpp |
| $ cmake . -DCMAKE_INSTALL_PREFIX="$HOME/lpn-deps" -DCMAKE_POSITION_INDEPENDENT_CODE=ON |
| $ cmake --build . --target install |
| - When building libphonenumber library, if abseil-cpp is still getting downloaded and |
| built, use flags like ```CMAKE_PREFIX_PATH="$HOME/lpn-deps"``` |
| - Notes: |
| - We are cloning only a particular version of the abseil-cpp so that we |
| are not commiting to catch up with new build requirements of that |
| library. Eg: After the above tag version C++14 is made as minimum |
| version to build abseil-cpp library. |
| - libphonenumber is presently using C++11 by default, you can always |
| change it by passing ```CMAKE_CXX_STANDARD``` flag. |
| |
| Building and testing the library |
| -------------------------------- |
| $ cd libphonenumber/cpp |
| $ mkdir build |
| $ cd build |
| $ cmake .. |
| $ make |
| $ ./libphonenumber_test |
| |
| |
| Manually installing the library on Mac |
| -------------------------------------- |
| |
| You can easily install dependencies on Mac using a package manager. In these |
| instructions we use Homebrew (http://brew.sh). |
| |
| Install Homebrew package manager and use it to install dependencies: |
| $ /usr/bin/ruby -e "$(curl -fsSL \ |
| https://raw.githubusercontent.com/Homebrew/install/master/install)" |
| $ brew install boost cmake icu4c pkg-config protobuf wget |
| |
| See https://github.com/Homebrew/homebrew/issues/14099 - homebrew does not have |
| gtest. We don't need to install gtest, we only copy sources. For example: |
| $ mkdir ~/googletest_clone |
| $ cd ~/googletest_clone |
| $ git clone https://github.com/google/googletest.git |
| |
| Get the libphonenumber source. For example: |
| $ mkdir ~/libphonenumber_clone |
| $ cd ~/libphonenumber_clone |
| $ git clone https://github.com/google/libphonenumber.git |
| |
| Build and test the library: |
| $ cd libphonenumber/cpp |
| $ mkdir build |
| $ cd build |
| Replace XXX in the commands below with the appropriate version number: |
| $ cmake \ |
| -DGTEST_SOURCE_DIR=~/googletest_clone/googletest/googletest/ \ |
| -DGTEST_INCLUDE_DIR=~/googletest_clone/googletest/googletest/include/ \ |
| -DICU_UC_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \ |
| -DICU_UC_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicuuc.dylib \ |
| -DICU_I18N_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \ |
| -DICU_I18N_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicui18n.dylib \ |
| -DUSE_STD_MAP=ON \ |
| .. |
| $ make |
| $ ./libphonenumber_test |
| |
| Optional: Deleting & uninstalling everything again: |
| $ cd |
| $ rm -rf ~/libphonenumber_clone ~/googletest_clone |
| |
| openssl is a dependency of wget and installed with it by Homebrew. If you had |
| openssl before installing wget don't uninstall here. |
| $ brew uninstall boost cmake icu4c openssl pkg-config protobuf wget |
| |
| $ /usr/bin/ruby -e "$(curl -fsSL \ |
| https://raw.githubusercontent.com/Homebrew/install/master/uninstall)" |
| |
| Homebrew will have changed permissions at installation. See output of previous |
| command for how to change them back, for example: |
| $ sudo chmod 0755 /usr/local |
| $ sudo chgrp wheel /usr/local |
| |
| |
| Troubleshooting CMake via ccmake |
| -------------------------------- |
| Follow these instructions if the build steps above don't work for you. |
| |
| - Incorrect protocol buffer library issues |
| If the build process complains that the version of protoc being used is too |
| old or that it cannot find the correct libprotobuf library, you may need to |
| change the library path of the project. |
| |
| This issue should typically only occur in cases where you have two (or more) |
| versions of the protocol buffer libraries installed on your system. This |
| step assumes that you have already manually downloaded and installed the |
| protocol buffer libraries into /usr/local (as described above). |
| |
| To make cmake use the manually installed version of the protocol buffer |
| libraries, install cmake-curses-gui and use ccmake as follows. |
| |
| From within libphonenumber/cpp/build: |
| $ ccmake . |
| |
| You should set the following values: |
| PROTOBUF_INCLUDE_DIR /usr/local/include |
| PROTOBUF_LIB /usr/local/lib/libprotobuf.dylib |
| PROTOC_BIN /usr/local/bin/protoc |
| |
| Now press 'c' then 'g' to configure the new parameters and exit ccmake. |
| Finally regenerate the make files and rebuild via: |
| $ cmake .. |
| $ make |
| |
| - Protoc binary not executing properly |
| If you still have issues with the protoc binary tool in /usr/local/bin not |
| running correctly (cannot find libprotobuf.so.x) then you may need to |
| configure the LD_LIBRARY_PATH. To do this, as a superuser, add the following |
| file: |
| /etc/ld.so.conf.d/libprotobuf.conf |
| |
| with the contents: |
| # Use the manually installed version of the protocol buffer libraries. |
| /usr/local/lib |
| |
| And then run: |
| $ sudo chmod 644 /etc/ld.so.conf.d/libprotobuf.conf |
| $ sudo ldconfig |
| |
| - Incorrect ICU library issues |
| Similar to the protocol buffer library issue above, it is possible that your |
| build may fail if you have two conflicting versions of the ICU libraries |
| installed on your system. This step assumes that you have already manually |
| downloaded and installed a recent version of the ICU libraries into |
| /usr/local. |
| |
| Install and run the ccmake tool (as described above) and set the following |
| values: |
| ICU_I18N_INCLUDE_DIR /usr/local/include |
| ICU_I18N_LIB /usr/local/lib/libicui18n.so |
| ICU_UC_INCLUDE_DIR /usr/local/include |
| ICU_UC_LIB /usr/local/lib/libicuuc.so |
| |
| Now press 'c' then 'g' to configure the new parameters and exit ccmake. |
| Finally regenerate the make files and rebuild via: |
| $ cmake .. |
| $ make |
| |
| |
| Building the library on Windows (Visual Studio) |
| ----------------------------------------------- |
| We recommend that libphonenumber on Windows be built with Visual Studio 2015 |
| Update 2 (https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update2-vs) |
| or later. |
| |
| This enables support of plain UTF-8 source files, for which you also need to specify |
| the /utf-8 option in build files; see "New Options in VS2015 Update 2" at |
| https://blogs.msdn.microsoft.com/vcblog/2016/02/22/new-options-for-managing-character-sets-in-the-microsoft-cc-compiler/, |
| or a Chrome patch for an example: |
| https://codereview.chromium.org/2488853002/diff/80001/build/config/compiler/BUILD.gn |
| |
| Without this version and the option, your compilation will have warnings when |
| setting the codepage for non-Unicode applications on Windows to one of the CJK |
| code pages, since libphonenumber has UTF-8 strings in source files. While these |
| are only comments (as opposed to string literals) the warnings can be |
| suppressed, but we reserve the right to introduce UTF-8 string literals. |
| |
| The library was tested with Visual Studio 2010. |
| |
| You will need to manually fetch and install the following dependencies: |
| - CMake (tested with v2.8.6): |
| http://cmake.org/cmake/resources/software.html |
| * Download and install the Win32 installer. |
| |
| - Boost (tested with v1.44) from BoostPro: |
| http://www.boostpro.com/download/ |
| * Select all the variants and Boost DateTime and Boost Thread during the |
| installation process. |
| See Linux instructions for information about thread-safety. |
| |
| - GTest (tested with v1.6.0): |
| http://code.google.com/p/googletest/downloads/list |
| * Open msvc/gtest-md.sln with Visual Studio and build the whole solution. |
| |
| - ICU (MSVC binaries, tested with v4.8.1): |
| http://site.icu-project.org/download/48#ICU4C-Download |
| * Simply extract the archive. |
| |
| - Protocol Buffers: |
| http://code.google.com/p/protobuf/downloads/list |
| * Open vsprojects/protobuf.sln with Visual Studio and build the whole |
| solution. |
| |
| Then run cmake-gui and specify the path to the libphonenumber's cpp directory |
| and its build directory which must be created (e.g. cpp/build). |
| |
| When clicking on "Configure", specify the appropriate Visual Studio version |
| (tested with 2010). |
| |
| Then CMake will need your help to locate the dependencies. You will have to set |
| the following variables (this example assumes that you extracted the |
| dependencies to C:/). |
| |
| GTEST_INCLUDE_DIR C:/gtest-1.6.0/include |
| GTEST_LIB C:/gtest-1.6.0/msvc/gtest-md/Release/gtest.lib |
| |
| ICU_I18N_INCLUDE_DIR C:/icu/include |
| ICU_I18N_LIB C:/icu/lib/icuin.lib |
| |
| ICU_UC_INCLUDE_DIR C:/icu/include |
| ICU_UC_LIB C:/icu/lib/icuuc.lib |
| |
| PROTOBUF_INCLUDE_DIR C:/protobuf-3.6.1/src |
| PROTOBUF_LIB C:/protobuf-3.6.1/vsprojects/Release/libprotobuf.lib |
| PROTOC_BIN C:/protobuf-3.6.1/vsprojects/Release/protoc.exe |
| |
| Then you can click on "Configure" again. CMake should have located all the |
| dependencies. |
| Then click on "Generate" to generate the appropriate Visual Studio project. |
| Then open cpp/build/libphonenumber.sln with Visual Studio and build the INSTALL |
| target. |
| |
| As a result the library's headers and binaries should have been installed to |
| C:/Program Files/libphonenumber/. |
| Note that this path can be set by overriding the CMAKE_INSTALL_PREFIX variable |
| with cmake-gui. |
| |
| |
| Supported build parameters |
| -------------------------- |
| Build parameters can be specified invoking CMake with '-DKEY=VALUE' or using a |
| CMake user interface (ccmake or cmake-gui). |
| |
| USE_ALTERNATE_FORMATS = ON | OFF [ON] -- Use alternate formats for the phone |
| number matcher. |
| USE_BOOST = ON | OFF [ON] -- Use Boost. This is only needed in |
| multi-threaded environments that |
| are not Linux and Mac. |
| Libphonenumber relies on Boost for |
| non-POSIX, non-Windows and non-C++ 2011 |
| multi-threading. |
| USE_ICU_REGEXP = ON | OFF [ON] -- Use ICU regexp engine. |
| USE_LITE_METADATA = ON | OFF [OFF] -- Generates smaller metadata that |
| doesn't include example numbers. |
| USE_POSIX_THREAD = ON | OFF [OFF] -- Use Posix thread for multi-threading. |
| USE_RE2 = ON | OFF [OFF] -- Use RE2. |
| USE_STD_MAP = ON | OFF [OFF] -- Force the use of std::map. |
| USE_STDMUTEX = ON | OFF [OFF] -- Detect and use C++2011 for multi-threading. |
| REGENERATE_METADATA = ON | OFF [ON] -- When this is set to OFF it will skip |
| regenerating the metadata with |
| BuildMetadataCppFromXml. Since the |
| metadata is included in the source |
| tree anyway, it is beneficial for |
| packagers to turn this OFF: it saves |
| some time, and it also makes it |
| unnecessary to have java in the build |
| environment. |