diff --git a/cpp/README b/cpp/README index d114fe170..bbdaf36a0 100644 --- a/cpp/README +++ b/cpp/README @@ -1,395 +1,215 @@ - C++ version of the libphonenumber project - ========================================= -This library is a port of the Java version. +# libphonenumber C++ Library -This project uses some third-party code: - - src/phonenumbers/utf/ sources come from lib9 which is also used in Go. +A C++ port of the original Java [libphonenumber](https://github.com/google/libphonenumber) library. +This project includes some third-party code, such as sources from [lib9 UTF-8 package](https://github.com/golang/go/tree/master/src/internal/utf8) used in `src/phonenumbers/utf/`. -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 +## Table of Contents -Installing the source package: - - Use this if you wish to develop or debug the library: - $ sudo apt-get source libphonenumber +- [Installation on GNU/Linux](#installation-on-gnulinux) + - [Using Packages (Debian-based)](#using-packages-debian-based) + - [Manual Build](#manual-build) +- [Installation on macOS](#installation-on-macos) +- [Building and Testing](#building-and-testing) +- [Troubleshooting](#troubleshooting) +- [Building on Windows](#building-on-windows) +- [Supported Build Options](#supported-build-options) -The latest packages can be found on the Debian packages site: - https://packages.debian.org/search?searchon=names&keywords=libphonenumber +--- +## Installation on GNU/Linux -Manually installing the library on GNU/Linux --------------------------------------------- -You should only need these instructions if the above instructions do not work. +### Using Packages (Debian-based) -The example command lines below assume that you have a Debian-based GNU/Linux -distribution. Other distributions and packaging systems will differ. +If you want to simply use or link the library: -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 +```bash +sudo apt-get install libphonenumber8 libphonenumber-dev +``` -If any of these packages fails to install correctly, follow the instructions -in the appropriate section below. +For development or debugging: -Requirements: - - CMake build system - http://www.cmake.org +```bash +sudo apt-get source libphonenumber +``` - Installation: - $ sudo apt-get install cmake +Latest packages can be found at: +[https://packages.debian.org/search?searchon=names&keywords=libphonenumber](https://packages.debian.org/search?searchon=names&keywords=libphonenumber) - 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: - https://packages.ubuntu.com/search?keywords=libre2-9 - https://packages.ubuntu.com/search?keywords=libre2-dev - - You need to download both the libre2-dev and libre2-1 packages. - Once downloaded, install them with: - $ sudo dpkg -i libre2*.deb - - - 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 solutions. - - 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 - $ 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. +--- + +### Manual Build + +Use this if packages are unavailable or you want to build from source. + +#### Prerequisites + +- **CMake** + +```bash +sudo apt-get install cmake cmake-curses-gui +``` + +- **Protocol Buffers (≥ 3.6.1)** + +```bash +sudo apt-get install libprotobuf-dev protobuf-compiler +``` + +If unavailable, see: https://github.com/protocolbuffers/protobuf + +- **Google Test** + +```bash +sudo apt-get install libgtest-dev +``` + +- **RE2** + +```bash +sudo apt-get install libre2-dev +``` + +- **ICU** + +```bash +sudo apt-get install libicu-dev +``` + +- **Thread Synchronization (optional, for thread safety)** + +Supported options: +- Boost (≥ 1.40) +- POSIX Threads (Linux/macOS) +- C++11 `std::mutex` (`-DUSE_STDMUTEX=ON`) +- Windows Win32 API + +--- + +### On Debian, install Boost libraries: + +```bash +sudo apt-get install libboost-dev libboost-thread-dev libboost-system-dev +``` + +Abseil-cpp is downloaded and built automatically but can also be installed manually: +https://abseil.io/docs/cpp/tools/cmake-installs + +--- + +## Installation on macOS + +Install [Homebrew](https://brew.sh) if you don't have it: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +### Install dependencies: + +```bash +brew install boost cmake icu4c pkg-config protobuf wget +``` + +### Clone GoogleTest (not available via Homebrew): + +```bash +mkdir ~/googletest_clone +cd ~/googletest_clone +git clone https://github.com/google/googletest.git +``` + +### Clone libphonenumber: + +```bash +mkdir ~/libphonenumber_clone +cd ~/libphonenumber_clone +git clone https://github.com/google/libphonenumber.git +``` + +--- + +## Building and Testing + +```bash +cd libphonenumber/cpp +mkdir build && cd build +``` + +### Replace `XXX` with your ICU version number (e.g., `77`) + +To find your ICU version number, run: + +```bash +ls /usr/local/Cellar/icu4c/ +``` + +If no versions are found, install ICU with: + +```bash +brew install icu4c +``` + +Then replace `XXX` with the installed version number. + +### Configure and build: + +```bash +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 +``` + +--- + +## Troubleshooting + +### Protobuf Issues + +If you encounter issues with Protocol Buffers, use `ccmake` or another CMake GUI to set: + +```bash +PROTOBUF_INCLUDE_DIR /usr/local/include +PROTOBUF_LIB /usr/local/lib/libprotobuf.dylib +PROTOC_BIN /usr/local/bin/protoc +``` + +### ICU Issues + +Set ICU paths appropriately: + +```bash +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 +``` + +--- + +## Building on Windows + +1. Use Visual Studio 2015 Update 2 or later. +2. Manually install dependencies: CMake, Boost, GTest, ICU, Protobuf. +3. Use `cmake-gui` to configure and generate project files. +4. Build the `INSTALL` target to install the library. + +--- + +## Supported Build Options + +| Option | Default | Description | +|---------------------|---------|-----------------------------------------------| +| USE_ALTERNATE_FORMATS| ON | Use alternate phone number formats | +| USE_BOOST | ON | Use Boost libraries for threading | +| USE_ICU_REGEXP | ON | Use ICU regular expressions | +| USE_LITE_METADATA | OFF | Generate smaller metadata without example numbers| +| USE_POSIX_THREAD | OFF | Use POSIX threads | +| USE_RE2 | OFF | Use RE2 regex engine | +| USE_STD_MAP | OFF | Force use of std::map | +| USE_STDMUTEX | OFF | Use C++11 std::mutex | +| REGENERATE_METADATA | ON | Regenerate metadata during build |