update readme and add documentation for embedded compiling

2 files changed, 51 insertions, 59 deletions

diff --git a/README.md b/README.md
index b0c5008..762af9d 100644
--- a/README.md
+++ b/README.md
@@ -7,74 +7,21 @@ The main reason for yet another serial communication library for the JVM is that
 ## Basic usage
 For a short guide on how to use flow see the file "documentation/basics.md", accessible on github [here](https://github.com/jodersky/flow/blob/master/documentation/basics.md).
 
-Flow is built and its examples run with SBT. To get started, run `sbt flow/publish-local` to publish the library locally. From there on, you may use the library in any project simply by adding a library dependency to it.
-
-    libraryDependencies += "com.github.jodersky" % "flow" % "1.1-SNAPSHOT"
-
-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.
-
-Since flow integrates into the Akka-IO framework, a good resource on its general design is the framework's documentation at http://doc.akka.io/docs/akka/2.2.0/scala/io.html
-        
 ## Currently supported platforms
 
 | OS (tested on)    | Architecture            | Notes                                                                 |
 |-------------------|-------------------------|-----------------------------------------------------------------------|
-| Linux (3.2.0)     | x86<br>x86_64<br>armv7l | A user accessing a serial port may need to be in the 'dialout' group. |
+| Linux (3.2.0)     | x86<br>x86_64<br>armv7  | A user accessing a serial port may need to be in the 'dialout' group. |
 | Mac OS X (10.6.8) | x86_64                  | Use /dev/cu* device instead of /dev/tty*.                             |
 
-Note: flow may work on older versions of the tested OS kernels.
-
 ## Native side
 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
-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. Nevertheless, to provide multiplatform support, flow produces a "fat executable", a jar containing native binaries compiled for different flavours of operating system and architecture combinations. During runtime, a matching native binary is selected and loaded. To understand how flow can achieve such a mix, it is helpful to look at the project's directory layout.
-
-    flow
-    ├── documentation
-    ├── flow-binaries
-    ├── flow-main
-    ├── flow-native
-    │   ├── shared
-    │   │   └── include
-    │   └── unix
-    ├── flow-samples
-    └── project
-
-The directories of interest in a build are:
-
- - flow-main:
- Contains java/scala sources that constitute the main library.
- 
- - flow-native:
- Contains native sources used in combination with JNI to support interacting with serial hardware. The directory itself is subdivided into:
-   - shared/include:
-   general headers describing the native side of the serial API
-   - unix:
-   source code implementing the native serial API for unix-like operating systems
- 
- - flow-binaries:
- Contains binaries produced by various native builds on different platforms. The format of binaries inside this directory is `<os>/<arch>/<libraryname>.<major>.<minor>`, where `<os>` and `<arch>` correspond to the values (without spaces) given by `System.properties` from the JVM.
- 
+The build is currently being restructured for less cumbersome native compilation and easier cross-compilation (e.g. for targeting embedded platforms like the Raspberry Pi).
+Current status: building works, however the production of fat jars containing native libraries is not yet supported.
 
-With this structure in mind, building a complete distribution of flow involves (sbt commands are given in code tags):
+See documentation/embedded-building.md for a description on how to build the native part of flow on memory restricted devices, requiring only a C compiler and linker.
 
- 1. compiling java/scala sources: `flow/compile`
- This simply compiles any scala and java sources as with any standard sbt project.
- 
- 2. compiling and linking native sources for the current platform: `flow-native-<os>/native:link`
- This is the most complicated and error-prone step in the build. It involves running javah to generate JNI headers, compiling the native sources for the current platform and linking them.
- Note that for this step to work, a project for the current operating system has to be defined. Take a look at the build file to see how this is done.
- 
- 3. locally publishing the native binary to include in final jar: `flow-native-<os>/publishNative`
- This copies the compiled binary (for the current platform) to the flow-binaries folder.
- 
- 4. packaging the final jar: `flow/package`
- This copies the latest major version-compatible shared libraries of flow-binaries to the final jar.
- 
-The idea behind publishing to an intermediate location is to provide a central collection of binaries that may be created from different systems and included in one final jar (a nice corollary is that anyone can compile native sources on a platform, submit a pull request and have the binary included). As such, if you are only modifying java/scala sources, it is not necessary to compile any native sources and steps 2 and 3 from above may be omitted.
+## License
+flow is released under the terms of the 3-clause BSD license. See LICENSE for details.
\ No newline at end of file
diff --git a/documentation/embedded-building.md b/documentation/embedded-building.md
new file mode 100644
index 0000000..c2220ce
--- /dev/null
+++ b/documentation/embedded-building.md
@@ -0,0 +1,45 @@
+# 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 platform that can run SBT (referred to as the host)
+
+## 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 procdure
+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=".:/home/<folder containing libflow.so>". E.g. ```java -Djava.library.path=".:/home/<folder containing libflow.so>" -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 and /usr/local/lib