cpp/README - external/libphonenumber - Git at Google

  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 libphonenumber6 libphonenumber6-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 sufficent 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

 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://code.google.com/p/protobuf/
  Version 2.4 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: 2.5.0-9ubuntu1 <-- This must be >= 2.4.0
  ...

  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:
  $ tar xjf protobuf-2.4.tar.bz2
  $ cd protobuf-2.4
  $ ./configure && make && sudo make install

  - Google Test
  http://code.google.com/p/googletest/

  Installation:
  $ sudo apt-get install libgtest-dev

  - RE2
  http://code.google.com/p/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

  - Boost
  Version 1.40 or more recent is required if you need libphonenumber to be
  thread-safe. If you access libphonenumber from a single thread, you can
  avoid the Boost dependency by disabling the USE_BOOST CMake option (see
  Troubleshooting section below for information about ccmake).

  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.


 Building the library
 --------------------
  $ cd libphonenumber/cpp
  $ mkdir build
  $ cd build
  $ cmake ..
  $ make


 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.so
  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)
 -----------------------------------------------
 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-2.4.1/src
 PROTOBUF_LIB C:/protobuf-2.4.1/vsprojects/Release/libprotobuf.lib
 PROTOC_BIN C:/protobuf-2.4.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 (e.g. Windows)
  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_RE2 = ON | OFF [OFF] -- Use RE2.
  USE_STD_MAP = ON | OFF [OFF] -- Force the use of std::map.
	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 libphonenumber6 libphonenumber6-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 sufficent 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

	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://code.google.com/p/protobuf/
	Version 2.4 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: 2.5.0-9ubuntu1 <-- This must be >= 2.4.0
	...

	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:
	$ tar xjf protobuf-2.4.tar.bz2
	$ cd protobuf-2.4
	$ ./configure && make && sudo make install

	- Google Test
	http://code.google.com/p/googletest/

	Installation:
	$ sudo apt-get install libgtest-dev

	- RE2
	http://code.google.com/p/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

	- Boost
	Version 1.40 or more recent is required if you need libphonenumber to be
	thread-safe. If you access libphonenumber from a single thread, you can
	avoid the Boost dependency by disabling the USE_BOOST CMake option (see
	Troubleshooting section below for information about ccmake).

	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.


	Building the library
	--------------------
	$ cd libphonenumber/cpp
	$ mkdir build
	$ cd build
	$ cmake ..
	$ make


	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.so
	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)
	-----------------------------------------------
	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-2.4.1/src
	PROTOBUF_LIB C:/protobuf-2.4.1/vsprojects/Release/libprotobuf.lib
	PROTOC_BIN C:/protobuf-2.4.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 (e.g. Windows)
	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_RE2 = ON \| OFF [OFF] -- Use RE2.
	USE_STD_MAP = ON \| OFF [OFF] -- Force the use of std::map.