buff
/
pEpEngine
forked from pEp.foundation/pEpEngine
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Clean up doc/readme.md, Linux- and macOS-specific instructions

Browse Source
doc_update_sequoia
Damiano Boppart 6 years ago
parent 945f478934
commit 51dabe081c
6 changed files with 315 additions and 239 deletions
Show Stats Download Patch File Download Diff File

137
doc/README-OSX.md
Unescape Escape View File

@ -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`.

102
doc/README.txt
Unescape Escape View File

@ -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

111
doc/build-debian.md
Unescape Escape View File

@ -0,0 +1,111 @@
<!-- Copyright 2015-2017, pEp foundation, Switzerland
This file is part of the pEp Engine
This file may be used under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) License
See CC_BY-SA.txt -->
# 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
~~~

35
doc/build-ios.md
Unescape Escape View File

@ -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
```

125
doc/build-macos.md
Unescape Escape View File

@ -0,0 +1,125 @@
<!-- Copyright 2015-2017, pEp foundation, Switzerland
This file is part of the pEp Engine
This file may be used under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) License
See CC_BY-SA.txt -->
# 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
~~~

44
doc/readme.md
Unescape Escape View File

@ -0,0 +1,44 @@
<!-- Copyright 2015-2017, pEp foundation, Switzerland
This file is part of the pEp Engine
This file may be used under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) License
See CC_BY-SA.txt -->
# 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.
Write Preview
Loading…
Cancel
Save