doc/build-macos.md
author Damiano Boppart <damiano@pep-security.net>
Wed, 20 Sep 2017 18:20:45 +0200
branchENGINE-261
changeset 2082 253f13cdf056
parent 2042 e020ff3378c0
child 2210 17c30881c885
permissions -rw-r--r--
Make Makefile ready for local.conf, add deprecation warning to doc
     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 Note: Everything PLATFORM_OVERRIDE-related is currenty outdated. Do not rely on the documentation here!
    80 
    81 For an explanation of the mechanics of `PLATFORM_OVERRIDE`, see the inline comments in `Makefile.conf`.
    82 In this guide, the platform-specific configuration will be called `local`.
    83 The installation directory will be a subdirectory of the repository.
    84 This is useful for testing only.
    85 
    86 ~~~
    87 export PLATFORM_OVERRIDE=local
    88 ~~~
    89 
    90 `./build-config/local.conf`:
    91 
    92 ~~~
    93 PREFIX=$(HOME)/code/pep-engine/build
    94 SYSTEM_DB=$(PREFIX)/share/pEp/system.db
    95 
    96 YML2_PATH=$(HOME)/code/yml2
    97 
    98 ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
    99 ETPAN_INC=-I$(HOME)/code/libetpan/build/include
   100 
   101 GPGME_LIB=-L$(HOME)/code/gpgme/build/lib
   102 GPGME_INC=-I$(HOME)/code/gpgme/build/include
   103 ~~~
   104 
   105 The engine is built as follows:
   106 
   107 ~~~
   108 make all
   109 make db
   110 ~~~
   111 
   112 If your build fails with an error message similar to the following:
   113 
   114 ~~~
   115   File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 477, in _parse_localename
   116     raise ValueError, 'unknown locale: %s' % localename
   117 ValueError: unknown locale: UTF-8
   118 ~~~
   119 
   120 or any other locale-related Python error, make sure Python does not have any locale-related environment variables set.
   121 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.
   122 This is a bug in Python, see [https://bugs.python.org/issue18378#msg215215](https://bugs.python.org/issue18378#msg215215).
   123 
   124 The unit tests can be run without the engine library being installed, however `system.db` must be installed:
   125 
   126 ~~~
   127 make -C db install
   128 ~~~
   129 
   130 Since `system.db` rarely changes, its installation is not needed for every build.
   131 
   132 Tests can be compiled and executed with the following commands:
   133 
   134 ~~~
   135 make -C test compile
   136 make test
   137 ~~~