diff options
Diffstat (limited to 'documentation/manual.html')
| -rw-r--r-- | documentation/manual.html | 117 |
1 files changed, 3 insertions, 114 deletions
diff --git a/documentation/manual.html b/documentation/manual.html index 2d402c7..6b5a915 100644 --- a/documentation/manual.html +++ b/documentation/manual.html @@ -70,23 +70,12 @@ <li><a href="#requirements" id="markdown-toc-requirements">Requirements</a></li> </ul> </li> - <li><a href="#building-from-source" id="markdown-toc-building-from-source">Building from Source</a> <ul> - <li><a href="#building-scala-sources" id="markdown-toc-building-scala-sources">Building Scala Sources</a></li> - <li><a href="#building-native-sources" id="markdown-toc-building-native-sources">Building Native Sources</a> <ul> - <li><a href="#aside-autotools-introduction" id="markdown-toc-aside-autotools-introduction">Aside: Autotools Introduction</a></li> - <li><a href="#build-process" id="markdown-toc-build-process">Build Process</a></li> - <li><a href="#creating-a-fat-jar" id="markdown-toc-creating-a-fat-jar">Creating a Fat Jar</a></li> - <li><a href="#note-about-versioning" id="markdown-toc-note-about-versioning">Note About Versioning</a></li> - </ul> - </li> - </ul> - </li> </ul> <h1 id="getting-started">Getting Started</h1> <p>Flow uses SBT as build system. To get started, include a dependency to flow in your project:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="n">libraryDependencies</span> <span class="o">+=</span> <span class="s">"com.github.jodersky"</span> <span class="o">%%</span> <span class="s">"flow"</span> <span class="o">%</span> <span class="s">"2.4.0-M2"</span> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="n">libraryDependencies</span> <span class="o">+=</span> <span class="s">"com.github.jodersky"</span> <span class="o">%%</span> <span class="s">"flow"</span> <span class="o">%</span> <span class="s">"2.4.0"</span> </code></pre> </div> @@ -109,14 +98,14 @@ <h3 id="the-easy-way">The Easy Way</h3> <p>In case your OS/architecture combination is present in the “supported platforms” table in the downloads section, add a second dependency to your project:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="n">libraryDependencies</span> <span class="o">+=</span> <span class="s">"com.github.jodersky"</span> <span class="o">%</span> <span class="s">"flow-native"</span> <span class="o">%</span> <span class="s">"2.4.0-M2"</span> <span class="o">%</span> <span class="s">"runtime"</span> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="n">libraryDependencies</span> <span class="o">+=</span> <span class="s">"com.github.jodersky"</span> <span class="o">%</span> <span class="s">"flow-native"</span> <span class="o">%</span> <span class="s">"2.4.0"</span> <span class="o">%</span> <span class="s">"runtime"</span> </code></pre> </div> <p>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.</p> <h3 id="maximum-portability">Maximum Portability</h3> -<p>First, obtain a copy of the native library, either by <a href="#building-from-source">building flow</a> or by <a href="https://jodersky.github.io/flow/downloads">downloading</a> a precompiled version. In order to work with this version of flow, native libraries need to be of major version 3 and minor version greater or equal to 0.</p> +<p>First, obtain a copy of the native library, either by <a href="./developer">building flow</a> or by <a href="https://jodersky.github.io/flow/downloads">downloading</a> a precompiled version. In order to work with this version of flow, native libraries need to be of major version 3 and minor version greater or equal to 0.</p> <p>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:</p> @@ -285,106 +274,6 @@ the client on new files.</p> <h2 id="requirements">Requirements</h2> <p>Flow uses Java’s <code class="highlighter-rouge">WatchService</code>s under the hood, therefore a Java runtime of a version of at least 1.7 is required.</p> -<hr /> - -<h1 id="building-from-source">Building from Source</h1> -<p>A complete build of flow involves two parts</p> - -<ol> - <li> - <p>Building Scala sources (the front-end), resulting in a platform independent artifact (i.e. a jar file).</p> - </li> - <li> - <p>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.</p> - </li> -</ol> - -<p>Both steps are independent, their only interaction being a header file generated by the JDK utility <code class="highlighter-rouge">javah</code> (see <code class="highlighter-rouge">sbt javah</code> for details), and may therefore be built in any order.</p> - -<h2 id="building-scala-sources">Building Scala Sources</h2> -<p>Run <code class="highlighter-rouge">sbt flow-main/packageBin</code> in the base directory. This simply compiles Scala sources as with any standard sbt project and packages the resulting class files in a jar.</p> - -<h2 id="building-native-sources">Building Native Sources</h2> -<p>The back-end is managed by GNU Autotools and all relevant files are contained in <code class="highlighter-rouge">flow-native</code>.</p> - -<aside class="notice"> - <h3 id="aside-autotools-introduction">Aside: Autotools Introduction</h3> - <p>Autotools is a suite of programs constituting a sort of “meta-build system”. It is used to generate a platform-independent build script known as <code class="highlighter-rouge">./configure</code>, which, when run, will analyze the current system (search for a C compiler, required libraries etc) and produce a <code class="highlighter-rouge">Makefile</code>. The makefile in turn is system-specific and can be used to create the final binary. In summary the build process is as follows:</p> - - <ol> - <li>Autotools (specifically the program <code class="highlighter-rouge">autoreconf</code>) generates <code class="highlighter-rouge">./configure</code>, this happens on the developer’s machine</li> - <li><code class="highlighter-rouge">./configure</code> is run on the host computer</li> - <li><code class="highlighter-rouge">make</code> is run to produce a binary, also on the host computer</li> - </ol> - - <p>In a typical, source-controlled repository, only a bootstrapping script that calls Autotools is checked into version control. However, source <em>releases</em> include the generated <code class="highlighter-rouge">./configure</code> script. An end-user then downloads a source release and only has to run <code class="highlighter-rouge">./configure && make</code>.</p> - - <p>However, since flow does currently not provide source releases (not to be confused with source repository or Git tags), the developer’s machine is the same as the host machine and so the bootstrapping process always needs to be performed.</p> -</aside> - -<h3 id="build-process">Build Process</h3> - -<p>Several steps are involved in producing the native library:</p> - -<ol> - <li> - <p>Bootstrap the build (run this once, if <code class="highlighter-rouge">./configure</code> does not exist).</p> - - <ol> - <li>Check availability of dependencies: autotools and libtool (on Debian-based systems run <code class="highlighter-rouge">apt-get install build-essential autoconf automake libtool</code>)</li> - <li>Run <code class="highlighter-rouge">./bootstrap</code></li> - </ol> - </li> - <li> - <p>Compile</p> - - <ol> - <li>Check availability of dependencies: C compiler and JDK (1.8 or above)</li> - <li>Run <code class="highlighter-rouge">./configure && make</code>. -<em>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.</em></li> - </ol> - </li> - <li> - <p>Install</p> - - <p>The native library is now ready and can be:</p> - - <ul> - <li> - <p>copied to a local directory: <code class="highlighter-rouge">DESTDIR=$(pwd)/<directory> make install</code></p> - </li> - <li> - <p>installed system-wide: <code class="highlighter-rouge">make install</code></p> - </li> - <li> - <p>put into a “fat” jar, useful for dependency management with SBT (see next section)</p> - </li> - </ul> - </li> -</ol> - -<h3 id="creating-a-fat-jar">Creating a Fat Jar</h3> -<p>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 <code class="highlighter-rouge">sbt flow-native/packageBin</code> in the base directory produces the fat jar in <code class="highlighter-rouge">flow-native/target</code>.</p> - -<p>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 <code class="highlighter-rouge">flow-native/lib_native</code>. The subfolder should have the name <code class="highlighter-rouge">com/github/jodersky/flow/native/$(arch)-$(kernel)</code>, where <code class="highlighter-rouge">arch</code> and <code class="highlighter-rouge">kernel</code> are, respectively, the lower-case values returned by <code class="highlighter-rouge">uname -m</code> and <code class="highlighter-rouge">uname -s</code>.</p> - -<h3 id="note-about-versioning">Note About Versioning</h3> -<p>The project and package versions follow a <a href="http://semver.org/">semantic</a> pattern: <code class="highlighter-rouge">M.m.p</code>, where</p> - -<ul> - <li> - <p><code class="highlighter-rouge">M</code> is the major version, representing backwards incompatible changes</p> - </li> - <li> - <p><code class="highlighter-rouge">m</code> is the minor version, indicating backwards compatible changes such as new feature additions</p> - </li> - <li> - <p><code class="highlighter-rouge">p</code> is the patch number, representing internal modifications such as bug-fixes</p> - </li> -</ul> - -<p>Usually (following most Linux distribution’s conventions), shared libraries produced by a project <code class="highlighter-rouge">name</code> of version <code class="highlighter-rouge">M.m.p</code> are named <code class="highlighter-rouge">libname.so.M.m.p</code>. However, since when accessing shared libraries through the JVM, only the <code class="highlighter-rouge">name</code> can be specified and no particular version, the convention adopted by flow is to append <code class="highlighter-rouge">M</code> to the library name and always keep the major version at zero. E.g. <code class="highlighter-rouge">libflow.so.3.1.2</code> becomes <code class="highlighter-rouge">libflow3.so.0.1.2</code>.</p> - </div> |