diff options
-rw-r--r-- | README.md | 58 |
1 files changed, 47 insertions, 11 deletions
@@ -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 |