Update macos build instructions ENGINE-544
authorDamiano Boppart <damiano.boppart@pep.security>
Tue, 14 May 2019 18:59:27 +0200
branchENGINE-544
changeset 404295d078590008
parent 3677 51c4944d6257
Update macos build instructions
doc/build-macos.md
     1.1 --- a/doc/build-macos.md	Tue May 14 18:40:26 2019 +0200
     1.2 +++ b/doc/build-macos.md	Tue May 14 18:59:27 2019 +0200
     1.3 @@ -5,6 +5,7 @@
     1.4  
     1.5  # Build instructions for macOS Sierra
     1.6  
     1.7 +
     1.8  # Installing packaged dependencies
     1.9  You will find instructions for using either Macports or Homebrew below to install the compile-time dependencies.
    1.10  
    1.11 @@ -25,12 +26,6 @@
    1.12  sudo port install gpgme
    1.13  ~~~
    1.14  
    1.15 -Ensure that `python` is Python 2.7:
    1.16 -
    1.17 -~~~
    1.18 -sudo port select python python27
    1.19 -~~~
    1.20 -
    1.21  ## Homebrew
    1.22  Install Homebrew according to the instructions found [here](https://docs.brew.sh/Installation.html).
    1.23  Ensure that Homebrew's binary path (`/usr/local/bin`) is in your `PATH` environment variable.
    1.24 @@ -50,9 +45,10 @@
    1.25  brew install gpgme
    1.26  ~~~
    1.27  
    1.28 +
    1.29  # Installing unpackaged dependencies
    1.30  ## YML2
    1.31 -To check if lxml is properly installed, you can use this lxml "hello world" command:
    1.32 +To check if lxml (a dependency of YML2) is properly installed for a given python interpreter, you can use this lxml "hello world" command:
    1.33  
    1.34  ~~~
    1.35  python2 -c 'from lxml import etree; root = etree.Element("root"); print(root.tag)'
    1.36 @@ -64,6 +60,8 @@
    1.37  root
    1.38  ~~~
    1.39  
    1.40 +If you have used the Macports instructions from above to install your dependencies, you will want to use `/opt/local/bin/python2` instead of `python2` as your python interpreter. See also the setting of `YML2_PROC` below, you will need to select the appropriate python interpreter there.
    1.41 +
    1.42  ~~~
    1.43  mkdir -p ~/code/yml2
    1.44  hg clone https://pep.foundation/dev/repos/yml2/ ~/code/yml2
    1.45 @@ -94,10 +92,10 @@
    1.46  cp -r /opt/local/lib/libgpg* ~/code/gpgme/build/lib
    1.47  ~~~
    1.48  
    1.49 -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.
    1.50 +It is of course possible to use a self-compiled GPGME/GPG instead of the Macports version.
    1.51 +
    1.52  
    1.53  # pEp Engine
    1.54 -
    1.55  ~~~
    1.56  mkdir -p ~/code/pep-engine
    1.57  hg clone https://pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine
    1.58 @@ -105,11 +103,13 @@
    1.59  mkdir ~/code/pep-engine/build
    1.60  ~~~
    1.61  
    1.62 -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`.
    1.63 +You can change the parameters of the build by assigning non-default values to certain `make` variables.
    1.64 +All variables that you can safely change are documented in `/Makefile.conf`. The default values are also given in this file.
    1.65 +You may edit these variables directly in `/Makefile.conf`, or you can create a `/local.conf` containing `make` variable assignments -- both methods work in the same manner.
    1.66  
    1.67 -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.
    1.68 +If a dependency is not found in your system's default include or library paths, you will have to specify the according paths in the appropriate `make` variable. Typically, this has to be done at least for YML2, and libetpan.
    1.69  
    1.70 -For a more detailed explanation of the mechanics of these build configuration files, and overriding defaults, see the comments in `Makefile.conf`.
    1.71 +For a more detailed explanation of the mechanics of these build configuration files, and overriding defaults, see the comments in `/Makefile.conf`.
    1.72  
    1.73  Below is a sample `./local.conf` file, for orientation.
    1.74  
    1.75 @@ -118,21 +118,28 @@
    1.76  SYSTEM_DB=$(PREFIX)/share/pEp/system.db
    1.77  
    1.78  YML2_PATH=$(HOME)/code/yml2
    1.79 +YML2_PROC=/opt/local/bin/python2 $(YML2_PATH)/yml2proc $(YML2_OPTS)
    1.80  
    1.81  ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
    1.82  ETPAN_INC=-I$(HOME)/code/libetpan/build/include
    1.83  
    1.84 -GPGME_LIB=-L$(HOME)/lib
    1.85 -GPGME_INC=-I$(HOME)/include
    1.86 +GPGME_LIB=-L$(HOME)/code/gpgme/build/lib
    1.87 +GPGME_INC=-I$(HOME)/code/gpgme/build/include
    1.88 +
    1.89 +CPPUNIT_LIB=-L$(HOME)/code/cpptest/build/lib
    1.90 +CPPUNIT_INC=-I$(HOME)/code/cpptest/build/include
    1.91  ~~~
    1.92  
    1.93  The engine is built as follows:
    1.94  
    1.95  ~~~
    1.96  make all
    1.97 -make db
    1.98 +make install
    1.99  ~~~
   1.100  
   1.101 +A hand full of other build targets following the sematics of the GNU Build System are also available.
   1.102 +
   1.103 +## Troubleshooting
   1.104  If your build fails with an error message similar to the following:
   1.105  
   1.106  ~~~
   1.107 @@ -145,7 +152,8 @@
   1.108  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.
   1.109  This is a bug in Python, see [https://bugs.python.org/issue18378#msg215215](https://bugs.python.org/issue18378#msg215215).
   1.110  
   1.111 -The unit tests can be run without the engine library being installed, however `system.db` must be installed:
   1.112 +## Testing
   1.113 +The unit tests can be run without the engine library being installed, however `system.db` must be installed. Install it like this:
   1.114  
   1.115  ~~~
   1.116  make -C db install
   1.117 @@ -156,6 +164,5 @@
   1.118  Tests can be compiled and executed with the following commands:
   1.119  
   1.120  ~~~
   1.121 -make -C test compile
   1.122 -make test
   1.123 +make check
   1.124  ~~~