README
1 C++ version of the libphonenumber project
2 =========================================
3
4This library is a port of the Java version.
5
6This project uses some third-party code:
7 - src/phonenumbers/utf/ sources come from lib9 which is also used in Go.
8
9
10Installing the library on GNU/Linux
11-----------------------------------
12In recent Debian-based distributions you may be able to simply install the
13libphonenumber library directly.
14
15Installing 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
18
19Installing the source package:
20 - Use this if you wish to develop or debug the library:
21 $ sudo apt-get source libphonenumber
22
23The latest packages can be found on the Debian packages site:
24 https://packages.debian.org/search?searchon=names&keywords=libphonenumber
25
26
27Manually installing the library on GNU/Linux
28--------------------------------------------
29You should only need these instructions if the above instructions do not work.
30
31The example command lines below assume that you have a Debian-based GNU/Linux
32distribution. Other distributions and packaging systems will differ.
33
34Quickstart:
35 - In recent Debian-based distributions, it should be sufficient 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 \
39 protobuf-compiler
40
41If any of these packages fails to install correctly, follow the instructions
42in the appropriate section below.
43
44Requirements:
45 - CMake build system
46 http://www.cmake.org
47
48 Installation:
49 $ sudo apt-get install cmake
50
51 Additionally it is recommended you install the ccmake configuration tool:
52 $ sudo apt-get install cmake-curses-gui
53
54 - Protocol Buffers
55 http://github.com/google/protobuf/
56 Version 3.6.1 or more recent is required (this is available by default for
57 recent Debian-based GNU/Linux distributions).
58
59 You can check which version is available:
60 $ apt-cache show libprotobuf-dev
61 Package: libprotobuf-dev
62 Source: protobuf
63 Version: 3.6.1-9ubuntu1 <-- This must be >= 3.6.1
64 ...
65
66 Installation:
67 $ sudo apt-get install libprotobuf-dev
68
69 Note: if your GNU/Linux distribution doesn't provide the needed package,
70 please download and install it manually:
71 More details can be found at its official page:
72 https://github.com/protocolbuffers/protobuf
73
74 - Google Test
75 http://github.com/google/googletest
76
77 Installation:
78 $ sudo apt-get install libgtest-dev
79
80 - RE2
81 http://github.com/google/re2
82
83 Installation:
84 $ sudo apt-get install libre2-dev
85
86 Note that some distributions (notably Ubuntu 10.4) may not include this,
87 so you might need to download and install it manually.
88
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
92
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
96
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.
101
102 - ICU
103 Installation:
104 $ sudo apt-get install libicu-dev
105
106 Otherwise you need to download the source tarball for the latest version
107 from:
108 http://site.icu-project.org/download
109 And then extract it via:
110 $ tar xzf icu4c-*-src.tgz
111
112 Alternatively you can export the SVN repository to the current directory
113 via:
114 $ svn export http://source.icu-project.org/repos/icu/icu/tags/release-XX-y-z/
115
116 Having acquired the latest sources, make and install it via:
117 $ cd icu/source
118 $ ./configure && make && sudo make install
119
120 - Boost
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).
125
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
128
129 Note: Boost Thread is the only library needed at link time.
130
131
132Building and testing the library
133--------------------------------
134 $ cd libphonenumber/cpp
135 $ mkdir build
136 $ cd build
137 $ cmake ..
138 $ make
139 $ ./libphonenumber_test
140
141
142Manually installing the library on Mac
143--------------------------------------
144
145You can easily install dependencies on Mac using a package manager. In these
146instructions we use Homebrew (http://brew.sh).
147
148Install Homebrew package manager and use it to install dependencies:
149 $ /usr/bin/ruby -e "$(curl -fsSL \
150 https://raw.githubusercontent.com/Homebrew/install/master/install)"
151 $ brew install boost cmake icu4c pkg-config protobuf wget
152
153See https://github.com/Homebrew/homebrew/issues/14099 - homebrew does not have
154gtest. We don't need to install gtest, we only copy sources. For example:
155 $ mkdir ~/googletest_clone
156 $ cd ~/googletest_clone
157 $ git clone https://github.com/google/googletest.git
158
159Get the libphonenumber source. For example:
160 $ mkdir ~/libphonenumber_clone
161 $ cd ~/libphonenumber_clone
162 $ git clone https://github.com/google/libphonenumber.git
163
164Build and test the library:
165 $ cd libphonenumber/cpp
166 $ mkdir build
167 $ cd build
168 Replace XXX in the commands below with the appropriate version number:
169 $ cmake \
170 -DGTEST_SOURCE_DIR=~/googletest_clone/googletest/googletest/ \
171 -DGTEST_INCLUDE_DIR=~/googletest_clone/googletest/googletest/include/ \
172 -DICU_UC_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \
173 -DICU_UC_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicuuc.dylib \
174 -DICU_I18N_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \
175 -DICU_I18N_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicui18n.dylib \
176 -DUSE_STD_MAP=ON \
177 ..
178 $ make
179 $ ./libphonenumber_test
180
181Optional: Deleting & uninstalling everything again:
182 $ cd
183 $ rm -rf ~/libphonenumber_clone ~/googletest_clone
184
185 openssl is a dependency of wget and installed with it by Homebrew. If you had
186 openssl before installing wget don't uninstall here.
187 $ brew uninstall boost cmake icu4c openssl pkg-config protobuf wget
188
189 $ /usr/bin/ruby -e "$(curl -fsSL \
190 https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
191
192 Homebrew will have changed permissions at installation. See output of previous
193 command for how to change them back, for example:
194 $ sudo chmod 0755 /usr/local
195 $ sudo chgrp wheel /usr/local
196
197
198Troubleshooting CMake via ccmake
199--------------------------------
200 Follow these instructions if the build steps above don't work for you.
201
202 - Incorrect protocol buffer library issues
203 If the build process complains that the version of protoc being used is too
204 old or that it cannot find the correct libprotobuf library, you may need to
205 change the library path of the project.
206
207 This issue should typically only occur in cases where you have two (or more)
208 versions of the protocol buffer libraries installed on your system. This
209 step assumes that you have already manually downloaded and installed the
210 protocol buffer libraries into /usr/local (as described above).
211
212 To make cmake use the manually installed version of the protocol buffer
213 libraries, install cmake-curses-gui and use ccmake as follows.
214
215 From within libphonenumber/cpp/build:
216 $ ccmake .
217
218 You should set the following values:
219 PROTOBUF_INCLUDE_DIR /usr/local/include
220 PROTOBUF_LIB /usr/local/lib/libprotobuf.dylib
221 PROTOC_BIN /usr/local/bin/protoc
222
223 Now press 'c' then 'g' to configure the new parameters and exit ccmake.
224 Finally regenerate the make files and rebuild via:
225 $ cmake ..
226 $ make
227
228 - Protoc binary not executing properly
229 If you still have issues with the protoc binary tool in /usr/local/bin not
230 running correctly (cannot find libprotobuf.so.x) then you may need to
231 configure the LD_LIBRARY_PATH. To do this, as a superuser, add the following
232 file:
233 /etc/ld.so.conf.d/libprotobuf.conf
234
235 with the contents:
236 # Use the manually installed version of the protocol buffer libraries.
237 /usr/local/lib
238
239 And then run:
240 $ sudo chmod 644 /etc/ld.so.conf.d/libprotobuf.conf
241 $ sudo ldconfig
242
243 - Incorrect ICU library issues
244 Similar to the protocol buffer library issue above, it is possible that your
245 build may fail if you have two conflicting versions of the ICU libraries
246 installed on your system. This step assumes that you have already manually
247 downloaded and installed a recent version of the ICU libraries into
248 /usr/local.
249
250 Install and run the ccmake tool (as described above) and set the following
251 values:
252 ICU_I18N_INCLUDE_DIR /usr/local/include
253 ICU_I18N_LIB /usr/local/lib/libicui18n.so
254 ICU_UC_INCLUDE_DIR /usr/local/include
255 ICU_UC_LIB /usr/local/lib/libicuuc.so
256
257 Now press 'c' then 'g' to configure the new parameters and exit ccmake.
258 Finally regenerate the make files and rebuild via:
259 $ cmake ..
260 $ make
261
262
263Building the library on Windows (Visual Studio)
264-----------------------------------------------
265We recommend that libphonenumber on Windows be built with Visual Studio 2015
266Update 2 (https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update2-vs)
267or later.
268
269This enables support of plain UTF-8 source files, for which you also need to specify
270the /utf-8 option in build files; see "New Options in VS2015 Update 2" at
271https://blogs.msdn.microsoft.com/vcblog/2016/02/22/new-options-for-managing-character-sets-in-the-microsoft-cc-compiler/,
272or a Chrome patch for an example:
273https://codereview.chromium.org/2488853002/diff/80001/build/config/compiler/BUILD.gn
274
275Without this version and the option, your compilation will have warnings when
276setting the codepage for non-Unicode applications on Windows to one of the CJK
277code pages, since libphonenumber has UTF-8 strings in source files. While these
278are only comments (as opposed to string literals) the warnings can be
279suppressed, but we reserve the right to introduce UTF-8 string literals.
280
281The library was tested with Visual Studio 2010.
282
283You will need to manually fetch and install the following dependencies:
284 - CMake (tested with v2.8.6):
285 http://cmake.org/cmake/resources/software.html
286 * Download and install the Win32 installer.
287
288 - Boost (tested with v1.44) from BoostPro:
289 http://www.boostpro.com/download/
290 * Select all the variants and Boost DateTime and Boost Thread during the
291 installation process.
292 See Linux instructions for information about thread-safety.
293
294 - GTest (tested with v1.6.0):
295 http://code.google.com/p/googletest/downloads/list
296 * Open msvc/gtest-md.sln with Visual Studio and build the whole solution.
297
298 - ICU (MSVC binaries, tested with v4.8.1):
299 http://site.icu-project.org/download/48#ICU4C-Download
300 * Simply extract the archive.
301
302 - Protocol Buffers:
303 http://code.google.com/p/protobuf/downloads/list
304 * Open vsprojects/protobuf.sln with Visual Studio and build the whole
305 solution.
306
307Then run cmake-gui and specify the path to the libphonenumber's cpp directory
308and its build directory which must be created (e.g. cpp/build).
309
310When clicking on "Configure", specify the appropriate Visual Studio version
311(tested with 2010).
312
313Then CMake will need your help to locate the dependencies. You will have to set
314the following variables (this example assumes that you extracted the
315dependencies to C:/).
316
317GTEST_INCLUDE_DIR C:/gtest-1.6.0/include
318GTEST_LIB C:/gtest-1.6.0/msvc/gtest-md/Release/gtest.lib
319
320ICU_I18N_INCLUDE_DIR C:/icu/include
321ICU_I18N_LIB C:/icu/lib/icuin.lib
322
323ICU_UC_INCLUDE_DIR C:/icu/include
324ICU_UC_LIB C:/icu/lib/icuuc.lib
325
326PROTOBUF_INCLUDE_DIR C:/protobuf-3.6.1/src
327PROTOBUF_LIB C:/protobuf-3.6.1/vsprojects/Release/libprotobuf.lib
328PROTOC_BIN C:/protobuf-3.6.1/vsprojects/Release/protoc.exe
329
330Then you can click on "Configure" again. CMake should have located all the
331dependencies.
332Then click on "Generate" to generate the appropriate Visual Studio project.
333Then open cpp/build/libphonenumber.sln with Visual Studio and build the INSTALL
334target.
335
336As a result the library's headers and binaries should have been installed to
337C:/Program Files/libphonenumber/.
338Note that this path can be set by overriding the CMAKE_INSTALL_PREFIX variable
339with cmake-gui.
340
341
342Supported build parameters
343--------------------------
344 Build parameters can be specified invoking CMake with '-DKEY=VALUE' or using a
345 CMake user interface (ccmake or cmake-gui).
346
347 USE_ALTERNATE_FORMATS = ON | OFF [ON] -- Use alternate formats for the phone
348 number matcher.
349 USE_BOOST = ON | OFF [ON] -- Use Boost. This is only needed in
350 multi-threaded environments that
351 are not Linux and Mac.
352 Libphonenumber relies on Boost for
353 non-POSIX (e.g. Windows)
354 multi-threading.
355 USE_ICU_REGEXP = ON | OFF [ON] -- Use ICU regexp engine.
356 USE_LITE_METADATA = ON | OFF [OFF] -- Generates smaller metadata that
357 doesn't include example numbers.
358 USE_RE2 = ON | OFF [OFF] -- Use RE2.
359 USE_STD_MAP = ON | OFF [OFF] -- Force the use of std::map.
360