Skip to content

Latest commit

 

History

History
391 lines (326 loc) · 15.4 KB

INSTALL.md

File metadata and controls

391 lines (326 loc) · 15.4 KB
Raw

Serval DNA Build and Test

Serval Project, December 2017

Supported Architectures

These instructions will build Serval DNA successfully for the following platforms:

  • Debian Linux, ix86 and x86_64, kernel versions 2.6 and later, using gcc 4.4 and later, gcc 5, gcc 6 and gcc 7
  • Mac OS x86_64, releases 10.7 “Lion” to 10.13 “High Sierra”, using Xcode versions 3.2 to 9.3, supplemented by homebrew
  • Oracle SunOs 5.10 (Solaris), Sparc, using gcc 4.4 and GNU tools installed

Serval DNA also builds and runs on the following platforms, for which there are separate build instructions:

Download

Serval DNA source code is available from the serval-dna repository on GitHub. You can use Git to download the latest version:

$ cd $HOME/src
$ git clone -q git://github.com/servalproject/serval-dna.git
$ cd serval-dna
$

Dependencies

The dependencies for build are expressed in configure.ac. Most mandatory dependencies are present in the standard Linux development environment.

Mandatory dependencies:

  • standard C library libc and standard headers
  • standard math library libm and headers <math.h> <float.h>
  • network services library libnsl and headers
  • dynamic link library libdl and header <dlfcn.h>
  • Native Posix Threads Library libpthread and header <pthread.h>
  • on Solaris, the realtime library librt (for the nanosleep() function)
  • GNU autoconf 2.67-2.69 (2.70 may work but has not been tested)
  • GNU automake 1.15 or later
  • GNU libtool 2.4.6 or later (for the libtoolize utility)

Optional:

  • Java compiler and SDK 1.6.0 or later
  • Swift 3 or 4 compiler
  • ALSA sound library and headers (present on Linux, not on Android)

Test dependencies:

  • Bash 3.2.48 or later
  • GNU grep, GNU sed and GNU awk
  • jq 1.3 or later
  • curl 7.45 or later

Apple Mac OS

On Apple Mac OS, the following dependencies are provided by the Xcode package:

  • all libraries and headers listed above
  • Swift 3 or 4
  • Bash 3.2.48
  • curl 7.45

The following dependencies must be installed on Mac OS using the homebrew package manager:

  • GNU autoconf 2.69
  • GNU automake 1.15
  • GNU libtool 2.4.6 (provides glibtoolize)
  • GNU grep (provides ggrep)
  • GNU sed (provides gsed)
  • GNU awk (provides gawk)
  • jq

See Notes for Developers for more details.

Native Build

A native build of Serval DNA will produce libraries and executable programs that can be run on the same platform on which the build is performed. This is useful for development and testing.

The following commands will compile a native (ie, not cross-compiled) Serval DNA from source:

$ cd $HOME/src/serval-dna
$ autoreconf -f -i -I m4
$ ./configure
$ make
$

A successful session should appear something like:

$ cd $HOME/src/serval-dna
$ autoreconf -f -i -I m4
$ ./configure
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
checking target system type... i686-pc-linux-gnu
checking for pkg-config... /usr/bin/pkg-config
checking pkg-config is at least version 0.9.0... yes
checking for gcc... gcc
...
checking for library containing strlcpy... no
configure: creating ./config.status
config.status: creating Makefile
config.status: creating testconfig.sh
$ make
SERVALD CC servald_features.c
MAKE libsodium-dev
make[1]: Entering directory '/home/username/src/serval-dna/libsodium'
Making install in contrib
make[2]: Entering directory '/home/username/src/serval-dna/libsodium/contrib'
...
make[4]: Leaving directory '/home/username/src/serval-dna/libsodium/src/libsodium/include'
make[4]: Entering directory '/home/username/src/serval-dna/libsodium/src/libsodium'
  CC       crypto_aead/chacha20poly1305/sodium/libsodium_la-aead_chacha20poly1305.lo
  CC       crypto_aead/xchacha20poly1305/sodium/libsodium_la-aead_xchacha20poly1305.lo
  CC       crypto_auth/libsodium_la-crypto_auth.lo
...
----------------------------------------------------------------------
Libraries have been installed in:
   /home/username/src/serval-dna/libsodium-dev/lib
...
make[1]: Leaving directory '/home/username/src/serval-dna/libsodium'
SERVALD CC jni_common.c
SERVALD CC jni_commandline.c
SERVALD CC jni_instance.c
...
CC version_servald.c
AR _servald.a
LINK libservaldaemon.so
LIB CC base64.c
LIB CC cli.c
LIB CC cli_stdio.c
...
LINK servald
CC directory_service.c
LINK directory_service
SERVALD CC servalwrap.c
LINK servaldwrap
SERVALD CC test_features.c
LINK serval-tests
CC fakeradio.c
LINK fakeradio
CC simulator.c
LINK simulator
CC tfw_createfile.c
LINK tfw_createfile
SWIFT servaldswift
make[1]: Entering directory '/home/username/src/serval-dna/java-api'
JAVAC classes
JAVAC testclasses
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
make[1]: Leaving directory '/home/username/src/serval-dna/java-api'
SWIFT MODULE servald.swiftmodule
cd swift-api && make SOURCE_PREFIX= all
make[1]: Entering directory '/home/username/src/serval-dna/swift-api'
swift build --package-path package
Compile Swift Module 'ServalClient' (5 sources)
Archiving /home/username/src/serval-dna/swift-api/package/.build/x86_64-unknown-linux/debug/libServalClient.a
SWIFT test-swift
make[1]: Leaving directory '/home/username/src/serval-dna/swift-api'
rm _servalclient.a _monitorclient.a _servald.a
$

