From 8f816dafb7014337743a003870c98189d7ba0f19 Mon Sep 17 00:00:00 2001
From: heck <heck@pep.foundation>
Date: Thu, 5 Nov 2020 18:00:41 +0100
Subject: [PATCH] overhaul install instructions

---
 docs/source/install.rst | 93 +++++++++++++++++++----------------------
 1 file changed, 42 insertions(+), 51 deletions(-)

diff --git a/docs/source/install.rst b/docs/source/install.rst
index 2670f4a..9c25ad8 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -3,79 +3,70 @@ Installation
 
 Requirements
 ------------
+In order to build, use or install this extension module, you need to have some
+system dependencies already installed:
 
-[Sequoia](https://gitlab.com/sequoia-pgp/sequoia)
-[pEpEngine](https://pep.foundation/dev/repos/pEpEngine/)
-[libpEpAdapter](https://pep.foundation/dev/repos/libpEpAdapter/)
+* pEp-base (sequoia, libetpan, asn1c, yml2, pEpEngine, libpEpAdapter)
+* boost-python
 
-## Build Instructions
+These `build instructions <https://dev.pep.foundation/Common%20Adapter%20Documentation/Adapter_Build_Instructions>`_ will get you all setup.
 
-To install all the dependencies, referer to their respective documentation.
+Additionally, there is a `build script <http://pep-security.lu/gitlab/juga/Internal-Deployment/-/blob/master/build-pep-stack.sh>`_
+that executes these build instructions automatically (Debian and MacOS):
 
-These build instructions should work on:
- * Linux (Verified 26.4.20 - heck)
- * MacOS (Verified 26.4.20 - heck)
- * Windows
+.. Note:: If you dont install pEp-base system wide, but under a prefix, like /home/foo/local/
+   you will need to have LD_LIBARY_PATH/DYLD_LIBRARY_PATH adjusted for all the following operations.
 
-### Build
-To build against system wide pEp installation (libs/includes)
-```bash
-python3 setup.py build_ext
-```
 
-To build against a pEp installation in your home dir (libs/includes):
-```bash
-python3 setup.py build_ext --local
-```
+Build
+-----
+The pEpPythonAdapter is a python extension module that contains C/C++ code that needs to be
+compiled first. So, before any use or installation, the module needs to be built.
 
-To build against a pEp installation in a custom installation root (libs/includes)
-```bash
-python3 setup.py build_ext --prefix=<path_to_your_install_root>
-```
+Build config
+~~~~~~~~~~~~
+Create a local build config by creating a 'local.conf' file. There is a 'local.conf.example' describing
+all the build options. You can use this as a template.
 
-Installation in all platforms
------------------------------
+``cp local.conf.example local.conf``
 
-It is possible to install `pEpPythonAdapter` without building it first, since
-the installation process will build it when it has not been built yet, but you
-need to have all the dependencies already installed.
 
+If you have pEp-base installed under a custom prefix (e.g. /home/foo/local) it is important
+that you specify "PREFIX".
+
+Build
+~~~~~
+To build the module just type:
+
+``make``
+
+Installation
+------------
 You can install this adapter in the in the following ways:
 
-To install the extension module system wide, as root, run:
-```bash
-python3 setup.py install
-```
+To install the extension module system wide or into a venv:
 
-To install the extension module into you home dir
-```bash
-python3 setup.py install --user
-```
+``make install``
+
+
+To install the extension module into you home dir:
+
+``make install-user``
 
-To install the extension module into a custom destination
-```bash
-python3 setup.py install --prefix=<custom_destination_root>
-```
-Attention: The ~ (tilde) does not get expanded, but env vars work ($HOME).
 
 If you're working on different Python projects, it's recommended to use
-[virtualenv](https://virtualenv.pypa.io/en/stable/) to have different
+`virtualenv <https://virtualenv.pypa.io/en/stable/>`_ to have different
 libraries versions.
 
 If you're working in a virtualenv you can also install the package with
-`pip install .`
-
-To install the package in "develop mode", run `python setup.py develop`
-or `pip install -e .`
+``pip install .``
 
-Debian installation
---------------------
+To install the package in "develop mode", run ``python setup.py develop``
+or ``pip install -e .``
 
-You can also install the dependencies using the scripts
-http://pep-security.lu/gitlab/juga/Internal-Deployment/-/blob/master/install-sys-deps-debian.sh
-and
-http://pep-security.lu/gitlab/juga/Internal-Deployment/-/blob/master/build-pep-stack.sh
 
+Docker
+------
 If you know how to use docker, you can avoid having to install all
 the dependencies using the image
 https://registry.gitlab.com/juga0/pepdocker/peppythonadapter.