doc/build-macos.md
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Fri, 03 Apr 2020 10:07:40 +0200
branchmaintain
changeset 4528 c270a05ee98e
parent 4456 c0c7a44a731c
permissions -rw-r--r--
closing branch: please use branch 'postrelease'
     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 You will find instructions for using either Macports or Homebrew below to install the compile-time dependencies.
    10 
    11 ## MacPorts
    12 Install MacPorts according to the instructions found [here](https://www.macports.org/install.php).
    13 Ensure that Macports' binary paths (`/opt/local/bin` and `/opt/local/sbin`) are in your `PATH` environment variable.
    14 
    15 ~~~
    16 # general
    17 sudo port install mercurial
    18 # YML2
    19 sudo port install py27-lxml
    20 # libetpan
    21 sudo port install git autoconf automake libtool
    22 # asn1c
    23 sudo port install asn1c
    24 # engine
    25 sudo port install gpgme
    26 ~~~
    27 
    28 Ensure that `python` is Python 2.7:
    29 
    30 ~~~
    31 sudo port select python python27
    32 ~~~
    33 
    34 ## Homebrew
    35 Install Homebrew according to the instructions found [here](https://docs.brew.sh/Installation.html).
    36 Ensure that Homebrew's binary path (`/usr/local/bin`) is in your `PATH` environment variable.
    37 
    38 ~~~
    39 # general
    40 brew install mercurial
    41 # YML2
    42 # If you don't have pip with your Python 2 distribution, you can install it with brew
    43 brew install python
    44 pip2 install --user lxml
    45 # libetpan
    46 brew install git autoconf automake libtool
    47 # asn1c
    48 brew install asn1c
    49 # engine
    50 brew install gpgme
    51 ~~~
    52 
    53 # Installing unpackaged dependencies
    54 ## YML2
    55 To check if lxml is properly installed, you can use this lxml "hello world" command:
    56 
    57 ~~~
    58 python2 -c 'from lxml import etree; root = etree.Element("root"); print(root.tag)'
    59 ~~~
    60 
    61 It should generate the following output:
    62 
    63 ~~~
    64 root
    65 ~~~
    66 
    67 ~~~
    68 mkdir -p ~/code/yml2
    69 hg clone https://pep.foundation/dev/repos/yml2/ ~/code/yml2
    70 ~~~
    71 
    72 ## libetpan
    73 pEp Engine requires libetpan with a set of patches that have not been upstreamed yet.
    74 
    75 ~~~
    76 mkdir -p ~/code/libetpan
    77 git clone https://github.com/fdik/libetpan ~/code/libetpan
    78 cd ~/code/libetpan
    79 mkdir ~/code/libetpan/build
    80 ./autogen.sh --prefix="$HOME/code/libetpan/build"
    81 make
    82 make install
    83 ~~~
    84 
    85 ## GPGME
    86 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.
    87 
    88 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.
    89 
    90 ~~~
    91 mkdir -p ~/code/gpgme/build/include
    92 cp /opt/local/include/gpg*.h ~/code/gpgme/build/include
    93 mkdir -p ~/code/gpgme/build/lib
    94 cp -r /opt/local/lib/libgpg* ~/code/gpgme/build/lib
    95 ~~~
    96 
    97 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.
    98 
    99 # pEp Engine
   100 
   101 ~~~
   102 mkdir -p ~/code/pep-engine
   103 hg clone https://pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine
   104 cd ~/code/pep-engine
   105 mkdir ~/code/pep-engine/build
   106 ~~~
   107 
   108 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 `Makefile.conf`.
   109 
   110 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.
   111 
   112 For a more detailed explanation of the mechanics of these build configuration files, and overriding defaults, see the comments in `Makefile.conf`.
   113 
   114 Below is a sample `./local.conf` file, for orientation.
   115 
   116 ~~~
   117 PREFIX=$(HOME)/code/engine/build
   118 PER_MACHINE_DIRECTORY=$(PREFIX)/share/pEp
   119 
   120 YML2_PATH=$(HOME)/code/yml2
   121 
   122 ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
   123 ETPAN_INC=-I$(HOME)/code/libetpan/build/include
   124 
   125 GPGME_LIB=-L$(HOME)/lib
   126 GPGME_INC=-I$(HOME)/include
   127 ~~~
   128 
   129 The engine is built as follows:
   130 
   131 ~~~
   132 make all
   133 make db
   134 ~~~
   135 
   136 If your build fails with an error message similar to the following:
   137 
   138 ~~~
   139   File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 477, in _parse_localename
   140     raise ValueError, 'unknown locale: %s' % localename
   141 ValueError: unknown locale: UTF-8
   142 ~~~
   143 
   144 or any other locale-related Python error, make sure Python does not have any locale-related environment variables set.
   145 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.
   146 This is a bug in Python, see [https://bugs.python.org/issue18378#msg215215](https://bugs.python.org/issue18378#msg215215).
   147 
   148 The unit tests can be run without the engine library being installed, however `system.db` must be installed:
   149 
   150 ~~~
   151 make -C db install
   152 ~~~
   153 
   154 Since `system.db` rarely changes, its installation is not needed for every build.
   155 
   156 Tests can be compiled and executed with the following commands:
   157 
   158 ~~~
   159 make -C test compile
   160 make test
   161 ~~~