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