update documentation

2 files changed, 40 insertions, 43 deletions

diff --git a/README.md b/README.md
index 4837a73..816b5f2 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,33 @@ For a short guide on how to use flow see the file [documentation/basics.md](docu
 
 Flow is built and its examples run with SBT. To get started, include a dependency to flow in your project:
 
-    libraryDependencies += "com.github.jodersky" %% "flow" % "2.0.0-RC2"
+    libraryDependencies += "com.github.jodersky" %% "flow" % "2.0.0-RC3" (repository pending)
 
-ATTENTION: flow uses native libraries to back serial communication, therefore before you can run any application depending on flow you must include flow's native library in the JVM library path. Check out section 'build' on how this may be done.
+ATTENTION: flow uses native libraries to back serial communication, therefore before you can run any application depending on flow you must include flow's native library! To do so, you have two options.
+
+1.  The easy way: add a second dependency to your project:
+        
+        libraryDependencies += "com.github.jodersky" %% "flow-native" % "2.0.0-RC3" (repository pending)
+
+    This will add a jar to your classpath containing native libraries for various platforms. At run time, the correct library for the current platform is selected, extracted and loaded. This solution enables running applications seamlessly, as if they were pure JVM applications. However, since the JVM does not enable full determination of the current platform (only OS and rough architecture are known), only a couple of platforms can be supported through this solution at the same time. Currently, these are given in the table below.
+
+    | OS                | Architecture         | Notes                                                                  |
+    |-------------------|----------------------|------------------------------------------------------------------------|
+    | Linux | x86<br>x86_64<br>ARM (v7, hardfloat ABI) | A user accessing a serial port may need to be in the dialout group <br> ARM may work on other versions too, any feedback is welcome!<br>|
+    | Mac OS X | x86_64               | Use /dev/cu* device instead of /dev/tty*.                              |
+
+
+2.  Maximum scalability: do not include the second dependency above. Instead, for every end-user application that relies on flow, manually add the native library for the current platform to the JVM's library path. This can be achieved through various ways, notably:
+      - Per application:
+        Run your program with the command-line option ```-Djava.library.path=".:<folder containing libflow.so>"```. E.g. ```java -Djava.library.path=".:/home/<folder containing libflow.so>" -jar your-app.jar```
+
+      - System- or user-wide:
+          - Copy the native library to a place that is on the default java library path and run your application normally. Such places usually include /usr/lib and /usr/local/lib.
+          - Use a provided installer (currently debian archive and mac .pkg, available in releases)
+
+    The native library can either be obtained by building flow (see section Build) or by taking a pre-compiled one, found in releases in the github project.
+
+It is recomended that you use the first option only for testing purposes or end-user applications. The second option is recomended for libraries, since it leaves more choice to the end-user.
 
 ## Examples
 Examples on flow's usage are located in the flow-samples directory. The examples may be run by switching to the corresponding project in sbt: `project flow-samples-<sample_name>` and typing `run`. Be sure to connect a serial device before running an example.
diff --git a/documentation/building.md b/documentation/building.md
index 03729f7..433dce8 100644
--- a/documentation/building.md
+++ b/documentation/building.md
@@ -1,48 +1,21 @@
-# Building flow
-Flow can be divided into two layers: a scala front-end that wraps serial communication in an actor-style way, and a native back-end that actually enables the communication. These layers are loosely coupled, their only interaction being the JNI bindings generated by javah. As such, building flow may be decomposed into two independent steps.
+# Building from source
+A complete build of flow involves two parts
 
-## 1) Front-end
-The front-end is compiled as any regular Scala project. It is managed by sbt and may be built by running `sbt flow/packageBin`, producing a jar ready to be included in any project.
+ 1. building scala sources (the front-end)
+ 2. building native sources (the back-end)
 
-## 2) Back-end
-_Note: currently, the native build only supports Linux. However, the code is designed to be portable and should be able to compile on other Unix flavours (including Mac). Any contributions to the native build are highly welcome._
+As any java or scala project, the first part results in a platform independent artifact. However, the second part yields a binary that may only be used on systems resembling the platform for which it was compiled. Both steps are independent, their only interaction being the header files generated by javah (see `sbt javah` for details), and may therefore be built in part and in any order.
 
-All files related to the back-end are contained in `flow-native` and are managed by make. The build offers various options for compilation and installation, be sure to check the makefile for additional information. The following is a short, incomplete list of build possibilities:
+## Compiling and packaging java/scala sources
+Run `sbt flow/packageBin` in the base directory. This simply compiles any scala and java sources as with any standard sbt project and produces a jar ready for being used.
 
-1.  Build shared library
-    Run `make all` to build a shared library, including any associated links. Be advised that the shared library doesn't quite use semantic versioning in that the major version is always kept at zero and instead appended to the name of the library, i.e. the semantic libflow.so.3.1.2 becomes libflow3.so.0.1.2. This deviation from semantic versioning is necessary since java does not permit loading libraries based on their soname.
+## Compiling and linking native sources
+The back-end is managed by GNU Autotools and all releveant files are contained in 'flow-native'. Run `./configure && make` to compile the back-end. After completing this step, native libraries for the different platforms are available to be copied and included in end-user applications or installed on the system. To copy the binaries to a local directory, run ```DESTDIR=`pwd`/<directory> make install```. To install them system-wide, simply run `make install` as an administrator.
 
-2.  Install shared library on system
-    Run `sudo make install` to install the compiled shared libraries on the local system.
+## Creating a fat jar
+The native binaries produced in the previous step may be bundled in a "fat" jar so that they can be included in sbt projects through its regular dependency mechanisms. In this process, sbt basically acts as a wrapper script around autotools, calling the native build process and packaging generated binaries. Running `sbt flow-native/packageBin` in the base directory produces the fat jar in 'flow-native/target'.
 
-3.  Debian package build
-    A debian binary package can be built the standard way by navigating to the build directory and running `debuild` or `dpkg-buildpackage`. The resulting packages are created in this project's root directory and can be installed with `sudo dpkg -i *.deb`.
+Note: an important feature of fat jars is to include binaries for several platforms. To copy binaries compiled on other platforms to the fat jar, place them in a subfolder of 'flow-native/lib_native'. The subfolder should have the name `$(os.name)-$(os.arch)`, where `os.name` and `os.arch` are the java system properties of the respective platforms.
 
-Note that for compiling a JNI_INCLUDE environment variable should be set, pointing to any directories containing JNI headers. If this variable is not set, the default is to use the JNI include directories of an OpenJDK 7 installation on Debian.
-
-# Including flow
-As is with the build, using flow in a project can also be divided into two parts.
-
-## 1) Front-end
-In your scala/java application, treat flow as if it were a pure scala/java library and build your application with flow as a usual dependency. When using sbt to build your application, you can add flow as a dependency with the following line:
-
-    libraryDependencies += "com.github.jodersky" %% "flow" % "2.0.0-RC2"
-
-## 2) Back-end
-When running your application or any other application that relies on it, the native library must be included in java's library path. To do so, you have several options depending on the type of build you performed (see previous section).
-
-### Manual or package-based installation
-You are done. If you performed steps 2 or 3 from the native build instructions, the library has been installed in a place that is checked by the jvm when loading flow.
-
-### Only shared library
-If you only built or downloaded a precompiled library (without installing it), you can choose how to include it:
--  Per application:
-    -  Run java with the command-line option -Djava.library.path="\<folder containing library\>". For example, if the native library is in the current directory, ```java -Djava.library.path="." -jar your-app.jar```
-    -  Run your program by prepending LD_LIBRARY_PATH=<folder containing libflow.so> to the command. E.g ```LD_LIBRARY_PATH=<folder containing libflow.so> java -jar your-app.jar```
-
--  System- or user-wide:
-    - Copy the library to a place that is on the default java library path and run your application normally. Such places usually include /usr/lib.
-
-
-# Precompiled binaries
-Precompiled versions of the native back-end are available for download in the releases of the github project.
\ No newline at end of file
+# Note about versioning
+When building and locally publishing projects, the usual convention is to append "-SNAPSHOT" to the version string. This practice however breaks version identification and badly hurts git (bisecting becomes a nightmare). Therefore, to identify a build artifact with a specific commit in the repository, a sha1 hash is appended to the version instead. When publishing a new release, this hash may be ommited by setting the java system property "release=true", simply by running sbt -Drelease=true.
\ No newline at end of file