docs/features: add feature flags guide

Author: hobofan

FEATURE-FLAGS.md

@@ -0,0 +1,84 @@
+# Feature flags in Leaf
+
+## The problem(s)
+
+Supporting different backends is an important concept in Leaf.
+
+Optimally we would like to always have to choice of running Leaf on all backends.
+However in reality there are some tradeoffs that have to be made.
+
+One problem is that certain backends require the presence of special hardware to
+run (CUDA needs NVIDIA GPUs), or the libraries to address them are not present on
+the developers machine which is necessary for compilation.
+
+Another challenge is that not all backends have support for the same operations,
+which constrains neural networks with special requirements to the backends that
+provide those operations. Due to some limitations in the current version of Rust
+(1.7) allowing differently featured backends can not be that easily supported.
+See [Issue #81](https://github.com/autumnai/leaf/issues/81).
+
+## The solution
+
+Feature flags are a well known concept to add opt-in functionality that is
+not necessary for every use-case of a library and are a good solution to the first
+problem.
+Luckily, Cargo, Rust's package manager has built-in support for feature flags.
+
+A simple dependency with additional features enabled in a `Cargo.toml` looks like this:
+```toml
+[dependencies]
+leaf = { version = "0.2.0", features = ["cuda"] }
+```
+
+Feature flags are usually used in an additive way, but **some configurations
+of features for Leaf might actually take away some functionality**.
+We do this because we want the models to be portable across different backends,
+which is not possible if e.g. the CUDA backend supports Convolution layers while
+the Native backend doesn't. To make it possible we deactivate those features that
+are only available on a single backend, effectively "dumbing down" the backends.
+
+Example:
+- feature flags are `cuda` -> `Convolution` Layer **is available** since the CUDA backend provides the required traits and there is no native backend it has to be compatible with.
+- feature flags are `native` -> `Convolution` Layer **is not available** since the native backend does not provide the required traits and there are no other frameworks present.
+- feature flags are `native cuda` -> `Convolution` Layer **is not available** since the native backend does not provide the required traits, and the CUDA backend has been dumbed down.
+
+## Using the feature flags
+
+One thing we have ignored until now are default feature flags. Cargo allows to
+define a set of features that should be included in a package by default .
+One of the default feature flags of Leaf is the `native` flag. When looking at
+the above example you might notice that the only way we can unleash the full
+power of the CUDA backend is by deactivating the default `native` flag.
+Cargo allows us to do that either via the `--no-default-features` on the CLI or
+by specifying `default-feature = false` for a dependency in `Cargo.toml`.
+
+#### In your project
+
+The simple `Cargo.toml` example above works in simple cases but if you want
+to provide the same flexibility of backends in your project, you can reexport
+the feature flags.
+
+A typical example (including collenchyma) would look like this:
+```toml
+[dependencies]
+leaf = { version = "0.2.0", default-features = false }
+# the native collenchyma feature is neccesary to read/write tensors
+collenchyma = { version = "0.0.8", default-features = false, features = ["native"] }
+
+[features]
+default = ["native"]
+native  = ["leaf/native"]
+opencl  = ["leaf/opencl", "collenchyma/opencl"]
+cuda    = ["leaf/cuda", "collenchyma/cuda"]
+
+```
+
+Building your project would then look like this:
+```sh
+# having both native and CUDA backends
+# `native` is provided by default, and `cuda` explicitly specified by `--features cuda`
+cargo build --features cuda
+# unleashing CUDA
+# `native` default not included because of `--no-default-features`, and `cuda` explicitly specified by `--features cuda`
+cargo build --no-default-features --features cuda
+```

README.md

@@ -86,6 +86,8 @@ cuda    = ["leaf/cuda"]
 opencl  = ["leaf/opencl"]
 ```
 
+> More information on the use of feature flags in Leaf can be found in [FEATURE-FLAGS.md](./FEATURE-FLAGS.md)
+
 
 ## Examples
 
@@ -100,7 +102,7 @@ the install guide, clone this repoistory and then run
 
 ```bash
 # The examples currently require CUDA support.
-cargo run --release --example benchmarks
+cargo run --release --no-default-features --features cuda --example benchmarks alexnet
 ```
 
 [leaf-examples]: https://github.com/autumnai/leaf-examples

examples/benchmarks.rs

@@ -115,7 +115,7 @@ fn get_time_scale<'a>(sec: f64) -> (f64, &'a str) {
 #[cfg(feature="native")]
 fn bench_alexnet() {
     println!("Examples run only with CUDA support at the moment, because of missing native convolution implementation for the Collenchyma NN Plugin.");
-    println!("Try running with `cargo run --no-default-features --features cuda --example benchmarks alexnet`.");
+    println!("Try running with `cargo run --release --no-default-features --features cuda --example benchmarks alexnet`.");
 }
 #[cfg(all(feature="cuda", not(feature="native")))]
 fn bench_alexnet() {
@@ -197,7 +197,7 @@ fn bench_alexnet() {
 #[cfg(feature="native")]
 fn bench_overfeat() {
     println!("Examples run only with CUDA support at the moment, because of missing native convolution implementation for the Collenchyma NN Plugin.");
-    println!("Try running with `cargo run --no-default-features --features cuda --example benchmarks overfeat`.");
+    println!("Try running with `cargo run --release --no-default-features --features cuda --example benchmarks overfeat`.");
 }
 #[cfg(all(feature="cuda", not(feature="native")))]
 fn bench_overfeat() {
@@ -279,7 +279,7 @@ fn bench_overfeat() {
 #[cfg(feature="native")]
 fn bench_vgg_a() {
     println!("Examples run only with CUDA support at the moment, because of missing native convolution implementation for the Collenchyma NN Plugin.");
-    println!("Try running with `cargo run --no-default-features --features cuda --example benchmarks vgg`.");
+    println!("Try running with `cargo run --release --no-default-features --features cuda --example benchmarks vgg`.");
 }
 #[cfg(all(feature="cuda", not(feature="native")))]
 fn bench_vgg_a() {