diff --git a/.hgignore b/.hgignore
index 629d5b5..87e6032 100644
--- a/.hgignore
+++ b/.hgignore
@@ -69,3 +69,4 @@ src/org.tar.gz
 syntax: regexp
 android/external/[^.]*
 
+src/local.conf
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2e86527
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# p≡p JNI Adapter
+
+## Prerequisites
+
+### yml2
+To set up yml2 properly, consult the documentation of pEp Engine (linked below). yml2 is a build dependency of pEp Engine.
+
+### C and C++ compiler
+Any gcc or clang distribution offered by your OS is fine.
+
+### pEp Engine
+Instructions for obtaining the pEp Engine can be found on [https://pep.foundation/dev/repos/pEpEngine/file/]().
+
+### libpEpAdapter
+Instructions for obtaining libpEpAdapter can be found on [https://pep.foundation/dev/repos/libpEpAdapter/file/]().
+
+### Java 8 (or newer) JDK
+Download Oracle Java from [https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html]().
+
+OpenJDK can be installed from macports on macOS with one of the following commands:
+
+~~~
+sudo port install openjdk8
+sudo port install openjdk11
+~~~
+
+## Building
+Customization of the build can be done in `src/Makefile.conf`, or in a file `src/local.conf` which is not part of the source code distribution.
+
+An example `src/local.conf` looks like this:
+
+~~~
+JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk8/Contents/Home
+
+YML2_PATH=$(HOME)/code/yml2
+
+ENGINE_INC=-I$(HOME)/code/engine/build/include
+ENGINE_LIB=-L$(HOME)/code/engine/build/lib
+
+AD_INC=-L$(HOME)/code/libad/build/include
+AD_LIB=-L$(HOME)/code/libad/build/lib
+~~~
+
+Depending on what is already set in your environment, or can be found in your default include/library paths, setting any of these variables may be optional on your platform.
+
+Now, build the Adapter with
+
+On Linux:
+
+~~~
+cd src
+make
+~~~
+
+On macOS:
+
+~~~
+cd src
+gmake
+~~~
+
+(The GNU Make distributed with macOS is too old, install GNU Make "gmake" from macPorts).
diff --git a/README.txt b/README.txt
index aca8ed9..9269728 100644
--- a/README.txt
+++ b/README.txt
@@ -1,4 +1,3 @@
 p≡p JNI Adapter
 ===============
 
-
diff --git a/android/build.gradle b/android/build.gradle
index b982d0c..d95d370 100644
--- a/android/build.gradle
+++ b/android/build.gradle
@@ -59,7 +59,7 @@ android {
     }
 
     dependencies {
-        compile 'commons-io:commons-io:2.4'
+        implementation 'commons-io:commons-io:2.4'
     }
 
     lintOptions {
diff --git a/src/Makefile b/src/Makefile
index 00411c2..5731a58 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -1,44 +1,83 @@
-LIBRARY=libpEpJNI.a
-SHARED=libpEpJNI.so
-JAR=pEp.jar
+# Copyright 2018, pEp Foundation
+# This file is part of pEp JNI Adapter
+# This file may be used under the terms of the GNU General Public License version 3
+# see LICENSE.txt
+
 include Makefile.conf
 
-CXXFLAGS+=-std=c++14 -fPIC
+ifneq ($(wildcard local.conf),)
+    $(info ================================================)
+    $(info Overrides in \`local.conf\` are used.)
+    $(info ================================================)
+endif
 
-all: $(JAR) $(SHARED)
+ifdef BUILD_CONFIG
+    $(info ================================================)
+    $(info Overrides in \`$(BUILD_CONFIG)\` are used.)
+    $(info ================================================)
+endif
+
+ifndef JAVA_HOME
+    $(error JAVA_HOME is not set!)
+endif
+
+JP=$(JAVA_HOME)/bin
 
-JAVA_SOURCES=org/pEp/jniadapter/pEpException.java \
-			 org/pEp/jniadapter/AbstractEngine.java \
-			 org/pEp/jniadapter/Message.java \
-			 org/pEp/jniadapter/Engine.java \
-			 org/pEp/jniadapter/Identity.java \
-			 org/pEp/jniadapter/_Identity.java \
-			 org/pEp/jniadapter/Blob.java \
-			 org/pEp/jniadapter/_Blob.java \
-			 org/pEp/jniadapter/CommType.java
+# Old versions of a Java distribution have a `javah` binary, new versions do not. This checks whether or not `javah` can be found in the Java distribution found in the directory `$JAVA_HOME`.
+NOT_USED:=$(shell which $(JAVA_HOME)/bin/javah)
+ifeq ($(.SHELLSTATUS),0)
+    OLD_JAVA=placeholder
+endif
+
+LIBRARY=libpEpJNI.a
+JAR=pEp.jar
+
+ifeq ($(BUILD_FOR),Linux)
+    SHARED=libpEpJNI.so
+else ifeq ($(BUILD_FOR),Darwin)
+    SHARED=libpEpJNI.dylib
+else
+    $(error I don't know how to build for $(BUILD_FOR).)
+endif
+
+JAVA_SOURCES=org/pEp/jniadapter/AbstractEngine.java \
+    org/pEp/jniadapter/Blob.java \
+    org/pEp/jniadapter/CommType.java \
+    org/pEp/jniadapter/Identity.java \
+    org/pEp/jniadapter/Pair.java \
+    org/pEp/jniadapter/Sync.java \
+    org/pEp/jniadapter/_Blob.java \
+    org/pEp/jniadapter/_Identity.java \
+    org/pEp/jniadapter/pEpException.java \
+    org/pEp/jniadapter/Message.java \
+    org/pEp/jniadapter/Engine.java \
 
 C_SOURCES=org_pEp_jniadapter_Engine.cc \
-		  org_pEp_jniadapter_Engine.h \
-		  org_pEp_jniadapter_Message.cc \
-		  org_pEp_jniadapter_Message.h \
-		  throw_pEp_exception.cc \
-		  throw_pEp_exception.hh \
-		  org_pEp_jniadapter_AbstractEngine.h
+    org_pEp_jniadapter_Engine.h \
+    org_pEp_jniadapter_Message.cc \
+    org_pEp_jniadapter_Message.h \
+    throw_pEp_exception.cc \
+    throw_pEp_exception.hh \
+    org_pEp_jniadapter_AbstractEngine.h
 
-gensource: $(JAVA_SOURCES) $(C_SOURCES)
 
-$(JAR): $(JAVA_SOURCES)
-	javac $(JAVA_SOURCES)
-	jar cf $@ org/pEp/jniadapter/*.class
+.PHONY: all
+all: $(JAR) $(SHARED)
 
-org_pEp_jniadapter_AbstractEngine.h: org/pEp/jniadapter/AbstractEngine.java
-	javah $(subst /,.,$(subst .java,,$<))
+.PHONY: gensource
+gensource: $(JAVA_SOURCES) $(C_SOURCES)
 
-org_pEp_jniadapter_Engine.h: org/pEp/jniadapter/Engine.java
-	javah $(subst /,.,$(subst .java,,$<))
+$(JAR): $(JAVA_SOURCES)
+	$(JP)/javac org/pEp/jniadapter/*.java
+	$(JP)/jar cf $@ org/pEp/jniadapter/*.class
 
-org_pEp_jniadapter_Message.h: org/pEp/jniadapter/Message.java
-	javah $(subst /,.,$(subst .java,,$<))
+BLUBB=org_pEp_jniadapter_AbstractEngine.h org_pEp_jniadapter_Engine.h org_pEp_jniadapter_Message.h
+$(BLUBB): org_pEp_jniadapter_%.h: org/pEp/jniadapter/%.java
+ifdef OLD_JAVA
+	$(JP)/javah $(subst /,.,$(subst .java,,$<))
+else
+	$(JP)/javac -h . $<
+endif
 
 org_pEp_jniadapter_AbstractEngine.o: %.o: %.cc %.h throw_pEp_exception.hh jniutils.hh
 	$(CXX) $(CXXFLAGS) -c $< -o $@
@@ -50,32 +89,31 @@ $(LIBRARY): org_pEp_jniadapter_AbstractEngine.o org_pEp_jniadapter_Engine.o org_
 	ar -r $@ *.o
 
 $(SHARED): $(LIBRARY)
-	$(CXX) $(CXXFLAGS) -shared -o $(SHARED) $(LDFLAGS) -lpEpEngine $(PEP_ADAPTER_OBJECT_LIB)/*.o *.o
-#FIXME ^ use libpEpAdapter.a instad of the bunch of *.o
+	$(CXX) *.o $(LDFLAGS) $(LDLIBS) -o $@
+
 org/pEp/jniadapter/pEpException.java: pEp.yml2 gen_java_exceptions.ysl2
-	yml2proc -y gen_java_exceptions.ysl2 $< -o $@
+	$(YML2_PROC) -y gen_java_exceptions.ysl2 $< -o $@
 
 org/pEp/jniadapter/Message.java: pEp.yml2 gen_java_Message.ysl2 types_java.ysl2
-	yml2proc -y gen_java_Message.ysl2 $<
-
-org_pEp_jniadapter_Message.cc: pEp.yml2 gen_cpp_Message.ysl2 types_c.ysl2
-	yml2proc -y gen_cpp_Message.ysl2 $<
+	$(YML2_PROC) -y gen_java_Message.ysl2 $<
 
 org/pEp/jniadapter/Engine.java: pEp.yml2 gen_java_Engine.ysl2 types_java.ysl2
-	yml2proc -y gen_java_Engine.ysl2 $<
+	$(YML2_PROC) -y gen_java_Engine.ysl2 $<
+
+org_pEp_jniadapter_Message.cc: pEp.yml2 gen_cpp_Message.ysl2 types_c.ysl2
+	$(YML2_PROC) -y gen_cpp_Message.ysl2 $<
 
 org_pEp_jniadapter_Engine.cc: pEp.yml2 gen_cpp_Engine.ysl2 types_c.ysl2
-	yml2proc -y gen_cpp_Engine.ysl2 $<
+	$(YML2_PROC) -y gen_cpp_Engine.ysl2 $<
 
 throw_pEp_exception.cc throw_pEp_exception.hh: pEp.yml2 gen_throw_pEp_exception.ysl2 textutils.ysl2
-	yml2proc -y gen_throw_pEp_exception.ysl2 $< -o throw_pEp_exception.cc
+	$(YML2_PROC) -y gen_throw_pEp_exception.ysl2 $< -o throw_pEp_exception.cc
 
 throw_pEp_exception.o: throw_pEp_exception.cc throw_pEp_exception.hh
 
 basic_api.o: basic_api.cc jniutils.hh throw_pEp_exception.hh
 
-.PHONY: clean test
-
+.PHONY: clean
 clean:
 	rm -f $(JAR) $(LIBRARY) $(SHARED)
 	rm -f *.o
@@ -87,12 +125,11 @@ clean:
 	rm -f org/pEp/jniadapter/Engine.java
 	rm -f org/pEp/jniadapter/Message.java
 	rm -f org/pEp/jniadapter/Color.java
+	rm -f org/pEp/jniadapter/DecryptFlags.java
+	rm -f org/pEp/jniadapter/IdentityFlags.java
+	rm -f org/pEp/jniadapter/Rating.java
+	rm -f org/pEp/jniadapter/Status.java
+	rm -f org/pEp/jniadapter/SyncHandshakeResult.java
+	rm -f org/pEp/jniadapter/SyncHandshakeSignal.java
 	rm -f throw_pEp_exception.*
 	rm -f org_pEp_jniadapter_Message.cc org_pEp_jniadapter_Engine.cc
-
-AdapterTest.class: AdapterTest.java SyncCallbacks.java
-	javac -cp .:$(JAR) $< SyncCallbacks.java
-
-test: AdapterTest.class
-	java AdapterTest
-
diff --git a/src/Makefile.conf b/src/Makefile.conf
index 11fb910..5d6c0d3 100644
--- a/src/Makefile.conf
+++ b/src/Makefile.conf
@@ -1,4 +1,70 @@
-CXXFLAGS=-I$(JAVA_HOME)/include -I$(JAVA_HOME)/include/darwin -I$(HOME)/include -fpermissive -DDISABLE_SYNC
-LDFLAGS=-L$(HOME)/lib
-SHARED=libpEpJNI.dylib
-PEP_ADAPTER_OBJECT_LIB=$(HOMEI)/pEp/libpEpAdapter
+# Copyright 2018, pEp Foundation
+# This file is part of pEp JNI Adapter
+# This file may be used under the terms of the GNU General Public License version 3
+# see LICENSE.txt
+
+######### Header #########
+HERE:=$(dir $(lastword $(MAKEFILE_LIST)))
+
+
+######### General #########
+BUILD_FOR:=$(shell uname)
+
+
+######### Java #########
+#JAVA_HOME=
+
+
+######### C and C++ #########
+LDFLAGS=-shared $(ENGINE_LIB) $(AD_LIB)
+
+LDLIBS=-lstdc++ -lpEpEngine
+
+
+######### C++ #########
+ifeq ($(BUILD_FOR),Linux)
+    CXX=g++ -std=c++14
+else ifeq ($(BUILD_FOR),Darwin)
+    CXX=clang -std=c++14
+endif
+
+ifeq ($(BUILD_FOR),Linux)
+    CXXFLAGS=-fdiagnostics-color=always -fpermissive -fPIC -I$(JAVA_HOME)/include -I$(JAVA_HOME)/include/linux $(AD_INC) $(ENGINE_INC) -DDISABLE_SYNC
+else ifeq ($(BUILD_FOR),Darwin)
+    CXXFLAGS=-fcolor-diagnostics -fpermissive -fPIC -I$(JAVA_HOME)/include -I$(JAVA_HOME)/include/darwin $(AD_INC) $(ENGINE_INC) -DDISABLE_SYNC
+endif
+
+
+######### YML2 #########
+YML2_PATH=$(HOME)/yml2
+
+YML2_PROC=$(YML2_PATH)/yml2proc $(YML2_OPTS)
+
+YML2_OPTS=--encoding=utf8
+
+
+######### Engine #########
+ENGINE_LIB=
+#ENGINE_LIB=-L$(HOME)/local/lib
+
+ENGINE_INC=
+#ENGINE_INC=-I$(HOME)/local/inc
+
+
+######### libAdapter #########
+AD_LIB=
+#AD_LIB=-L$(HOME)/local/lib
+
+AD_INC=
+#AD_INC=-I$(HOME)/local/inc
+
+
+######### Footer #########
+-include $(HERE)/local.conf
+
+ifdef BUILD_CONFIG
+    include $(BUILD_CONFIG)
+endif
+
+# YML_PATH is needed in the environment of every call to a program of the YML2 distribution
+export YML_PATH=$(YML2_PATH)