update documentation

5 files changed, 66 insertions, 123 deletions

diff --git a/CHANGELOG b/CHANGELOG
new file mode 100644
index 0000000..389d80b
--- /dev/null
+++ b/CHANGELOG
@@ -0,0 +1,16 @@
+Version 2.0
+-  Use of direct buffers to increase performance when receiving and transmititng data.
+-  Remove need to register to receive incoming data from an operator. A port is now opened by a client who will be the sole actor to receive messages from the operator.
+-  Migrate native build to makefile (C compiler is not called through sbt anymore).
+-  Add debian packaging.
+-  Drop option for creating fat jars (flow-pack).
+-  Downgrade Akka dependency to 2.2.0, for use with Play! projects.
+
+Version 1.2
+-  Upgrade Akka dependency to 2.3.0. (merge #3)
+
+Version 1.1
+-  Restructure build for easier cross-compilation. (fixes #1)
+
+Version 1.0
+-  Initial release.
\ No newline at end of file
diff --git a/README.md b/README.md
index 5097c8a..a7a127f 100644
--- a/README.md
+++ b/README.md
@@ -9,32 +9,9 @@ For a short guide on how to use flow see the file "documentation/basics.md", acc
 
 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" % "1.2.0"
+    libraryDependencies += "com.github.jodersky" %% "flow" % "2.0.0"
 
-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: (this dependency is not available on maven, please run ```flow-pack/publishLocal``` before)
-        
-        libraryDependencies += "com.github.jodersky" %% "flow-pack" % "1.2.0"
-        
-    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 are supported through this solution. Currently, these are given in the table below.
-
-    | OS                | Architecture         | Notes                                                                  |
-    |-------------------|----------------------|------------------------------------------------------------------------|
-    | Linux | x86<br>x86_64<br>ARM (v7, hardfloat, glibc 2.15) | 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
-
-    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.
+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.
 
 ## 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.
@@ -45,7 +22,7 @@ Since flow integrates into the Akka-IO framework, a good resource on its general
 Since hardware is involved in serial communication, a Scala-only solution is not possible. Nevertherless, the native code is kept simple and minimalistic with the burden of dealing with threads left to Scala. The code aims to be POSIX compliant and therefore easily portable.
 
 ## Build
-See detailed documentation in documentation/build.md (at github [here](https://github.com/jodersky/flow/blob/master/documentation/building.md)) on how to build flow. Note that flow can also be built on devices with sparse resources not able to run SBT (such as the Raspberry Pi), see documentation/embedded-building.md [here](https://github.com/jodersky/flow/blob/master/documentation/embedded-building.md).
+See detailed documentation in documentation/build.md (on github [here](https://github.com/jodersky/flow/blob/master/documentation/building.md)) on how to build and install flow.
 
 ## License
 flow is released under the terms of the 3-clause BSD license. See LICENSE for details.
diff --git a/documentation/building.md b/documentation/building.md
index 43a3678..238a4c0 100644
--- a/documentation/building.md
+++ b/documentation/building.md
@@ -1,40 +1,48 @@
 # Building flow
-A complete build of flow involves two parts
-
- 1. compiling scala sources (as in a regular project)
- 2. compiling native sources
- 
-As any java or scala project, the first part results in a platform independant artifact. However, the second part yields a binary that may only be used on systems resembling the platform for which it was compiled. To understand how flow can achieve such a mix, it is helpful to look at the project's directory layout.
-
-    .
-    ├── documentation
-    ├── flow
-    │   └── src
-    │       └── main
-    │           ├── java
-    │           ├── native
-    │           └── scala
-    ├── flow-pack
-    │   └── lib_native
-    ├── flow-samples
-    └── project
-
-The directories of interest in a build are:
-
- - flow/src/main/scala and flow/src/main/java:
- Contains java/scala sources that constitute the main library.
- 
- - flow/src/main/native:
- Contains native sources used in combination with JNI to support interacting with serial hardware. The directory itself is subdivided into:
-   - include: general headers describing the native side of the serial API
-   - posix: source code implementing the native serial API for posix-compliant operating systems
-
-With this structure in mind, building a complete distribution of flow involves (sbt commands are given in code tags):
-
- 1. compiling and packaging java/scala sources: `flow/packageBin`
- This simply compiles any scala and java sources as with any standard sbt project and produces a jar ready for being used.
- 
- 2. compiling and linking native sources for various platforms: `flow/nativeLink`
- This is the most complicated and error-prone step in the build. It involves compiling and cross-compiling the native sources for various platforms and linking them.
- Note that for this step to work, native builds for the current operating system have to be defined. Take a look at the build file to see how this is done (below ```trait Host``` in the file).
- After completing this step, native libraries for the different platforms are available to be copied and included in end-user applications.
\ No newline at end of file
+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.
+
+## Scala/Java 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.
+
+## Native 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._
+
+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:
+
+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.
+
+2.  Install shared library on system
+    Run `sudo make install` to install the compiled shared libraries on the local system.
+
+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 that for compiling, the JAVA_HOME environment variable must be set. Furthermore, the JNI include directories are currently set in the makefile to point to the default location of a Java 7 Oracle installation on Debian.
+
+# Using flow
+As is with the build, using flow in a project can also be divided into two parts.
+
+## 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"
+
+## 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
diff --git a/documentation/embedded-building.md b/documentation/embedded-building.md
deleted file mode 100644
index 36f5ba2..0000000
--- a/documentation/embedded-building.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Locally building on an embedded device
-Setting up cross-compilation on your host machine can be quite a daunting task, it involves installing and maybe even compiling other compilers and toolchains. The advantage of doing so is that you can easily build flow for different platforms at once and for systems that may not have the required resources to run sbt. However, if you are only targeting one specific platform that has the ability to run a C compiler and linker you can still build flow without the use of sbt.
-
-## Requirements
-- a target platform that has enough resources for compiling native programs
-- a host platform that can run SBT
-
-## Overview of required steps
-1. Compile native sources on target platform to a library
-2. Compile scala/java sources on host
-3. Use the compiled library with the scala/java application
-
-## Detailed procedure
-This section details the procedure for linux-based target platforms.
-
-1. Compilation of native sources [on the target platform]
-
-    a. Find where the jni include directory is. If you are using a recent oracle java distribution this would typically be /usr/lib/jvm/java-7-oracle/include/ and /usr/lib/jvm/java-7-oracle/include/linux
-
-    b. cd to flow/src/main/native
-
-    c. Compile: ```gcc -O2 -fPIC -I./include/ -I/usr/lib/jvm/java-7-oracle/include/ -I/usr/lib/jvm/java-7-oracle/include/linux -o flow.o -c posix/flow.c``` (replace the -I options with the paths found in a)
-
-    d. Link: ```gcc -shared -Wl,-soname,libflow.so.2 -o libflow.so flow.o```
-
-    e. That's all for the native side, you have a shared library backing flow. Copy libflow.so to any location you wish (see below).
-
-2. Compilation of scala/java sources [on the host platform]
-
-    a. ```sbt compile```
-
-    b. ```sbt publishLocal``` or ```sbt package``` or however you wish to publish flow
-
-    c. That's all regarding the scala/java side, you have a build of flow that is ready to be included in your projects.
-
-3. Putting it all together. 
-
-    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. However, 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:
-
-    - Per application:
-        - Run java with the command-line option -Djava.library.path="\<folder containing libflow.so\>". 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 libflow.so to a place that is on the default java library path and run your application normally. Such places usually include /usr/lib.
diff --git a/roadmap.md b/roadmap.md
deleted file mode 100644
index f802daa..0000000
--- a/roadmap.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Roadmap - changes that are, will or may be applied
-
-## Application side
-- Eliminate registering to receive data from an operator. A port is now opened by a client who will be the sole actor to receive messages from the operator. (DONE)
-- Use of direct buffers to increase performance when receiving and transmititng data. (DONE)
-- Remove flow-pack (Probably, it may look convenient at first but it is really a kind of dirty hack)
-
-## Build
-- Add better makefile build (Mostly done, TODO: become agnostic of jni.h location)
-- Add GNU Autotools build (Not sure, since autotools look kind of overly complex for a really simple native backend)
-- Add debian packaging (DONE)
-- Drop sbt native build (Probably, it seems like it was a mistake to call native compiler commands from sbt)
-- Reimplement native compilation for other Unix-like platforms
\ No newline at end of file