-C++ version of the libphonenumber project.
-Work in progress.
+ C++ version of the libphonenumber project
+ =========================================
-This is a port of the Java version.
+This library is a port of the Java version.
This project uses some third-party code:
- - src/base/ sources come from Chromium browser.
- - src/utf/ sources come from lib9 which is also used in Go.
+ - 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
- You can install it very easily on a Debian-based GNU/Linux distribution:
+ 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.
+ Version 2.4 or more recent is required (this is available by default for
+ recent Debian-based GNU/Linux distributions).
- You can install it very easily on a Debian-based GNU/Linux distribution:
+ 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,
- Google Test
http://code.google.com/p/googletest/
- You can install it very easily on a Debian-based GNU/Linux distribution:
+ Installation:
$ sudo apt-get install libgtest-dev
- RE2
http://code.google.com/p/re2/
- You can install it very easily on Ubuntu Maverick and later:
+ Installation:
$ sudo apt-get install libre2-dev
- Otherwise if you use a Debian-based distribution you can fetch the Ubuntu
- package which should work:
- http://packages.ubuntu.com/maverick/libre2-dev
+ Note that some distributions (notably Ubuntu 10.4) may not include this,
+ so you might need to download and install it manually.
- If you want to install it manually:
- You need Mercurial to checkout its source code:
- $ sudo apt-get install mercurial
+ 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
- Then checkout, build and install it:
- $ hg clone https://re2.googlecode.com/hg re2
- $ cd re2
- $ make test
- $ make install
- $ make testinstall
+ 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
- Version 4.4 or more recent is required.
- It can be built from sources. You need to download the source tarball at
- this location:
- http://site.icu-project.org/download
- Then you can extract, build and install it this way:
- $ tar xzf icu4c-4_4_2-src.tgz
+ 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
- If you have a Debian-based distribution providing an up-to-date version of
- ICU, you can install it using apt-get:
- $ sudo apt-get install libicu-dev
-
- Boost
- Version 1.40 or more recent is required.
+ 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 libboost1.40-dev libboost-thread1.40-dev
+ $ sudo apt-get install libboost-dev libboost-thread-dev libboost-system-dev
Note: Boost Thread is the only library needed at link time.
-How to build libphonenumber C++:
- $ cd libphonenumber
+
+Building the library
+--------------------
+ $ cd libphonenumber/cpp
$ mkdir build
$ cd build
$ cmake ..
$ make
-Supported build parameters:
+
+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_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.
+ 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.
projects / platform / upstream / libphonenumber.git / blobdiff