On some systems, the system make command may not be GNU Make, and the system cc command may not be GNU gcc. The following may work:

$ cd $HOME/src/serval-dna
$ autoreconf -f -i -I m4
$ ./configure CC=gcc
$ gmake
$

In the event of a build failure:

Android build

The batphone app for Android builds Serval DNA from source by including Android.mk in its own build process; see the batphone build instructions for more information.

It is not necessary to perform a native build before or after an Android build; the two produce completely unrelated artifacts.

Built artifacts

The native build process produces the following artifacts:

  • servald is the main Serval DNA daemon executable. All the Serval DNA daemon, SQLite and libsodium code is statically linked into this executable, and only common system libraries are dynamically linked, which keeps its run-time dependencies to a minimum. Its unstripped size is about 9.5 MB on a typical 64-bit system, of which about 7 MB is SQLite. Its stripped size is about 3 MB.

  • servaldwrap is a Serval DNA executable identical to servald, but it loads libservaldaemon.so at run-time using dlopen(3) instead of being statically linked, so it is only a dozen KB in size. This executable mainly exists to test that the shared library is loadable.

  • serval-tests is an executable utility that performs various system tests such as memory speed, cryptographic speed, byte ordering, and configuration parsing. These tests are not normally required in a deployed system, so are provided in a separate executable in order to keep the size of the servald executable to a minimum.

  • libservaldaemon.a is a static library containing the complete executable code of the Serval DNA daemon, including SQLite and libsodium cryptographic functions. An executable (such as servald) can be built with any desired subset of Serval functions by linking in only the required parts of this library using the features mechanism described in feature.h. The Serval DNA Swift API, which is used by the Serval Chat app for iOS, uses this static library.

  • libservaldaemon.so is a dynamic library containing the complete executable code of the Serval DNA daemon, including JNI entry points, SQLite and libsodium cryptographic functions. The servaldwrap executable and the Serval DNA Java API, which is used by batphone, both use this dynamic library.

  • directory_service is the executable for the Serval Infrastructure daemon.

  • libservalclient.a and libservalclient.so are static and dynamic libraries implementing the client end of the interface with the servald daemon, which includes the MDP API, a subset of the CLI API, and functions for starting and stopping the daemon. The dynamic library is linked into the batphone Java executable at run time and contains JNI entry points to these APIs.

  • libmonitorclient.a and libmonitorclient.so are static and dynamic libraries implementing the client end of the monitor interface with the servald daemon. The dynamic library is linked into the batphone Java executable at run time and contains JNI entry points to functions for managing the client end of a monitor connection with the servald daemon. The monitor interface is deprecated and will eventually be replaced by a set of equivalent MDP services that can be accessed using libservalclient.

  • fakeradio is an executable utility used by test scripts to simulate the serial interface to the RFD900 packet radio used in the Serval Mesh Extender

  • simulator is an executable utility used by test scripts for simulating wireless packet transmission under different conditions.

  • tfw_createfile is an executable utility needed by test scripts for creating large data files with unique, non-repeating content.

In addition, the following artifacts are produced if a Swift compiler is present:

  • servaldswift is a statically linked Serval DNA executable identical to servald, but its main entry point is compiled from a Swift program to prove that Swift code can invoke internal Serval DNA daemon APIs. It dynamically links to many more system libraries than servald because of the Swift language's run-time support and resultant library dependencies, so is not suitable for deployment.

  • ServalDNA.swiftmodule
    ServalDNA.swiftdoc
    libServalDNA.a
    are the Swift Daemon API module.

  • swift-client-api/build/debug/ServalClient.swiftmodule
    swift-client-api/build/debug/ServalClient.swiftdoc
    swift-client-api/build/debug/libServalClient.a
    are the Swift Client API module.

Test scripts

After building the native servald executable, run all the tests with the following command:

$ ./tests/all
1 [PASS.] (logging) By default, only errors and warnings are logged to stderr
2 [PASS.] (logging) Configure all messages logged to stderr
3 [PASS.] (logging) Configure no messages logged to stderr
4 [PASS.] (logging) By Default, all messages are appended to a configured file
...
375 [PASS.] (meshmsjava) Java API send MeshMS message from unknown identity
376 [PASS.] (meshmsjava) Java API MeshMS mark all conversations read
377 [PASS.] (meshmsjava) Java API MeshMS mark all conversations read
378 [PASS.] (meshmsjava) Java API MeshMS mark a message as read
378 tests, 378 pass, 0 fail, 0 error
$

Every test run writes log files into the testlog/all directory (relative to the current working directory), deleting any logs from the previous run.

See Serval DNA Testing for more information on running and developing test scripts.

Configure

Before running servald, it must be configured correctly. The doc/Servald-Configuration document describes the configuration of Serval DNA in detail.

About the examples

The examples in this document are Bourne shell commands, using standard quoting and variable expansion. Commands issued by the user are prefixed with the shell prompt $ to distinguish them from the output of the command. Single and double quotes around arguments are part of the shell syntax, so are not seen by the command. Lines ending in backslash \ continue the command on the next line.

The directory paths used in the examples are for illustrative purposes only, and may need to be changed for your particular circumstances.

Copyright 2013-2015 Serval Project Inc.
Copyright 2016-2017 Flinders University
CC-BY-4.0 This document is available under the Creative Commons Attribution 4.0 International licence.