Browse Source

improve build system documentation

master
Luca Saiu 1 month ago
parent
commit
1bd8d6c503
2 changed files with 132 additions and 43 deletions
  1. +67
    -29
      doc/build-debian.md
  2. +65
    -14
      test/README.md

+ 67
- 29
doc/build-debian.md View File

@ -1,43 +1,56 @@
<!-- Copyright 2015-2017, pEp foundation, Switzerland
<!-- Copyright 2015-2021, 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
# Build instructions for Debian 9 and 10
We assume the user keeps sources under `~/pep-src`. There is no single
installation prefix: each package is built, or when supported installed, in
either its source directory or in a subdirectory of its source directory.
Rationale: we do not pollute the user system, uninstalling is trivial.
This is Unix: we assume no spaces in user names.
~~~
mkdir -p ~/pep-src
~~~
# Installing packaged dependencies
~~~
# general
apt install -y mercurial
# YML2
apt install -y python-lxml
apt install -y git
# libetpan
apt install -y git build-essential automake libtool
# asn1c
apt install -y git build-essential automake libtool autoconf
# sequoia
apt install git rustc cargo clang libclang-dev make pkg-config nettle-dev libssl-dev capnproto libsqlite3-dev
# engine
apt install -y uuid-dev libgpgme-dev libsqlite3-dev sqlite3
# optional: developer documentation
apt install -y doxygen pandoc
~~~
# Installing unpackaged dependencies
## YML2
~~~
mkdir -p ~/code/yml2
git clone https://gitea.pep.foundation/fdik/yml2.git ~/code/yml2
mkdir -p ~/pep-src/yml2
git clone https://gitea.pep.foundation/fdik/yml2.git ~/pep-src/yml2
~~~
## libetpan
pEp Engine requires libetpan with a set of patches that have not been upstreamed yet.
~~~
mkdir -p ~/code/libetpan
mkdir -p ~/pep-src/libetpan
git clone https://gitea.pep.foundation/pEp.foundation/libetpan.git ~/code/libetpan
cd ~/code/libetpan
mkdir ~/code/libetpan/build
./autogen.sh --prefix="$HOME/code/libetpan/build"
git clone https://gitea.pep.foundation/pEp.foundation/libetpan.git ~/pep-src/libetpan
cd ~/pep-src/libetpan
mkdir ~/pep-src/libetpan/build
./autogen.sh --prefix="$HOME/pep-src/libetpan/build"
make
make install
~~~
@ -45,45 +58,70 @@ make install
## asn1c
~~~
mkdir -p ~/code/asn1c
git clone git://github.com/vlm/asn1c.git ~/code/asn1c
cd ~/code/asn1c
mkdir -p ~/pep-src/asn1c
git clone git://github.com/vlm/asn1c.git ~/pep-src/asn1c
cd ~/pep-src/asn1c
git checkout tags/v0.9.28 -b pep-engine
autoreconf -iv
mkdir ~/code/asn1c/build
./configure --prefix="$HOME/code/asn1c/build"
mkdir ~/pep-src/asn1c/build
./configure --prefix="$HOME/pep-src/asn1c/build"
make
make install
~~~
## sequoia
~~~
git clone https://gitlab.com/sequoia-pgp/sequoia
cd ~/pep-src/sequoia
git checkout openpgp/v1.3.0
# Make an optimised sequoia build.
cargo build --all --release -j16
~~~
This alternative for the last line above is faster, but generates compiled libraries
in `~/pep-src/sequoia/target/debug` instead of `~/pep-src/sequoia/target/release`:
several definitions below need to be adapted.
~~~
# Alternative: make a debugging sequoia build.
cargo build --all -j16
~~~
# pEp Engine
~~~
mkdir -p ~/code/pep-engine
hg clone https://pep.foundation/dev/repos/pEpEngine/ ~/code/pep-engine
cd ~/code/pep-engine
mkdir ~/code/pep-engine/build
mkdir -p ~/pep-src/pep-engine
git clone https://gitea.pep.foundation/pEp.foundation/pEpEngine ~/pep-src/pep-engine
cd ~/pep-src/pep-engine
mkdir build
~~~
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`.
Edit the build configuration to your needs in `Makefile.conf`, or create a `local.conf` in your source directory (the same containing `Makefile.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`.
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, libetpan and asn1c.
For a more detailed explanation of the mechanics of these build configuration files, and overriding defaults, see the comments in `Makefile.conf`.
Below is a sample `./local.conf` file, for orientation.
The following `./local.conf` example should work in the configuration described here.
~~~
PREFIX=$(HOME)/code/pep-engine/build
PREFIX=$(HOME)/pep-src/pep-engine/build
PER_MACHINE_DIRECTORY=$(PREFIX)/share/pEp
YML2_PATH=$(HOME)/code/yml2
YML2_PATH=$(HOME)/pep-src/yml2
ETPAN_LIB=-L$(HOME)/pep-src/libetpan/build/lib
ETPAN_INC=-I$(HOME)/pep-src/libetpan/build/include
ASN1C=$(HOME)/pep-src/asn1c/build/bin/asn1c
ASN1C_INC=-I$(HOME)/pep-src/asn1c/build/share/asn1c
ETPAN_LIB=-L$(HOME)/code/libetpan/build/lib
ETPAN_INC=-I$(HOME)/code/libetpan/build/include
SEQUOIA_INC=-I$(HOME)/pep-src/sequoia/openpgp-ffi/include
SEQUOIA_LDFLAGS=-L$(HOME)/pep-src/sequoia/target/release
ASN1C=$(HOME)/code/asn1c/build/bin/asn1c
ASN1C_INC=-I$(HOME)/code/asn1c/build/share/asn1c
GTEST_SRC_DIR=$(HOME)/pep-src/googletest/googletest
GTEST_INC_DIR=$(HOME)/pep-src/googletest/googletest/include
GTEST_PL=$(HOME)/pep-src/gtest-parallel/gtest_parallel.py
~~~
The engine is built as follows:


+ 65
- 14
test/README.md View File

@ -80,40 +80,61 @@ Ubuntu](https://www.eriksmistad.no/getting-started-with-google-test-on-ubuntu/))
1. Get the source, Fred. (Luke is tired of the source, I hear.)
```
git clone https://github.com/google/googletest.git
mkdir -p ~/pep-src/googletest
git clone https://github.com/google/googletest.git ~/pep-src/googletest
```
2. Switch into the source directory and find the directory
containing the `src` and `include` directories. Mark this directory
for later. (For me, this is `./googletest/googletest`)
3. Edit `CMakeLists.txt` here to contain the following line at the top:
2. Switch into the source directory and find the subdirectory of
`googletest` (the source distribution of googletest also contains a
`googlemock` library which is not useful to us here)
containing the `src` and `include` directories. Remember this
directory's path. For me it is `~/pep-src/googletest/googletest` .
3. Edit the file `CMakeLists.txt` in that directory, adding the
following line at the top:
```
set (CMAKE_CXX_STANDARD 11)
```
(If you don't, it won't compile, and I will shake my fist at you.)
4. Execute, in this directory:
4. Go to the googletest source directory (it should be the parent
directory of the directory containing the file you edited) and build
the library.
```
cd ~/pep-src/googletest
cmake CMakeLists.txt
make
```
5. In the lib directory of your current directory are located the
library files you'll use (`lib/*.a`). Copy or symlink them to the library
library files you'll use (`lib/*.a`). You may leave them there without
installing them, if you accept running a more complex command line than
```
make test
```
later. If you want to install the library, read on.
Copy or symlink them to the library
location of your choice (make sure this is a directory that can be seen
during the test build process - i.e. one that's in one of the library paths
used in building. Mine are located in `$HOME/lib`.
6. See `Makefile` and `local.conf` under "Building the test suite" below -
See `Makefile` and `local.conf` under "Building the test suite" below -
In this scenario, I set `GTEST_SRC_DIR` as `<clone_path>/googletest/googletest`
(i.e. the absolute path of where the `src` and `include` directories were
above - for me, `/Users/krista/googletest/googletest`).
above - for example, `/Users/krista/googletest/googletest`).
### Installing `gtest-parallel`
Pick a source directory and put your `gtest-parallel` source there
(e.g. via `git clone https://github.com/google/gtest-parallel.git`).
(e.g. via `git clone https://github.com/google/gtest-parallel.git`):
```
mkdir -p ~/pep-src/gtest-parallel
git clone https://github.com/google/gtest-parallel.git ~/pep-src/gtest-parallel
```
This library is written in Python and does not require any actual build.
We'll deal more with this when preparing to compile the test suite.
@ -133,13 +154,43 @@ are:
* `GTEST_INC_DIR`: This is where the include files for googletest are located
(defaults to `$(GTEST_SRC_DIR)/include`)
* `GTEST_PL`: This is the full path to the *python file* for `gtest_parallel`
* `GTEST_PL`: This is the full path to the *python file* for `gtest_parallel.py`
(default presumes you cloned it under `src` in your home directory, i.e. it is
`$(HOME)/src/gtest-parallel/gtest_parallel.py`)
The sample `local.conf` included in `../doc/build-debian.md` contains correct
definitions for these variables, assuming the user installed from sources under
`~/pep-src` as described here.
### Building
Presuming the above works, then from the top test directory, simply run make.
Presuming the above works and you installed every library, then from the top test
directory, simply run ``make``.
Libraries which have not been installed into the `lib` subdirectory of some
standard prefix will not be found automatically. But this problem is easy to
circumbent by setting environment libraries (on system using the GNU
linked-loader `LD_LIBRARY_PATH` for dynamic libraries, `LIBRARY_PATH` for static
libraries).
For example, this should be sufficient to run the test suite under a debian
system following the instruction at `../doc/build-debian.md`:
```
cd ~/pep-src/pep-engine
LIBRARY_PATH=$LIBRARY_PATH:$HOME/pep-src/googletest/lib LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/pep-src/pep-engine/src:$HOME/pep-src/sequoia/target/release:$HOME/pep-src/libetpan/build/lib make test
```
Such variable definitions may be prepended to the command lines below for running
individual tests or the entire test suite.
In case of test failures remember to build the database, on which the test suite
depends, and to copy it into the system directory:
```
make dbinstall
```
The database does not need to be rebuilt and reinstalled for every test suite
run: running the `dbinstall` target once suffices.
## Running the test suite


Loading…
Cancel
Save