From 6ca90e6b240a00cc8a0697763261f78f9cffdd21 Mon Sep 17 00:00:00 2001 From: Jakob Odersky Date: Sun, 24 Jan 2016 13:42:40 -0800 Subject: Update dicumentation --- site/jekyll/documentation/developer.md | 85 ++++++++++++++++++++++++++++++++++ site/jekyll/documentation/index.md | 11 +++-- site/jekyll/documentation/manual.md | 74 +---------------------------- site/jekyll/downloads/index.md | 27 ++--------- 4 files changed, 96 insertions(+), 101 deletions(-) create mode 100644 site/jekyll/documentation/developer.md (limited to 'site/jekyll') diff --git a/site/jekyll/documentation/developer.md b/site/jekyll/documentation/developer.md new file mode 100644 index 0000000..49efe08 --- /dev/null +++ b/site/jekyll/documentation/developer.md @@ -0,0 +1,85 @@ +--- +layout: page +title: Developer Guide +--- +# Building from Source +A complete build of flow involves two parts + +1. Building Scala sources (the front-end), resulting in a platform independent artifact (i.e. a jar file). + +2. Building C sources (the back-end), yielding a native library that may only be used on systems resembling the platform for which it was compiled. + +Both steps are independent, their only interaction being a header file generated by the JDK utility `javah` (see `sbt javah` for details), and may therefore be built in any order. + +## Building Scala Sources +Run `sbt flow-main/packageBin` in the base directory. This simply compiles Scala sources as with any standard sbt project and packages the resulting class files in a jar. + +## Building Native Sources +The back-end is managed by GNU Autotools and all relevant files are contained in `flow-native`. + +{::options parse_block_html="true" /} + + +### Build Process + +Several steps are involved in producing the native library: + +1. Bootstrap the build (run this once, if `./configure` does not exist). + + 1. Check availability of dependencies: autotools and libtool (on Debian-based systems run `apt-get install build-essential autoconf automake libtool`) + 2. Run `./bootstrap` + +2. Compile + + 1. Check availability of dependencies: C compiler and JDK (1.8 or above) + 2. Run `./configure && make`. + *Note: should you encounter an error about a missing "jni.h" file, try setting the JAVA_HOME environment variable to point to base path of your JDK installation.* + +3. Install + + The native library is now ready and can be: + + - copied to a local directory: `DESTDIR=$(pwd)/ make install` + + - installed system-wide: `make install` + + - put into a "fat" jar, useful for dependency management with SBT (see next section) + +### Creating a Fat Jar +The native library produced in the previous step may be bundled into a "fat" jar so that it can be included in SBT projects through its regular dependency mechanisms. In this process, sbt basically acts as a wrapper script around Autotools, calling the native build process and packaging generated libraries. Running `sbt flow-native/packageBin` in the base directory produces the fat jar in `flow-native/target`. + +Note: an important feature of fat jars is to include native libraries for several platforms. To copy binaries compiled on other platforms to the fat jar, place them in a subfolder of `flow-native/lib_native`. The subfolder should have the name `$(arch)-$(kernel)`, where `arch` and `kernel` are, respectively, the lower-case values returned by `uname -m` and `uname -s`. + +### Note About Versioning +The project and package versions follow a [semantic](http://semver.org/) pattern: `M.m.p`, where + +- `M` is the major version, representing backwards incompatible changes + +- `m` is the minor version, indicating backwards compatible changes such as new feature additions + +- `p` is the patch number, representing internal modifications such as bug-fixes + +Usually (following most Linux distribution's conventions), shared libraries produced by a project `name` of version `M.m.p` are named `libname.so.M.m.p`. However, since when accessing shared libraries through the JVM, only the `name` can be specified and no particular version, the convention adopted by flow is to append `M` to the library name and always keep the major version at zero. E.g. `libflow.so.3.1.2` becomes `libflow3.so.0.1.2`. + +# Publishing and Releasing +The release process managed with the `sbt-release` plugin. See 'project/Release.scala' for a description of the various steps involved. + +Here are some important notes on creating a release: + +- During a release, only readily available libraries in `lib_native` are packaged into the fat jar, no local compilation is performed. The rationale behind this is that while native libraries rarely change, they are tied to the version of libc of the compiling system. Since the releases are mostly done on a cutting-edge OS, compiling native libraries locally could break compatibility with older systems. + +- Currently, the release script does not handle uploading the native libraries archive (don't confuse this with the fat jar, which is uploaded). If creating a release that changed the native libraries or added support for more platforms, creating and uploading a new native archive must be done manually. + +- Don't forget to update the website after creating a new release. + diff --git a/site/jekyll/documentation/index.md b/site/jekyll/documentation/index.md index ef35414..56c83d6 100644 --- a/site/jekyll/documentation/index.md +++ b/site/jekyll/documentation/index.md @@ -10,19 +10,22 @@ Start by reading the manual and checking out some examples. - [Examples](https://github.com/jodersky/flow/tree/master/flow-samples) See some very simple, working demo applications. - + - [API documentation]({{site.url}}/latest/api#com.github.jodersky.flow.Serial$) Browse flow's API. - + +- [Developer Guide](developer.html) + Instructions on building and publishing flow. + ## Help Have a question or suggestion? Found a bug? There are several channels to get help. - [Issues](https://github.com/jodersky/flow/issues) Check known issues or file a new one. This is also the place to go for long questions or propositions. - + - [Chat](https://gitter.im/jodersky/flow) Gitter chat for simple inquiries. - + ## Use cases Get inspired by some real projects that use flow. diff --git a/site/jekyll/documentation/manual.md b/site/jekyll/documentation/manual.md index 918f206..c796992 100644 --- a/site/jekyll/documentation/manual.md +++ b/site/jekyll/documentation/manual.md @@ -34,7 +34,7 @@ libraryDependencies += "com.github.jodersky" % "flow-native" % "{{site.data.curr 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. ### Maximum Portability -First, obtain a copy of the native library, either by [building flow](#building-from-source) or by [downloading]({{site.url}}/downloads) a precompiled version. In order to work with this version of flow, native libraries need to be of major version {{site.data.current.native_version.major}} and minor version greater or equal to {{site.data.current.native_version.minor}}. +First, obtain a copy of the native library, either by [building flow](./developer) or by [downloading]({{site.url}}/downloads) a precompiled version. In order to work with this version of flow, native libraries need to be of major version {{site.data.current.native_version.major}} and minor version greater or equal to {{site.data.current.native_version.minor}}. Second, 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: @@ -183,75 +183,3 @@ Note that the manager has a deathwatch on every subscribed client. Hence, should ## Requirements Flow uses Java's `WatchService`s under the hood, therefore a Java runtime of a version of at least 1.7 is required. - ---- - -# Building from Source -A complete build of flow involves two parts - -1. Building Scala sources (the front-end), resulting in a platform independent artifact (i.e. a jar file). - -2. Building C sources (the back-end), yielding a native library that may only be used on systems resembling the platform for which it was compiled. - -Both steps are independent, their only interaction being a header file generated by the JDK utility `javah` (see `sbt javah` for details), and may therefore be built in any order. - -## Building Scala Sources -Run `sbt flow-main/packageBin` in the base directory. This simply compiles Scala sources as with any standard sbt project and packages the resulting class files in a jar. - -## Building Native Sources -The back-end is managed by GNU Autotools and all relevant files are contained in `flow-native`. - -{::options parse_block_html="true" /} - - -### Build Process - -Several steps are involved in producing the native library: - -1. Bootstrap the build (run this once, if `./configure` does not exist). - - 1. Check availability of dependencies: autotools and libtool (on Debian-based systems run `apt-get install build-essential autoconf automake libtool`) - 2. Run `./bootstrap` - -2. Compile - - 1. Check availability of dependencies: C compiler and JDK (1.8 or above) - 2. Run `./configure && make`. - *Note: should you encounter an error about a missing "jni.h" file, try setting the JAVA_HOME environment variable to point to base path of your JDK installation.* - -3. Install - - The native library is now ready and can be: - - - copied to a local directory: `DESTDIR=$(pwd)/ make install` - - - installed system-wide: `make install` - - - put into a "fat" jar, useful for dependency management with SBT (see next section) - -### Creating a Fat Jar -The native library produced in the previous step may be bundled into a "fat" jar so that it can be included in SBT projects through its regular dependency mechanisms. In this process, SBT basically acts as a wrapper script around Autotools, calling the native build process and packaging generated libraries. Running `sbt flow-native/packageBin` in the base directory produces the fat jar in `flow-native/target`. - -Note: an important feature of fat jars is to include native libraries for several platforms. To copy binaries compiled on other platforms to the fat jar, place them in a subfolder of `flow-native/lib_native`. The subfolder should have the name `com/github/jodersky/flow/native/$(arch)-$(kernel)`, where `arch` and `kernel` are, respectively, the lower-case values returned by `uname -m` and `uname -s`. - -### Note About Versioning -The project and package versions follow a [semantic](http://semver.org/) pattern: `M.m.p`, where - -- `M` is the major version, representing backwards incompatible changes - -- `m` is the minor version, indicating backwards compatible changes such as new feature additions - -- `p` is the patch number, representing internal modifications such as bug-fixes - -Usually (following most Linux distribution's conventions), shared libraries produced by a project `name` of version `M.m.p` are named `libname.so.M.m.p`. However, since when accessing shared libraries through the JVM, only the `name` can be specified and no particular version, the convention adopted by flow is to append `M` to the library name and always keep the major version at zero. E.g. `libflow.so.3.1.2` becomes `libflow3.so.0.1.2`. diff --git a/site/jekyll/downloads/index.md b/site/jekyll/downloads/index.md index 9bb1b49..dd2569c 100644 --- a/site/jekyll/downloads/index.md +++ b/site/jekyll/downloads/index.md @@ -22,17 +22,9 @@ libraryDependencies += "com.github.jodersky" % "flow-native" % "{{site.data.curr ### Archives -- Main Jar -[.jar (scala 2.11)](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow_2.11/2.4.0-M2/flow_2.11-2.4.0-M2.jar) -[.asc (signature)](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow_2.11/2.4.0-M2/flow_2.11-2.4.0-M2.jar.asc) - -- Native Jar -[.jar](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow-native/2.4.0-M2/flow-native-2.4.0-M2.jar) -[.asc (signature)](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow-native/2.4.0-M2/flow-native-2.4.0-M2.jar.asc) - - Native Libraries -[.tar.gz](https://bintray.com/artifact/download/jodersky/generic/flow-native-libraries-3.0.1.tar.gz) -[.asc (signature)](https://bintray.com/artifact/download/jodersky/generic/flow-native-libraries-3.0.1.tar.gz.asc) +[.tar.gz](https://bintray.com/artifact/download/jodersky/generic/flow-native-libraries-{{site.data.current.native_version.major}}.{{site.data.current.native_version.minor}}.{{site.data.current.native_version.patch}}.tar.gz) +[.asc (signature)](https://bintray.com/artifact/download/jodersky/generic/flow-native-libraries-{{site.data.current.native_version.major}}.{{site.data.current.native_version.minor}}.{{site.data.current.native_version.patch}}.tar.gz.asc) @@ -64,20 +56,7 @@ Flow is POSIX compatible so it can be built for a lot more platforms.

Consult the release notes for important changes. ## Requirements -Flow depends on Akka 2.4 and requires a Java runtime version of 1.8. +Flow depends on Akka 2.4 and requires a Java runtime version of 1.8. It is released for Scala binary versions 2.11 and 2.12. ## Previous Versions - -### 2.3.1 - -- Main Jar -[.jar (scala 2.11)](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow_2.11/2.3.1/flow_2.11-2.3.1.jar) -[.asc (signature)](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow_2.11/2.3.1/flow_2.11-2.3.1.jar.asc) - -- Native Jar -[.jar](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow-native/2.3.1/flow-native-2.3.1.jar) -[.asc (signature)](https://bintray.com/artifact/download/jodersky/maven/com/github/jodersky/flow-native/2.3.1/flow-native-2.3.1.jar.asc) - - -### Older Releases Archived releases are available in GitHub releases. -- cgit v1.2.3