1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
|
# 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.
## 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, 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.
# 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.
|
