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 libphonenumber8 libphonenumber-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 - A thread synchronization solution or more recent is required if you need
121 libphonenumber to be thread-safe. Supported solution are:
122 - Boost Version 1.40 or more recent
123 - Posix Thread. Linux or Apple (ios/mac) detection is automatic. On other
124 Posix environnement, uses -DUSE_POSIX_THREAD = ON
125 - C++ 2011 (and later) std::mutex. Uses -DUSE_STDMUTEX = ON to enable
126 automatic C++ 2011 detection (if you prefer Posix or Win32 solution).
127 - Windows Win32 synchronization API.
128
129 If you access libphonenumber from a single thread, you don't need one of
130 these solution.
131
132 You can install it very easily on a Debian-based GNU/Linux distribution:
133 $ sudo apt-get install libboost-dev libboost-thread-dev libboost-system-dev
134
135 Note: Boost Thread is the only library needed at link time.
136
137
138Building and testing the library
139--------------------------------
140 $ cd libphonenumber/cpp
141 $ mkdir build
142 $ cd build
143 $ cmake ..
144 $ make
145 $ ./libphonenumber_test
146
147
148Manually installing the library on Mac
149--------------------------------------
150
151You can easily install dependencies on Mac using a package manager. In these
152instructions we use Homebrew (http://brew.sh).
153
154Install Homebrew package manager and use it to install dependencies:
155 $ /usr/bin/ruby -e "$(curl -fsSL \
156 https://raw.githubusercontent.com/Homebrew/install/master/install)"
157 $ brew install boost cmake icu4c pkg-config protobuf wget
158
159See https://github.com/Homebrew/homebrew/issues/14099 - homebrew does not have
160gtest. We don't need to install gtest, we only copy sources. For example:
161 $ mkdir ~/googletest_clone
162 $ cd ~/googletest_clone
163 $ git clone https://github.com/google/googletest.git
164
165Get the libphonenumber source. For example:
166 $ mkdir ~/libphonenumber_clone
167 $ cd ~/libphonenumber_clone
168 $ git clone https://github.com/google/libphonenumber.git
169
170Build and test the library:
171 $ cd libphonenumber/cpp
172 $ mkdir build
173 $ cd build
174 Replace XXX in the commands below with the appropriate version number:
175 $ cmake \
176 -DGTEST_SOURCE_DIR=~/googletest_clone/googletest/googletest/ \
177 -DGTEST_INCLUDE_DIR=~/googletest_clone/googletest/googletest/include/ \
178 -DICU_UC_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \
179 -DICU_UC_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicuuc.dylib \
180 -DICU_I18N_INCLUDE_DIR=/usr/local/Cellar/icu4c/XXX/include/ \
181 -DICU_I18N_LIB=/usr/local/Cellar/icu4c/XXX/lib/libicui18n.dylib \
182 -DUSE_STD_MAP=ON \
183 ..
184 $ make
185 $ ./libphonenumber_test
186
187Optional: Deleting & uninstalling everything again:
188 $ cd
189 $ rm -rf ~/libphonenumber_clone ~/googletest_clone
190
191 openssl is a dependency of wget and installed with it by Homebrew. If you had
192 openssl before installing wget don't uninstall here.
193 $ brew uninstall boost cmake icu4c openssl pkg-config protobuf wget
194
195 $ /usr/bin/ruby -e "$(curl -fsSL \
196 https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
197
198 Homebrew will have changed permissions at installation. See output of previous
199 command for how to change them back, for example:
200 $ sudo chmod 0755 /usr/local
201 $ sudo chgrp wheel /usr/local
202
203
204Troubleshooting CMake via ccmake
205--------------------------------
206 Follow these instructions if the build steps above don't work for you.
207
208 - Incorrect protocol buffer library issues
209 If the build process complains that the version of protoc being used is too
210 old or that it cannot find the correct libprotobuf library, you may need to
211 change the library path of the project.
212
213 This issue should typically only occur in cases where you have two (or more)
214 versions of the protocol buffer libraries installed on your system. This
215 step assumes that you have already manually downloaded and installed the
216 protocol buffer libraries into /usr/local (as described above).
217
218 To make cmake use the manually installed version of the protocol buffer
219 libraries, install cmake-curses-gui and use ccmake as follows.
220
221 From within libphonenumber/cpp/build:
222 $ ccmake .
223
224 You should set the following values:
225 PROTOBUF_INCLUDE_DIR /usr/local/include
226 PROTOBUF_LIB /usr/local/lib/libprotobuf.dylib
227 PROTOC_BIN /usr/local/bin/protoc
228
229 Now press 'c' then 'g' to configure the new parameters and exit ccmake.
230 Finally regenerate the make files and rebuild via:
231 $ cmake ..
232 $ make
233
234 - Protoc binary not executing properly
235 If you still have issues with the protoc binary tool in /usr/local/bin not
236 running correctly (cannot find libprotobuf.so.x) then you may need to
237 configure the LD_LIBRARY_PATH. To do this, as a superuser, add the following
238 file:
239 /etc/ld.so.conf.d/libprotobuf.conf
240
241 with the contents:
242 # Use the manually installed version of the protocol buffer libraries.
243 /usr/local/lib
244
245 And then run:
246 $ sudo chmod 644 /etc/ld.so.conf.d/libprotobuf.conf
247 $ sudo ldconfig
248
249 - Incorrect ICU library issues
250 Similar to the protocol buffer library issue above, it is possible that your
251 build may fail if you have two conflicting versions of the ICU libraries
252 installed on your system. This step assumes that you have already manually
253 downloaded and installed a recent version of the ICU libraries into
254 /usr/local.
255
256 Install and run the ccmake tool (as described above) and set the following
257 values:
258 ICU_I18N_INCLUDE_DIR /usr/local/include
259 ICU_I18N_LIB /usr/local/lib/libicui18n.so
260 ICU_UC_INCLUDE_DIR /usr/local/include
261 ICU_UC_LIB /usr/local/lib/libicuuc.so
262
263 Now press 'c' then 'g' to configure the new parameters and exit ccmake.
264 Finally regenerate the make files and rebuild via:
265 $ cmake ..
266 $ make
267
268
269Building the library on Windows (Visual Studio)
270-----------------------------------------------
271We recommend that libphonenumber on Windows be built with Visual Studio 2015
272Update 2 (https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update2-vs)
273or later.
274
275This enables support of plain UTF-8 source files, for which you also need to specify
276the /utf-8 option in build files; see "New Options in VS2015 Update 2" at
277https://blogs.msdn.microsoft.com/vcblog/2016/02/22/new-options-for-managing-character-sets-in-the-microsoft-cc-compiler/,
278or a Chrome patch for an example:
279https://codereview.chromium.org/2488853002/diff/80001/build/config/compiler/BUILD.gn
280
281Without this version and the option, your compilation will have warnings when
282setting the codepage for non-Unicode applications on Windows to one of the CJK
283code pages, since libphonenumber has UTF-8 strings in source files. While these
284are only comments (as opposed to string literals) the warnings can be
285suppressed, but we reserve the right to introduce UTF-8 string literals.
286
287The library was tested with Visual Studio 2010.
288
289You will need to manually fetch and install the following dependencies:
290 - CMake (tested with v2.8.6):
291 http://cmake.org/cmake/resources/software.html
292 * Download and install the Win32 installer.
293
294 - Boost (tested with v1.44) from BoostPro:
295 http://www.boostpro.com/download/
296 * Select all the variants and Boost DateTime and Boost Thread during the
297 installation process.
298 See Linux instructions for information about thread-safety.
299
300 - GTest (tested with v1.6.0):
301 http://code.google.com/p/googletest/downloads/list
302 * Open msvc/gtest-md.sln with Visual Studio and build the whole solution.
303
304 - ICU (MSVC binaries, tested with v4.8.1):
305 http://site.icu-project.org/download/48#ICU4C-Download
306 * Simply extract the archive.
307
308 - Protocol Buffers:
309 http://code.google.com/p/protobuf/downloads/list
310 * Open vsprojects/protobuf.sln with Visual Studio and build the whole
311 solution.
312
313Then run cmake-gui and specify the path to the libphonenumber's cpp directory
314and its build directory which must be created (e.g. cpp/build).
315
316When clicking on "Configure", specify the appropriate Visual Studio version
317(tested with 2010).
318
319Then CMake will need your help to locate the dependencies. You will have to set
320the following variables (this example assumes that you extracted the
321dependencies to C:/).
322
323GTEST_INCLUDE_DIR C:/gtest-1.6.0/include
324GTEST_LIB C:/gtest-1.6.0/msvc/gtest-md/Release/gtest.lib
325
326ICU_I18N_INCLUDE_DIR C:/icu/include
327ICU_I18N_LIB C:/icu/lib/icuin.lib
328
329ICU_UC_INCLUDE_DIR C:/icu/include
330ICU_UC_LIB C:/icu/lib/icuuc.lib
331
332PROTOBUF_INCLUDE_DIR C:/protobuf-3.6.1/src
333PROTOBUF_LIB C:/protobuf-3.6.1/vsprojects/Release/libprotobuf.lib
334PROTOC_BIN C:/protobuf-3.6.1/vsprojects/Release/protoc.exe
335
336Then you can click on "Configure" again. CMake should have located all the
337dependencies.
338Then click on "Generate" to generate the appropriate Visual Studio project.
339Then open cpp/build/libphonenumber.sln with Visual Studio and build the INSTALL
340target.
341
342As a result the library's headers and binaries should have been installed to
343C:/Program Files/libphonenumber/.
344Note that this path can be set by overriding the CMAKE_INSTALL_PREFIX variable
345with cmake-gui.
346
347
348Supported build parameters
349--------------------------
350 Build parameters can be specified invoking CMake with '-DKEY=VALUE' or using a
351 CMake user interface (ccmake or cmake-gui).
352
353 USE_ALTERNATE_FORMATS = ON | OFF [ON] -- Use alternate formats for the phone
354 number matcher.
355 USE_BOOST = ON | OFF [ON] -- Use Boost. This is only needed in
356 multi-threaded environments that
357 are not Linux and Mac.
358 Libphonenumber relies on Boost for
359 non-POSIX, non-Windows and non-C++ 2011
360 multi-threading.
361 USE_ICU_REGEXP = ON | OFF [ON] -- Use ICU regexp engine.
362 USE_LITE_METADATA = ON | OFF [OFF] -- Generates smaller metadata that
363 doesn't include example numbers.
364 USE_POSIX_THREAD = ON | OFF [OFF] -- Use Posix thread for multi-threading.
365 USE_RE2 = ON | OFF [OFF] -- Use RE2.
366 USE_STD_MAP = ON | OFF [OFF] -- Force the use of std::map.
367 USE_STDMUTEX = ON | OFF [OFF] -- Detect and use C++2011 for multi-threading.
368 REGENERATE_METADATA = ON | OFF [ON] -- When this is set to OFF it will skip
369 regenerating the metadata with
370 BuildMetadataCppFromXml. Since the
371 metadata is included in the source
372 tree anyway, it is beneficial for
373 packagers to turn this OFF: it saves
374 some time, and it also makes it
375 unnecessary to have java in the build
376 environment.
377