update README

1 files changed, 47 insertions, 11 deletions

diff --git a/README.md b/README.md
index 1e3162c..ae06433 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ Clone the repository and run `sbt flow-main/publish-local` to publish the librar
 
 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-sample-<sample_name>` and typing `run`. Be sure to connect a serial device before running an example.
 
-As flow integrates into the Akka-IO framework, a good resource on its "spirit" is the framework's documentation at http://doc.akka.io/docs/akka/2.2.0-RC2/scala/io.html
+As flow integrates into the Akka-IO framework, a good resource on its general "spirit" is the framework's documentation at http://doc.akka.io/docs/akka/2.2.0-RC2/scala/io.html
         
 ### Currently supported platforms
 
@@ -25,19 +25,55 @@ As flow integrates into the Akka-IO framework, a good resource on its "spirit" i
 
 
 ## Build
-The building of flow involves two parts
- 1. compiling scala sources 9as in a regular project0
- 2. compiling native sources that interface with system calls
+A complete build of flow involves two parts
+
+ 1. compiling scala sources (as in a regular project)
+ 2. compiling native sources
+ 
+As any java 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.
 
-### Project structure
     flow
-    ├── flow-main //main scala/java sources
-    ├── flow-native //native sources
-    │   ├── include //general headers
-    │   └── unix    //source code for unix-like systems
+    ├── flow-binaries
+    ├── flow-main
+    ├── flow-native
+    │   ├── include
+    │   └── unix
     ├── flow-samples
-    ├── project
-    └── README.md
+    └── 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:
+   - 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>`
+ 
+
+With this structure in mind, building a complete distribution of flow involves (sbt commands are given in code tags):
+
+ 1. compiling java/scala sources: `flow-main/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-main/package`
+ This copies the latest 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
 Copyright (c) 2013 by Jakob Odersky