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