diff --git a/doc/build-debian.md b/doc/build-debian.md index 56edca16..9bc295e4 100644 --- a/doc/build-debian.md +++ b/doc/build-debian.md @@ -1,43 +1,56 @@ - -# 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: diff --git a/test/README.md b/test/README.md index 553bc823..33b88c46 100644 --- a/test/README.md +++ b/test/README.md @@ -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 `/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