doc/build-macos.md
author Damiano Boppart <damiano@pep-security.net>
Tue, 12 Sep 2017 15:47:45 +0200
changeset 2042 e020ff3378c0
parent 2039 b88e62c9ea72
child 2082 253f13cdf056
permissions -rw-r--r--
Update documentation to reflect last change
     1 <!-- Copyright 2015-2017, pEp foundation, Switzerland
     2 This file is part of the pEp Engine
     3 This file may be used under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) License
     4 See CC_BY-SA.txt -->
     5 
     6 # Build instructions for macOS Sierra
     7 
     8 # Installing packaged dependencies
     9 
    10 ## MacPorts
    11 
    12 MacPorts is needed to install some compile-time dependencies.
    13 Install MacPorts according to the instructions found [here](https://www.macports.org/install.php).
    14 Ensure that Macports' binary paths (`/opt/local/bin` and `/opt/local/sbin`) are in your `PATH` environment variable.
    15 
    16 ~~~
    17 # general
    18 sudo port install mercurial
    19 # YML2
    20 sudo port install py27-lxml
    21 # libetpan
    22 sudo port install git autoconf automake libtool
    23 # asn1c
    24 sudo port install asn1c
    25 # engine
    26 sudo port install gpgme
    27 ~~~
    28 
    29 Ensure that `python` is Python 2.7:
    30 
    31 ~~~
    32 sudo port select python python27
    33 ~~~
    34 
    35 # Installing unpackaged dependencies
    36 ## YML2
    37 
    38 ~~~
    39 mkdir -p ~/code/yml2
    40 hg clone https://cacert.pep.foundation/dev/repos/yml2/ ~/code/yml2
    41 ~~~
    42 
    43 ## libetpan
    44 pEp Engine requires libetpan with a set of patches that have not been upstreamed yet.
    45 
    46 ~~~
    47 mkdir -p ~/code/libetpan
    48 git clone https://github.com/fdik/libetpan ~/code/libetpan
    49 cd ~/code/libetpan
    50 mkdir ~/code/libetpan/build
    51 ./autogen.sh --prefix="$HOME/code/libetpan/build"
    52 make
    53 make install
    54 ~~~
    55 
    56 ## GPGME
    57 The MacPorts-packaged GPGME links to a version of GNU libiconv that has files in the same include/library paths as GPGME. This version of libiconv must not be visible to the linker when the pEp Engine is build or run.
    58 
    59 Thus the files of the GPGME distribution will have to be manually copied to separate include/library folders, so that no include or library paths used for building the pEp Engine contains files of MacPorts' libiconv distribution.
    60 
    61 ~~~
    62 mkdir -p ~/code/gpgme/build/include
    63 cp /opt/local/include/gpg*.h ~/code/gpgme/build/include
    64 mkdir -p ~/code/gpgme/build/lib
    65 cp -r /opt/local/lib/libgpg* ~/code/gpgme/build/lib
    66 ~~~
    67 
    68 It's of course possible to skip MacPort's version, and use a self-compiled GPGME/GPG. The default build configuration assumes this case, and assumes you have installed your GPGME with `$(HOME)` as your prefix.
    69 
    70 # pEp Engine
    71 
    72 ~~~
    73 mkdir -p ~/code/pep-engine
    74 hg clone https://cacert.pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine
    75 cd ~/code/pep-engine
    76 mkdir ~/code/pep-engine/build
    77 ~~~
    78 
    79 For an explanation of the mechanics of `PLATFORM_OVERRIDE`, see the inline comments in `Makefile.conf`.
    80 In this guide, the platform-specific configuration will be called `local`.
    81 The installation directory will be a subdirectory of the repository.
    82 This is useful for testing only.
    83 
    84 ~~~
    85 export PLATFORM_OVERRIDE=local
    86 ~~~
    87 
    88 `./build-config/local.conf`:
    89 
    90 ~~~
    91 PREFIX=$(HOME)/code/pep-engine/build
    92 SYSTEM_DB=$(PREFIX)/share/pEp/system.db
    93 
    94 YML2_PATH=$(HOME)/code/yml2
    95 
    96 ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
    97 ETPAN_INC=-I$(HOME)/code/libetpan/build/include
    98 
    99 GPGME_LIB=-L$(HOME)/code/gpgme/build/lib
   100 GPGME_INC=-I$(HOME)/code/gpgme/build/include
   101 ~~~
   102 
   103 The engine is built as follows:
   104 
   105 ~~~
   106 make all
   107 make db
   108 ~~~
   109 
   110 If your build fails with an error message similar to the following:
   111 
   112 ~~~
   113   File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 477, in _parse_localename
   114     raise ValueError, 'unknown locale: %s' % localename
   115 ValueError: unknown locale: UTF-8
   116 ~~~
   117 
   118 or any other locale-related Python error, make sure Python does not have any locale-related environment variables set.
   119 Usually, `unset LC_CTYPE` is sufficient to take care of the problem, but it depends on your macOS's regional and language settings and which terminal emulator you use.
   120 This is a bug in Python, see [https://bugs.python.org/issue18378#msg215215](https://bugs.python.org/issue18378#msg215215).
   121 
   122 The unit tests can be run without the engine library being installed, however `system.db` must be installed:
   123 
   124 ~~~
   125 make -C db install
   126 ~~~
   127 
   128 Since `system.db` rarely changes, its installation is not needed for every build.
   129 
   130 Tests can be compiled and executed with the following commands:
   131 
   132 ~~~
   133 make -C test compile
   134 make test
   135 ~~~