From 51dabe081c71f5c328268a8a128798f41733986f Mon Sep 17 00:00:00 2001 From: Damiano Boppart Date: Tue, 29 Aug 2017 00:25:54 +0200 Subject: [PATCH] Clean up doc/readme.md, Linux- and macOS-specific instructions --- doc/README-OSX.md | 137 -------------------------------------------- doc/README.txt | 102 --------------------------------- doc/build-debian.md | 111 +++++++++++++++++++++++++++++++++++ doc/build-ios.md | 35 +++++++++++ doc/build-macos.md | 125 ++++++++++++++++++++++++++++++++++++++++ doc/readme.md | 44 ++++++++++++++ 6 files changed, 315 insertions(+), 239 deletions(-) delete mode 100644 doc/README-OSX.md delete mode 100644 doc/README.txt create mode 100644 doc/build-debian.md create mode 100644 doc/build-ios.md create mode 100644 doc/build-macos.md create mode 100644 doc/readme.md diff --git a/doc/README-OSX.md b/doc/README-OSX.md deleted file mode 100644 index b8d1d4fbf..000000000 --- a/doc/README-OSX.md +++ /dev/null @@ -1,137 +0,0 @@ -This file is under Creative Commons License 3.0 cc-by-sa - -# Building for OS X/macOS -See also README.txt for general information. - -For compiling pEp Engine and its dependencies, make sure you have the LANG variable set. Some source files contain unicode characters, and python (assuming files are ascii) will fail. - -``` -export LANG=en_US.UTF-8 -``` - -## Dependencies - -### MacPorts -[Install MacPorts](https://www.macports.org/install.php) for your version of OS X/macOS. - -If MacPorts is already installed on your machine, but was installed by a different user, make sure your `PATH` variable is set as follows in `~/.profile`: - -``` -export PATH="/opt/local/bin:/opt/local/sbin:$PATH" -``` - -Install dependencies packaged with MacPorts as follows. - -``` -sudo port install mercurial py27-lxml gpgme autoconf automake libtool asn1c zlib openssl libiconv cyrus-sasl2 -``` - -Make sure that `python` is a version 2 one: - -``` -sudo port select python python27 -``` - -### NetPGP (if not GPGME) - -#### Prepare : - -Get OpenSSL and build/install it as shared library. - -``` -wget https://www.openssl.org/source/old/1.0.1/openssl-1.0.1u.tar.gz -tar xvfz openssl-1.0.1u.tar.gz -cd openssl-1.0.1u -./Configure darwin64-x86_64-cc --prefix=$HOME shared -make install -``` - -Get and autoconf NetPGP - -``` -cd $SRC -hg clone https://cacert.pep.foundation/dev/repos/netpgp-et/ -cd netpgp-et -autoreconf -i -``` - -#### Build - -Important : LDFLAGS is set to help finding OpenSSL shared lib. If not set, -system's default libcrypto may silently be used instead, causing memory -corruption or crash at runtime. - -``` -mkdir netpgp_debug -cd netpgp_debug -$SRC/netpgp-et/configure --with-openssl=$HOME --prefix=$HOME CPPFLAGS=-DDEBUG CXXFLAGS="-g -O0" LDFLAGS="-L${HOME}/lib" -make -make install -``` - -### Other Dependecies - -#### [yml2](https://fdik.org/yml/toolchain) -Install into your home directory: - -``` -pushd ~ -hg clone https://cacert.pep.foundation/dev/repos/yml2/ -popd -``` - -#### libetpan - -Note: libetpan needs libz and libiconv, but the libiconv from MacPorts is not compatible, some -functions seem to have been renamed there. Therefore the dynlib from OS X is used. - -``` -git clone https://github.com/fdik/libetpan -cd libetpan -./autogen.sh --prefix "$HOME" -make -make install -``` - -## Building pEp Engine - -### Configuration -You can change some defaults by editing `Makefile.conf`. The following variable needs to be set appropriately: - -``` -LIBGPGME=/opt/local/lib/libgpgme.11.dylib -``` - -### Build - -``` -make clean -make all -make db -``` - -### Installation - -``` -make install -sudo make -C db install -``` - -Since the `system.db` rarely changes, the last step is not needed for every build. If you would like to be able to install the engine without `sudo`, ensure that your user can write the file `/usr/local/share/pEp/system.db`. This is not recommended for production machines. - -### Run tests - -If you installed the test keys in your keyring (see: README.txt), this should just work: - -``` -cd test -make test -``` - -# Building for iOS - -This is done with Xcode. Simply add `pEpEngine.xcodeproj` to -your project and add a dependency to the target `pEpEngine` -(in `Target Dependencies` in your `Build Phases`. - -Usually you just integrate `pEpiOSAdapter.xcodeproj`. diff --git a/doc/README.txt b/doc/README.txt deleted file mode 100644 index 338f3870f..000000000 --- a/doc/README.txt +++ /dev/null @@ -1,102 +0,0 @@ -# this file is under Creative Commons License 3.0 cc-by-sa - -1. Dependencies ---------------- - -p≡p engine is depending on the following FOSS libraries: - -* a fork of libetpan, see https://github.com/fdik/libetpan - git clone https://github.com/fdik/libetpan - -* zlib, see http://zlib.net/ -Oh yeah? Where? - -* OpenSSL, see http://openssl.org/ -Oh yeah? Where? - -* iconv, see http://www.gnu.org/software/libiconv/ - -* Cyrus SASL, see http://cyrusimap.org/ -Oh yeah? Where? - -* One of the following OpenPGP implementations: - * GnuPG via GPGME, version 1.6.0 or newer, see https://gnupg.org/ - * NetPGP/p≡p, see https://cacert.pep.foundation/dev/repos/netpgp-et/ - -* libcurl -Maybe on iOS? - -SQlite3 - - - - -compile-time dependencies: - -* Asn1c, download from https://lionet.info/soft/asn1c-0.9.27.tar.gz . Debian 8's v0.9.24 does not work. Debian 9's v0.9.27 generates non-POSIX code, that will cause issues when the engine is compiled with '-std=c99'. Thus, use v0.9.28 for best results. - -* yml2, which needs lxml (where to get?) - -* One of the following build systems - * GNU make - * Visual Studio 2015 - - -2. Building p≡p engine ----------------------- - -p≡p engine has an old style Makefile for building it. - -The build is configured in Makefile.conf - -It supports the common targets - -$ make all -$ make install -$ make clean - -and additionally - -$ make package # for building a .tar.bz2 with the source distribution - -On Windows, use Visual Studio. - - -3. How to cross-build ---------------------- - -For cross-building, BUILD_FOR is being used. I.e.: - -$ BUILD_FOR=yourOS make -e - - -4. How to build the databases ------------------------------ - -p≡p Engine uses two databases: ~/.pEp_management (on *NIX) or -%LOCALAPPDATA%\pEp\management.db on Windoze respectively, and -/usr/local/share/system.db on *NIX or %ALLUSERSPROFILE%\pEp\system.db -respectively. The latter contains the Trustwords dbs. - -The managment db is being created by the first call of init() of p≡p Engine. It -does not need to be created manually. system.db is being created by using the -DDL in db/create_system_db.sql – the content is created by db/dic2csv.py -out of hunspell's dictionary packages (or something similar) and then being -imported using sqlite3's .import command. Dictionary files for different -languages are part of p≡p engine source distribution. - -$ make db -$ make -C db install - -You can test the Trustwords in system.db using db/trustwords.py -Both Python tools have a switch --help - - -5. How to run the tests ------------------------ - -You have to import all the test keys into your local gpg instance: - - cd test - cat 0x*.asc *_sec.asc| gpg --import - diff --git a/doc/build-debian.md b/doc/build-debian.md new file mode 100644 index 000000000..7018352d3 --- /dev/null +++ b/doc/build-debian.md @@ -0,0 +1,111 @@ + + +# Build instructions for Debian 9 + +# Installing packaged dependencies + +~~~ +# general +apt install -y ca-cacert mercurial +# YML2 +apt install -y python-lxml +# libetpan +apt install -y git build-essential automake libtool +# asn1c +apt install -y git build-essential automake libtool +# engine +apt install -y uuid-dev libgpgme11-dev libsqlite3-dev sqlite3 +~~~ + +# Installing unpackaged dependencies +## YML2 + +~~~ +mkdir -p ~/code/yml2 +hg clone https://cacert.pep.foundation/dev/repos/yml2/ ~/code/yml2 +~~~ + +## libetpan +pEp Engine requires libetpan with a set of patches that have not been upstreamed yet. + +~~~ +mkdir -p ~/code/libetpan +git clone https://github.com/fdik/libetpan ~/code/libetpan +cd ~/code/libetpan +mkdir ~/code/libetpan/build +./autogen.sh --prefix="$HOME/code/libetpan/build" +make +make install +~~~ + +## asn1c + +~~~ +mkdir -p ~/code/asn1c +git clone git://github.com/vlm/asn1c.git ~/code/asn1c +cd ~/code/asn1c +git checkout tags/v0.9.28 -b pep-engine +autoreconf -iv +mkdir ~/code/asn1c/build +./configure --prefix="$HOME/code/asn1c/build" +make +make install +~~~ + +# pEp Engine + +~~~ +mkdir -p ~/code/pep-engine +hg clone https://cacert.pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine +cd ~/code/pep-engine +mkdir ~/code/pep-engine/build +~~~ + +For an explanation of the mechanics of `PLATFORM_OVERRIDE`, see the inline comments in `Makefile.conf`. +In this guide, the platform-specific configuration will be called `local`. +The installation directory will be a subdirectory of the repository. +This is useful for testing only. + +~~~ +export PLATFORM_OVERRIDE=local +~~~ + +`./build-config/local.conf`: + +~~~ +PREFIX=$(HOME)/code/pep-engine/build +SYSTEM_DB=$(PREFIX)/share/pEp/system.db + +YML2_PATH=$(HOME)/code/yml2 + +ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib +ETPAN_INC=-I$(HOME)/code/libetpan/build/include + +ASN1C=$(HOME)/code/asn1c/build/bin/asn1c +ASN1C_INC=-I$(HOME)/code/asn1c/build/share +~~~ + +The engine is built as follows: + +~~~ +make all +make db +~~~ + +The unit tests can be run without the engine library being installed, however the `system.db` must be installed: + +~~~ +make -C db install +~~~ + +Since `system.db` rarely changes, its installation is not needed for every build. + +Tests can be compiled and executed with the following commands: + +~~~ +make -C test compile +make test +~~~ diff --git a/doc/build-ios.md b/doc/build-ios.md new file mode 100644 index 000000000..91ac9bdb4 --- /dev/null +++ b/doc/build-ios.md @@ -0,0 +1,35 @@ +# Using NetPGP instead of GnuPG +## Prepare + +Get OpenSSL and build/install it as shared library. + +``` +wget https://www.openssl.org/source/old/1.0.1/openssl-1.0.1u.tar.gz +tar xvfz openssl-1.0.1u.tar.gz +cd openssl-1.0.1u +./Configure darwin64-x86_64-cc --prefix=$HOME shared +make install +``` + +Get and autoconf NetPGP + +``` +cd $SRC +hg clone https://cacert.pep.foundation/dev/repos/netpgp-et/ +cd netpgp-et +autoreconf -i +``` + +## Build + +Important : LDFLAGS is set to help finding OpenSSL shared lib. If not set, +system's default libcrypto may silently be used instead, causing memory +corruption or crash at runtime. + +``` +mkdir netpgp_debug +cd netpgp_debug +$SRC/netpgp-et/configure --with-openssl=$HOME --prefix=$HOME CPPFLAGS=-DDEBUG CXXFLAGS="-g -O0" LDFLAGS="-L${HOME}/lib" +make +make install +``` diff --git a/doc/build-macos.md b/doc/build-macos.md new file mode 100644 index 000000000..6e9967def --- /dev/null +++ b/doc/build-macos.md @@ -0,0 +1,125 @@ + + +# Build instructions for macOS Sierra and iOS + +# Installing packaged dependencies + +## MacPorts + +MacPorts is needed to install some compile-time dependencies. +Install MacPorts according to the instructions found [here](https://www.macports.org/install.php). +Ensure that Macports' binary paths (`/opt/local/bin` and `/opt/local/sbin`) are in your `PATH` environment variable. + +~~~ +# general +sudo port install mercurial +# YML2 +sudo port install py27-lxml +# libetpan +sudo port install git autoconf automake libtool +# asn1c +sudo port install asn1c +# engine +sudo port install gpgme +~~~ + +FIXME Are `zlib openssl cyrus-sasl2` needed? They were in an older revision of the instructions + +Ensure that `python` is Python 2.7: + +~~~ +sudo port select python python27 +~~~ + +# Installing unpackaged dependencies +## YML2 + +~~~ +mkdir -p ~/code/yml2 +hg clone https://cacert.pep.foundation/dev/repos/yml2/ ~/code/yml2 +~~~ + +## libetpan +pEp Engine requires libetpan with a set of patches that have not been upstreamed yet. + +~~~ +mkdir -p ~/code/libetpan +git clone https://github.com/fdik/libetpan ~/code/libetpan +cd ~/code/libetpan +mkdir ~/code/libetpan/build +./autogen.sh --prefix="$HOME/code/libetpan/build" +make +make install +~~~ + +## GPGME +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. + +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. + +~~~ +mkdir -p ~/code/gpgme/build/include +cp /opt/local/include/gpg*.h ~/code/gpgme/build/include +mkdir -p ~/code/gpgme/build/lib +cp -r /opt/local/lib/libgpg* ~/code/gpgme/build/lib +~~~ + +It's of course possible to skip MacPort's version, and use a self-compiled GPGME/GPG. + +# pEp Engine + +~~~ +mkdir -p ~/code/pep-engine +hg clone https://cacert.pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine +cd ~/code/pep-engine +mkdir ~/code/pep-engine/build +~~~ + +For an explanation of the mechanics of `PLATFORM_OVERRIDE`, see the inline comments in `Makefile.conf`. +In this guide, the platform-specific configuration will be called `local`. +The installation directory will be a subdirectory of the repository. +This is useful for testing only. + +~~~ +export PLATFORM_OVERRIDE=local +~~~ + +`./build-config/local.conf`: + +~~~ +PREFIX=$(HOME)/code/pep-engine/build +SYSTEM_DB=$(PREFIX)/share/pEp/system.db + +YML2_PATH=$(HOME)/code/yml2 + +ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib +ETPAN_INC=-I$(HOME)/code/libetpan/build/include + +GPGME_LIB=-L$(HOME)/code/gpgme/build/lib +GPGME_INC=-I$(HOME)/code/gpgme/build/include +~~~ + +The engine is built as follows: + +~~~ +make all +make db +~~~ + +The unit tests can be run without the engine library being installed, however the `system.db` must be installed: + +~~~ +make -C db install +~~~ + +Since `system.db` rarely changes, its installation is not needed for every build. + +Tests can be compiled and executed with the following commands: + +~~~ +make -C test compile +make test +~~~ diff --git a/doc/readme.md b/doc/readme.md new file mode 100644 index 000000000..89e4b569c --- /dev/null +++ b/doc/readme.md @@ -0,0 +1,44 @@ + + +# Information about the pEp Engine + +# Dependencies +The p≡p Engine depends on the following projects: + +- run-time dependencies + - One of the following OpenPGP implementations: + - GnuPG (version 2.0.30 or 2.1.16 or newer) by way of GPGME (version 1.6.0 or newer) [https://gnupg.org/](https://gnupg.org/) + - a fork of NetPGP, [https://cacert.pep.foundation/dev/repos/netpgp-et/](https://cacert.pep.foundation/dev/repos/netpgp-et/) + - a fork of libetpan, [https://github.com/fdik/libetpan](https://github.com/fdik/libetpan) + - zlib (Oh yeah, where?), [http://zlib.net/](http://zlib.net/) + - OpenSSL (Oh yeah, where?), [https://www.openssl.org](https://www.openssl.org) + - Cyrus SASL (Oh yeah, where?), [https://www.cyrusimap.org](https://www.cyrusimap.org) + - libcurl (Oh yeah, where?), [https://curl.haxx.se/libcurl/](https://curl.haxx.se/libcurl/) + - libuuid, [https://www.kernel.org/pub/linux/utils/util-linux/](https://www.kernel.org/pub/linux/utils/util-linux/) + - SQLite, [https://sqlite.org](https://sqlite.org) +- compile-time dependencies + - asn1c (version v0.9.28), [http://lionet.info/asn1c/blog/](http://lionet.info/asn1c/blog/) + - yml2, [https://fdik.org/yml//toolchain](https://fdik.org/yml//toolchain) + - One of the following build systems: + - GNU make (on Linux and macOS) + - MSBuild distributed with Microsoft Visual Studio 2015 (on Windows) + - One of the following compilers for C and C++: + - GNU GCC (on Linux) + - Apple "clang" LLVM (on MacOS) + - Microsoft MSVC/MSVC++ distributed with Microsoft Visual Studio 2015 (on Windows) + +# The pEp Engine's databases +The p≡p Engine uses two databases: +`~/.pEp_management` (on *NIX) or `%LOCALAPPDATA%\pEp\management.db` on Windows, and `/usr/local/share/system.db` (on *NIX) or `%ALLUSERSPROFILE%\pEp\system.db`. +The latter contains the Trustwords databases. + +The management db is created by the first call of init() of p≡p Engine. +It does not need to be created manually. +`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. +Dictionary files for different languages are part of the p≡p Engine source distribution. + +You can test the Trustwords in `system.db` using `db/trustwords.py`. +Both Python tools have a `--help` switch. \ No newline at end of file