plus-vision / rust

Rust language bindings for TensorFlow

Rust Binding

TensorFlow Rust provides idiomatic Rust language bindings for TensorFlow.

Notice: This project is still under active development and not guaranteed to have a stable API. This is especially true because the underlying TensorFlow C API has not yet been stabilized as well.

• Documentation
• TensorFlow website
• TensorFlow GitHub page

Getting Started

Since this crate depends on the TensorFlow C API, it needs to be compiled first. This crate will automatically compile TensorFlow for you, but it is also possible to manually install TensorFlow and the crate will pick it up accordingly.

Prerequisites

The following dependencies are needed to compile and build this crate (assuming TensorFlow itself should also be compiled transparently):

• git
• bazel
• Python Dependencies numpy, dev, pip and wheel
• Optionally, CUDA packages to support GPU-based processing

The TensorFlow website provides detailed instructions on how to obtain and install said dependencies, so if you are unsure please check out the docs for further details.

Usage

Add this to your Cargo.toml:

[dependencies]
tensorflow = "0.8.0"

and this to your crate root:

extern crate tensorflow;

Then run cargo build -j 1. The tensorflow-sys crate's build.rs now either downloads a pre-built, basic CPU only binary (the default) or compiles TensorFlow if forced to by an environment variable. If TensorFlow is compiled during this process, since the full compilation is very memory intensive, we recommend using the -j 1 flag which tells cargo to use only one task, which in turn tells TensorFlow to build with only one task. Though, if you have a lot of RAM, you can obviously use a higher value.

To include the especially unstable API (which is currently the expr module), use --features tensorflow_unstable.

For now, please see the Examples for more details on how to use this binding.

Manual TensorFlow Compilation

If you don't want to build TensorFlow after every cargo clean or you want to work against unreleased/unsupported TensorFlow versions, manual compilation is the way to go.

See TensorFlow from source first. The Python/pip steps are not necessary, but building tensorflow:libtensorflow.so is.

In short:

1. Install SWIG and NumPy. The version from your distro's package manager should be fine for these two.

2. Install Bazel, which you may need to do from source.

3. git clone https://github.com/tensorflow/tensorflow

4. cd tensorflow

5. ./configure

6. bazel build --compilation_mode=opt --copt=-march=native --jobs=1 tensorflow:libtensorflow.so

   Using --jobs=1 is recommended unless you have a lot of RAM, because TensorFlow's build is very memory intensive.

Copy $TENSORFLOW_SRC/bazel-bin/tensorflow/libtensorflow.so to /usr/local/lib. If this is not possible, add $TENSORFLOW_SRC/bazel-bin/tensorflow to LD_LIBRARY_PATH.

You may need to run ldconfig to reset ld's cache after copying libtensorflow.so.

macOS Note: Via Homebrew, you can just run brew install libtensorflow.

FAQ's

Why does the compiler say that parts of the API don't exist?

The especially unstable parts of the API (which is currently the expr modul) are feature-gated behind the feature tensorflow_unstable to prevent accidental use. See http://doc.crates.io/manifest.html#the-features-section. (We would prefer using an #[unstable] attribute, but that doesn't exist yet.)

Contributing

Developers and users are welcome to join #tensorflow-rust on irc.mozilla.org.

Please read the contribution guidelines on how to contribute code.

This is not an official Google product.

RFCs are issues tagged with RFC. Check them out and comment. Discussions are welcomed. After all, that is the purpose of Request For Comment!

License

This project is licensed under the terms of the Apache 2.0 license.