Removing rancid doc files. If we have build instructions, we have a responsibility to keep them up to date. If not, they're more dangerous than they're worth.
authorKrista 'DarthMama' Bennett <krista@pep.foundation>
Wed, 20 May 2020 12:26:22 +0200
changeset 47136a2d68d3e7db
parent 4710 ba4371f179e1
child 4715 7ca8b7b08a8a
child 4718 a6c15bc68c47
Removing rancid doc files. If we have build instructions, we have a responsibility to keep them up to date. If not, they're more dangerous than they're worth.
doc/build-macos.md
doc/build-netpgp.md
doc/readme.md
doc/testing.md
     1.1 --- a/doc/build-macos.md	Wed May 20 00:45:39 2020 +0200
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,161 +0,0 @@
     1.4 -<!-- Copyright 2015-2017, pEp foundation, Switzerland
     1.5 -This file is part of the pEp Engine
     1.6 -This file may be used under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) License
     1.7 -See CC_BY-SA.txt -->
     1.8 -
     1.9 -# Build instructions for macOS Sierra
    1.10 -
    1.11 -# Installing packaged dependencies
    1.12 -You will find instructions for using either Macports or Homebrew below to install the compile-time dependencies.
    1.13 -
    1.14 -## MacPorts
    1.15 -Install MacPorts according to the instructions found [here](https://www.macports.org/install.php).
    1.16 -Ensure that Macports' binary paths (`/opt/local/bin` and `/opt/local/sbin`) are in your `PATH` environment variable.
    1.17 -
    1.18 -~~~
    1.19 -# general
    1.20 -sudo port install mercurial
    1.21 -# YML2
    1.22 -sudo port install py27-lxml
    1.23 -# libetpan
    1.24 -sudo port install git autoconf automake libtool
    1.25 -# asn1c
    1.26 -sudo port install asn1c
    1.27 -# engine
    1.28 -sudo port install gpgme
    1.29 -~~~
    1.30 -
    1.31 -Ensure that `python` is Python 2.7:
    1.32 -
    1.33 -~~~
    1.34 -sudo port select python python27
    1.35 -~~~
    1.36 -
    1.37 -## Homebrew
    1.38 -Install Homebrew according to the instructions found [here](https://docs.brew.sh/Installation.html).
    1.39 -Ensure that Homebrew's binary path (`/usr/local/bin`) is in your `PATH` environment variable.
    1.40 -
    1.41 -~~~
    1.42 -# general
    1.43 -brew install mercurial
    1.44 -# YML2
    1.45 -# If you don't have pip with your Python 2 distribution, you can install it with brew
    1.46 -brew install python
    1.47 -pip2 install --user lxml
    1.48 -# libetpan
    1.49 -brew install git autoconf automake libtool
    1.50 -# asn1c
    1.51 -brew install asn1c
    1.52 -# engine
    1.53 -brew install gpgme
    1.54 -~~~
    1.55 -
    1.56 -# Installing unpackaged dependencies
    1.57 -## YML2
    1.58 -To check if lxml is properly installed, you can use this lxml "hello world" command:
    1.59 -
    1.60 -~~~
    1.61 -python2 -c 'from lxml import etree; root = etree.Element("root"); print(root.tag)'
    1.62 -~~~
    1.63 -
    1.64 -It should generate the following output:
    1.65 -
    1.66 -~~~
    1.67 -root
    1.68 -~~~
    1.69 -
    1.70 -~~~
    1.71 -mkdir -p ~/code/yml2
    1.72 -hg clone https://pep.foundation/dev/repos/yml2/ ~/code/yml2
    1.73 -~~~
    1.74 -
    1.75 -## libetpan
    1.76 -pEp Engine requires libetpan with a set of patches that have not been upstreamed yet.
    1.77 -
    1.78 -~~~
    1.79 -mkdir -p ~/code/libetpan
    1.80 -git clone https://github.com/fdik/libetpan ~/code/libetpan
    1.81 -cd ~/code/libetpan
    1.82 -mkdir ~/code/libetpan/build
    1.83 -./autogen.sh --prefix="$HOME/code/libetpan/build"
    1.84 -make
    1.85 -make install
    1.86 -~~~
    1.87 -
    1.88 -## GPGME
    1.89 -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.
    1.90 -
    1.91 -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.
    1.92 -
    1.93 -~~~
    1.94 -mkdir -p ~/code/gpgme/build/include
    1.95 -cp /opt/local/include/gpg*.h ~/code/gpgme/build/include
    1.96 -mkdir -p ~/code/gpgme/build/lib
    1.97 -cp -r /opt/local/lib/libgpg* ~/code/gpgme/build/lib
    1.98 -~~~
    1.99 -
   1.100 -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.101 -
   1.102 -# pEp Engine
   1.103 -
   1.104 -~~~
   1.105 -mkdir -p ~/code/pep-engine
   1.106 -hg clone https://pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine
   1.107 -cd ~/code/pep-engine
   1.108 -mkdir ~/code/pep-engine/build
   1.109 -~~~
   1.110 -
   1.111 -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.112 -
   1.113 -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.114 -
   1.115 -For a more detailed explanation of the mechanics of these build configuration files, and overriding defaults, see the comments in `Makefile.conf`.
   1.116 -
   1.117 -Below is a sample `./local.conf` file, for orientation.
   1.118 -
   1.119 -~~~
   1.120 -PREFIX=$(HOME)/code/engine/build
   1.121 -PER_MACHINE_DIRECTORY=$(PREFIX)/share/pEp
   1.122 -
   1.123 -YML2_PATH=$(HOME)/code/yml2
   1.124 -
   1.125 -ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
   1.126 -ETPAN_INC=-I$(HOME)/code/libetpan/build/include
   1.127 -
   1.128 -GPGME_LIB=-L$(HOME)/lib
   1.129 -GPGME_INC=-I$(HOME)/include
   1.130 -~~~
   1.131 -
   1.132 -The engine is built as follows:
   1.133 -
   1.134 -~~~
   1.135 -make all
   1.136 -make db
   1.137 -~~~
   1.138 -
   1.139 -If your build fails with an error message similar to the following:
   1.140 -
   1.141 -~~~
   1.142 -  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 477, in _parse_localename
   1.143 -    raise ValueError, 'unknown locale: %s' % localename
   1.144 -ValueError: unknown locale: UTF-8
   1.145 -~~~
   1.146 -
   1.147 -or any other locale-related Python error, make sure Python does not have any locale-related environment variables set.
   1.148 -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.149 -This is a bug in Python, see [https://bugs.python.org/issue18378#msg215215](https://bugs.python.org/issue18378#msg215215).
   1.150 -
   1.151 -The unit tests can be run without the engine library being installed, however `system.db` must be installed:
   1.152 -
   1.153 -~~~
   1.154 -make -C db install
   1.155 -~~~
   1.156 -
   1.157 -Since `system.db` rarely changes, its installation is not needed for every build.
   1.158 -
   1.159 -Tests can be compiled and executed with the following commands:
   1.160 -
   1.161 -~~~
   1.162 -make -C test compile
   1.163 -make test
   1.164 -~~~
     2.1 --- a/doc/build-netpgp.md	Wed May 20 00:45:39 2020 +0200
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,43 +0,0 @@
     2.4 -# Using NetPGP instead of GnuPG
     2.5 -## Prepare
     2.6 -
     2.7 -Get OpenSSL:
     2.8 -curl -O https://www.openssl.org/source/openssl-1.1.0f.tar.gz
     2.9 -
    2.10 -Build it using the openssl-for-ios build script:
    2.11 -git clone https://github.com/sinofool/build-openssl-ios/ .
    2.12 -
    2.13 -
    2.14 -
    2.15 - and build/install it as shared library.
    2.16 -
    2.17 -```
    2.18 -wget https://www.openssl.org/source/old/1.0.1/openssl-1.0.1u.tar.gz
    2.19 -tar xvfz openssl-1.0.1u.tar.gz
    2.20 -cd openssl-1.0.1u
    2.21 -./Configure darwin64-x86_64-cc --prefix=$HOME shared
    2.22 -make install
    2.23 -```
    2.24 -
    2.25 -Get and autoconf NetPGP
    2.26 -
    2.27 -```
    2.28 -cd $SRC
    2.29 -hg clone https://pep.foundation/dev/repos/netpgp-et/
    2.30 -cd netpgp-et
    2.31 -autoreconf -i
    2.32 -```
    2.33 -
    2.34 -## Build
    2.35 -
    2.36 -Important : LDFLAGS is set to help finding OpenSSL shared lib. If not set,
    2.37 -system's default libcrypto may silently be used instead, causing memory
    2.38 -corruption or crash at runtime.
    2.39 -
    2.40 -```
    2.41 -mkdir netpgp_debug
    2.42 -cd netpgp_debug
    2.43 -$SRC/netpgp-et/configure --with-openssl=$HOME --prefix=$HOME CPPFLAGS=-DDEBUG CXXFLAGS="-g -O0" LDFLAGS="-L${HOME}/lib"
    2.44 -make
    2.45 -make install
    2.46 -```
     3.1 --- a/doc/readme.md	Wed May 20 00:45:39 2020 +0200
     3.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.3 @@ -1,58 +0,0 @@
     3.4 -<!-- Copyright 2015-2017, pEp foundation, Switzerland
     3.5 -This file is part of the pEp Engine
     3.6 -This file may be used under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) License
     3.7 -See CC_BY-SA.txt -->
     3.8 -
     3.9 -# Information about the pEp Engine
    3.10 -
    3.11 -# Dependencies
    3.12 -The p≡p Engine depends on the following projects:
    3.13 -
    3.14 -- run-time dependencies
    3.15 -  - One of the following OpenPGP implementations:
    3.16 -    - GnuPG version 2.1.17 or later with GPGME (at least version 1.7.0) [https://gnupg.org/](https://gnupg.org/)
    3.17 -    - For platforms not supporting pinentry (e.g. Android) - GnuPG version 2.0.30 with GPGME version 1.6.0 (or later) [https://gnupg.org/](https://gnupg.org/)
    3.18 -    - a fork of NetPGP, [https://pep.foundation/dev/repos/netpgp-et/](https://pep.foundation/dev/repos/netpgp-et/)
    3.19 -    - Sequoia, which in turn requires:
    3.20 -      - Rust
    3.21 -      - libnettle
    3.22 -  - One of the following MIME libraries:
    3.23 -    - a fork of libetpan, [https://github.com/fdik/libetpan](https://github.com/fdik/libetpan)
    3.24 -    - pEpMIME
    3.25 -  - zlib, [http://zlib.net/](http://zlib.net/)
    3.26 -  - libcurl (Only with NetPGP), [https://curl.haxx.se/libcurl/](https://curl.haxx.se/libcurl/)
    3.27 -  - libuuid, [https://www.kernel.org/pub/linux/utils/util-linux/](https://www.kernel.org/pub/linux/utils/util-linux/)
    3.28 -  - SQLite, [https://sqlite.org](https://sqlite.org)
    3.29 -  - OpenSSL (Only with NetPGP), [https://www.openssl.org](https://www.openssl.org)
    3.30 -- compile-time dependencies
    3.31 -  - asn1c (version v0.9.28), [http://lionet.info/asn1c/blog/](http://lionet.info/asn1c/blog/)
    3.32 -  - yml2, [https://fdik.org/yml//toolchain](https://fdik.org/yml//toolchain)
    3.33 -    - Python 3
    3.34 -    - LXML
    3.35 -  - One of the following build systems:
    3.36 -    - GNU make (on Linux and macOS)
    3.37 -    - MSBuild distributed with Microsoft Visual Studio 2015 (on Windows)
    3.38 -  - One of the following compilers for C and C++:
    3.39 -    - GNU GCC (on Linux)
    3.40 -    - Apple "clang" LLVM (on MacOS)
    3.41 -    - Microsoft MSVC/MSVC++ distributed with Microsoft Visual Studio 2015 (on Windows)
    3.42 -  - A script for compiling OpenSSL for iOS, [https://github.com/sinofool/build-openssl-ios/](https://github.com/sinofool/build-openssl-ios/)
    3.43 -  - binutils
    3.44 -
    3.45 -# The pEp Engine's databases
    3.46 -The p≡p Engine uses two databases:
    3.47 -
    3.48 -- the management database
    3.49 -  - `~/.pEp_management` on \*NIX
    3.50 -  - `%LOCALAPPDATA%\pEp\management.db` on Windows
    3.51 -- the Trustword database
    3.52 -  - `/usr/local/share/system.db` on \*NIX
    3.53 -  - `%ALLUSERSPROFILE%\pEp\system.db` on Windows
    3.54 -
    3.55 -The management db is created by the first call of `init()` of p≡p Engine.
    3.56 -It does not need to be created manually.
    3.57 -`system.db` is created by using the DDL in `db/create_system_db.sql`; the database content is created by `db/dic2csv.py` out of hunspell's dictionary packages (or something similar) and then imported using `sqlite3`'s `.import` command.
    3.58 -Dictionary files for different languages are part of the p≡p Engine source distribution.
    3.59 -
    3.60 -You can test the Trustwords in `system.db` using `db/trustwords.py`.
    3.61 -Both Python tools have a `--help` switch.
     4.1 --- a/doc/testing.md	Wed May 20 00:45:39 2020 +0200
     4.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.3 @@ -1,2 +0,0 @@
     4.4 -# Testing
     4.5 -For the documentation of the tests, see `test/README.md`