doc/build-macos.md
author Damiano Boppart <damiano@pep-security.net>
Fri, 27 Oct 2017 17:21:25 +0200
branchdiphoton_M1
changeset 2258 340598e126a2
parent 2218 da5d2c04cd94
child 2296 1a12f577ac71
permissions -rw-r--r--
Update documentation to reflect the changes to Makefile.conf
     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 Edit the build configuration to your needs in `Makefile.conf`, or create a `local.conf` that sets any of the make variables documented in `Makefile.conf`. All the default values for the build configuration variables on each platform are documented in `default.conf`.
    80 
    81 If a dependency is not found in your system's default include or library paths, you will have to specify the according paths in a make variable. Typically, this has to be done at least for YML2, and libetpan.
    82 
    83 For a more detailed explanation of the mechanics of these build configuration files, and overriding defaults, see the comments in `default.conf`.
    84 
    85 Below is a sample `./local.conf` file, for orientation.
    86 
    87 ~~~
    88 PREFIX=$(HOME)/code/engine/build
    89 SYSTEM_DB=$(PREFIX)/share/pEp/system.db
    90 
    91 YML2_PATH=$(HOME)/code/yml2
    92 
    93 ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
    94 ETPAN_INC=-I$(HOME)/code/libetpan/build/include
    95 
    96 GPGME_LIB=-L$(HOME)/lib
    97 GPGME_INC=-I$(HOME)/include
    98 ~~~
    99 
   100 The engine is built as follows:
   101 
   102 ~~~
   103 make all
   104 make db
   105 ~~~
   106 
   107 If your build fails with an error message similar to the following:
   108 
   109 ~~~
   110   File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 477, in _parse_localename
   111     raise ValueError, 'unknown locale: %s' % localename
   112 ValueError: unknown locale: UTF-8
   113 ~~~
   114 
   115 or any other locale-related Python error, make sure Python does not have any locale-related environment variables set.
   116 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.
   117 This is a bug in Python, see [https://bugs.python.org/issue18378#msg215215](https://bugs.python.org/issue18378#msg215215).
   118 
   119 The unit tests can be run without the engine library being installed, however `system.db` must be installed:
   120 
   121 ~~~
   122 make -C db install
   123 ~~~
   124 
   125 Since `system.db` rarely changes, its installation is not needed for every build.
   126 
   127 Tests can be compiled and executed with the following commands:
   128 
   129 ~~~
   130 make -C test compile
   131 make test
   132 ~~~