1 C++ version of the libphonenumber project
2 =========================================
4 This library is a port of the Java version.
6 This project uses some third-party code:
7 - src/phonenumbers/utf/ sources come from lib9 which is also used in Go.
10 Installing the library on GNU/Linux
11 -----------------------------------
12 In recent Debian-based distributions you may be able to simply install the
13 libphonenumber library directly.
15 Installing 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
19 Installing the source package:
20 - Use this if you wish to develop or debug the library:
21 $ sudo apt-get source libphonenumber
23 The latest packages can be found on the Debian packages site:
24 https://packages.debian.org/search?searchon=names&keywords=libphonenumber
27 Manually installing the library on GNU/Linux
28 --------------------------------------------
29 You should only need these instructions if the above instructions do not work.
31 The example command lines below assume that you have a Debian-based GNU/Linux
32 distribution. Other distributions and packaging systems will differ.
35 - In recent Debian-based distributions, it should be sufficent 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
40 If any of these packages fails to install correctly, follow the instructions
41 in the appropriate section below.
48 $ sudo apt-get install cmake
50 Additionally it is recommended you install the ccmake configuration tool:
51 $ sudo apt-get install cmake-curses-gui
54 http://code.google.com/p/protobuf/
55 Version 2.4 or more recent is required (this is available by default for
56 recent Debian-based GNU/Linux distributions).
58 You can check which version is available:
59 $ apt-cache show libprotobuf-dev
60 Package: libprotobuf-dev
62 Version: 2.5.0-9ubuntu1 <-- This must be >= 2.4.0
66 $ sudo apt-get install libprotobuf-dev
68 Note: if your GNU/Linux distribution doesn't provide the needed package,
69 please download and install it manually:
70 $ tar xjf protobuf-2.4.tar.bz2
72 $ ./configure && make && sudo make install
75 http://code.google.com/p/googletest/
78 $ sudo apt-get install libgtest-dev
81 http://code.google.com/p/re2/
84 $ sudo apt-get install libre2-dev
86 Note that some distributions (notably Ubuntu 10.4) may not include this,
87 so you might need to download and install it manually.
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
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
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.
104 $ sudo apt-get install libicu-dev
106 Otherwise you need to download the source tarball for the latest version
108 http://site.icu-project.org/download
109 And then extract it via:
110 $ tar xzf icu4c-*-src.tgz
112 Alternatively you can export the SVN repository to the current directory
114 $ svn export http://source.icu-project.org/repos/icu/icu/tags/release-XX-y-z/
116 Having acquired the latest sources, make and install it via:
118 $ ./configure && make && sudo make install
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).
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
129 Note: Boost Thread is the only library needed at link time.
132 Building and testing the library
133 --------------------------------
134 $ cd libphonenumber/cpp
139 $ ./libphonenumber_test
141 Troubleshooting CMake via ccmake
142 --------------------------------
143 Follow these instructions if the build steps above don't work for you.
145 - Incorrect protocol buffer library issues
146 If the build process complains that the version of protoc being used is too
147 old or that it cannot find the correct libprotobuf library, you may need to
148 change the library path of the project.
150 This issue should typically only occur in cases where you have two (or more)
151 versions of the protocol buffer libraries installed on your system. This
152 step assumes that you have already manually downloaded and installed the
153 protocol buffer libraries into /usr/local (as described above).
155 To make cmake use the manually installed version of the protocol buffer
156 libraries, install cmake-curses-gui and use ccmake as follows.
158 From within libphonenumber/cpp/build:
161 You should set the following values:
162 PROTOBUF_INCLUDE_DIR /usr/local/include
163 PROTOBUF_LIB /usr/local/lib/libprotobuf.so
164 PROTOC_BIN /usr/local/bin/protoc
166 Now press 'c' then 'g' to configure the new parameters and exit ccmake.
167 Finally regenerate the make files and rebuild via:
171 - Protoc binary not executing properly
172 If you still have issues with the protoc binary tool in /usr/local/bin not
173 running correctly (cannot find libprotobuf.so.x) then you may need to
174 configure the LD_LIBRARY_PATH. To do this, as a superuser, add the following
176 /etc/ld.so.conf.d/libprotobuf.conf
179 # Use the manually installed version of the protocol buffer libraries.
183 $ sudo chmod 644 /etc/ld.so.conf.d/libprotobuf.conf
186 - Incorrect ICU library issues
187 Similar to the protocol buffer library issue above, it is possible that your
188 build may fail if you have two conflicting versions of the ICU libraries
189 installed on your system. This step assumes that you have already manually
190 downloaded and installed a recent version of the ICU libraries into
193 Install and run the ccmake tool (as described above) and set the following
195 ICU_I18N_INCLUDE_DIR /usr/local/include
196 ICU_I18N_LIB /usr/local/lib/libicui18n.so
197 ICU_UC_INCLUDE_DIR /usr/local/include
198 ICU_UC_LIB /usr/local/lib/libicuuc.so
200 Now press 'c' then 'g' to configure the new parameters and exit ccmake.
201 Finally regenerate the make files and rebuild via:
205 Building the library on Windows (Visual Studio)
206 -----------------------------------------------
207 The library was tested with Visual Studio 2010.
209 You will need to manually fetch and install the following dependencies:
210 - CMake (tested with v2.8.6):
211 http://cmake.org/cmake/resources/software.html
212 * Download and install the Win32 installer.
214 - Boost (tested with v1.44) from BoostPro:
215 http://www.boostpro.com/download/
216 * Select all the variants and Boost DateTime and Boost Thread during the
217 installation process.
218 See Linux instructions for information about thread-safety.
220 - GTest (tested with v1.6.0):
221 http://code.google.com/p/googletest/downloads/list
222 * Open msvc/gtest-md.sln with Visual Studio and build the whole solution.
224 - ICU (MSVC binaries, tested with v4.8.1):
225 http://site.icu-project.org/download/48#ICU4C-Download
226 * Simply extract the archive.
229 http://code.google.com/p/protobuf/downloads/list
230 * Open vsprojects/protobuf.sln with Visual Studio and build the whole
233 Then run cmake-gui and specify the path to the libphonenumber's cpp directory
234 and its build directory which must be created (e.g. cpp/build).
236 When clicking on "Configure", specify the appropriate Visual Studio version
239 Then CMake will need your help to locate the dependencies. You will have to set
240 the following variables (this example assumes that you extracted the
241 dependencies to C:/).
243 GTEST_INCLUDE_DIR C:/gtest-1.6.0/include
244 GTEST_LIB C:/gtest-1.6.0/msvc/gtest-md/Release/gtest.lib
246 ICU_I18N_INCLUDE_DIR C:/icu/include
247 ICU_I18N_LIB C:/icu/lib/icuin.lib
249 ICU_UC_INCLUDE_DIR C:/icu/include
250 ICU_UC_LIB C:/icu/lib/icuuc.lib
252 PROTOBUF_INCLUDE_DIR C:/protobuf-2.4.1/src
253 PROTOBUF_LIB C:/protobuf-2.4.1/vsprojects/Release/libprotobuf.lib
254 PROTOC_BIN C:/protobuf-2.4.1/vsprojects/Release/protoc.exe
256 Then you can click on "Configure" again. CMake should have located all the
258 Then click on "Generate" to generate the appropriate Visual Studio project.
259 Then open cpp/build/libphonenumber.sln with Visual Studio and build the INSTALL
262 As a result the library's headers and binaries should have been installed to
263 C:/Program Files/libphonenumber/.
264 Note that this path can be set by overriding the CMAKE_INSTALL_PREFIX variable
267 Supported build parameters
268 --------------------------
269 Build parameters can be specified invoking CMake with '-DKEY=VALUE' or using a
270 CMake user interface (ccmake or cmake-gui).
272 USE_ALTERNATE_FORMATS = ON | OFF [ON] -- Use alternate formats for the phone
274 USE_BOOST = ON | OFF [ON] -- Use Boost. This is only needed in
275 multi-threaded environments that
276 are not Linux and Mac.
277 Libphonenumber relies on Boost for
278 non-POSIX (e.g. Windows)
280 USE_ICU_REGEXP = ON | OFF [ON] -- Use ICU regexp engine.
281 USE_LITE_METADATA = ON | OFF [OFF] -- Generates smaller metadata that
282 doesn't include example numbers.
283 USE_RE2 = ON | OFF [OFF] -- Use RE2.
284 USE_STD_MAP = ON | OFF [OFF] -- Force the use of std::map.