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