Refactor to multi-plugin build

1 files changed, 74 insertions, 39 deletions

diff --git a/README.md b/README.md
index 7f3c6c3..502dfa7 100644
--- a/README.md
+++ b/README.md
@@ -1,62 +1,97 @@
-# SBT-JNI
-Making JNI tolerable.
-
-Work in progress...
+[Work in progress]
 
-## Overview of JNI
-Java Native Interface (JNI), is a standard interface to allow programs written in a JVM language to interact with native code. Creating a program that uses JNI is usually a multi-step process:
-
-1. The JVM side of the program is written (in Java or Scala for example) and interfacing methods declared as native.
-2. JVM sources are compiled.
-3. The program "javah" is run to generate C header files for classes containing native declarations.
-4. These header files may be included from actual native source files that implement the native methods.
-5. Native sources are compiled into a native library.
+# SBT-JNI
 
-Running the program also requires special steps:
+A suite of plugins for simplifying creation and distribution of JNI programs.
 
-1. Supply the native library to the program's library path.
-2. Run the program, making sure to load the native library (through `System.load()`) before calling any native methods.
+## Motivation
+Java Native Interface (JNI), is a standard interface to allow programs written in a JVM language to interact with native code. Such programs can be divided into two logical parts: the JVM part, consisting of source files that will generate java bytecode (e.g. Scala or Java), and the native part, consisting of source files that will be compiled down to machine-native code (e.g. C, C++ or assembly). Interaction between the two parts is managed by header files generated through the `javah` utility.
 
-Finally, since platform independence is lost with native libraries, publishing an application or library becomes harder:
+Using native code can be beneficial in some situations, it can for example provide performance gains or otherwise infeasable features such as system-level interaction with peripherals. However, it also adds a few complexities, notably:
 
-1. Native libraries must be compiled and made available for all supported platforms.
-2. Loading the correct library on a given platform has to be managed somehow.
+- Compilation: the project is divided into two parts, each of which require separate compilation. Furthermore, header generation with `javah` has to be dealt with.
+- Portability: native binaries only run on the platform on which they were compiled.
+- Distribution: native binaries must be made available and packaged for every supported platform.
 
-All in all, using JNI impairs platform-independence and thus a considerable amount of the JVM's advantages regarding ease of development and distribution.
+The second point, portability, is inherent to JNI and thus unavoidable. However the first and last points can be greatly simplified with the help of build tools.
 
 ## Plugin Overview
-As described in the previous paragraph, using JNI adds a number of burdens to developing applications. The problems can be divided into two groups, both of which this plugin attempts to address:
+This project consists of 4 autoplugins that aim to solve the difficulties in compiling and distributing JNI programs. These plugins provide two functionalities (compiling and distributing) for two parts of a project (JVM and native):
 
-- Build problems, related to the manual work involved with synchronizing JVM and native sources and running applications locally.
-- Distribution problems, related to the way libraries and applications can be deployed.
+Plugins
+--------------|-----------------|-------------
+Functionality | JVM part        | Native part
+--------------|-----------------|-------------
+Compiling     | JniJavah        | JniNative
+Packaging     | JniLoading      | JniPackaging
 
-[how the plugin addresses issues]
-[sbt wrapper for native build tools]
+A project using this suite of plugins must be divided into two sub-projects, corresponding to the two parts: one that will contain JVM sources and one that will contain native sources.
 
-## Usage
+The reason for dividing a project into two subprojects is two-fold: it enables flexible plugging of native sources and also integrates easily into the existing maven ecosystem. Adding the native binaries as additional artifacts has issues with scala versioning.
 
-Depend on plugin `project/plugins.sbt`:
+## Usage
+Add plugin dependency. In `project/plugins.sbt`:
 ```scala
-addSbtPlugin("ch.jodersky" % "sbt-jni" % "0.2")
+addSbtPlugin("ch.jodersky" % "sbt-jni" % "0.3")
 ```
 
-Create sbt project containing JVM sources:
-```scala
-lazy val main = Project("main", file("main)).enablePlugins(JniJvm).dependsOn(native % Runtime) 
-```
+Define sub-projects for JVM and native sources. In `myproject/build.sbt`:
 
-Create sbt project containing native sources:
 ```scala
-lazy val native = Project("native", file("native")).dependsOn(JniNative) 
+lazy val core = project in file("myproject-core") // contains regular jvm sources and @native methods
+lazy val native = project in file("myproject-native") // contains native sources
 ```
 
-### Keys
+Select plugins to enable on sub-projects:
 
-```
-javah
-jni
-```
+- In `myproject-core/build.sbt`:
+
+    ```scala
+    //enablePlugin(JniJavah) // this plugin is added to all JVM projects by default
+    enablePlugin(JniLoading)
+    ```
+
+- In `myproject-native/build.sbt`:
+
+    ```scala
+    enablePlugin(JniNative)
+    //enablePlugin(JniPackaging) // this plugin is added to all projects using JniNative by default
+    ```
+
+Note that some plugins are added by default. To disable their functionality (for example if you don't wish to package native libraries), add `disablePlugin(<plugin>)` to the corresponding build definition.
+
+
+## Plugin Details
+The following gives a detailed description about the various JNI plugins and the ways to customize their behaviour.
+
+### Javah
+*JVM sub-projects*
+
+#### Functionality
+Adds a `javah` task to generate header files for classes containing `@native` methods.
+
+#### Customization
+Change target to point to `include` directory of native sources: `target in javah := file("myproject-native") / "src" / "include"`
+
+
+### JniNative
+*Native sub-projects*
+
+#### Functionality
+Provides sbt tasks to call into a native build system such as Automake or CMake. Run `sbt nativeCompile` to compile native sources.
+
+#### Customization
+Change source directory to point to a directory containing the native build definition. Supported build tools are:
+
+- Automake
+- CMake
+
+*Make sure the native build configurations respect the arguments and output directories as specified in the [native build templates](templates)*
+
+### JniLoading
+*JVM sub-projects*
 
-### Common settings
+### JniPackaging
+*Native sub-projects*
 
 ## Examples