Skip to content

Docs #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 7, 2021
Merged

Docs #280

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
File renamed without changes.
144 changes: 19 additions & 125 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,46 @@
# TensorFlow for Java

## Welcome to the Java world of TensorFlow!

TensorFlow can run on any JVM for building, training and running machine learning models. It comes with
<table class="tfo-notebook-buttons" align="left">
<td>
<a target="_blank" href="https://www.tensorflow.org/jvm"><img src="https://www.tensorflow.org/images/tf_logo_32px.png" />View on TensorFlow.org</a>
</td>
<td>
<a target="_blank" href="https://github.com/tensorflow/java"><img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />View GitHub repository</a>
</td>
</table>

TensorFlow Java can run on any JVM for building, training and running machine learning models. It comes with
a series of utilities and frameworks that help achieve most of the tasks common to data scientists
and developers working in this domain. Java and other JVM languages, such as Scala or Kotlin, are
frequently used in small-to-large enterprises all over the world, which makes TensorFlow a strategic
choice for adopting machine learning at a large scale.

## This Repository
## The Repository

In the early days, the Java language bindings for TensorFlow were hosted in the [main repository](https://github.com/tensorflow/tensorflow)
In the early days, the Java language bindings for TensorFlow were hosted in the
[main TensorFlow repository](https://github.com/tensorflow/tensorflow)
and released only when a new version of the core library was ready to be distributed, which happens only
a few times a year. Now, all Java-related code has been moved to this repository so that it can evolve and
be released independently from official TensorFlow releases. In addition, most of the build tasks have been
migrated from Bazel to Maven, which is more familiar for most Java developers.

The following describes the layout of the repository and its different artifacts:

* `tensorflow-core`
* [tensorflow-core](https://github.com/tensorflow/java/tree/master/tensorflow-core)
* All artifacts that build up the core language bindings of TensorFlow for Java
* Intended audience: projects that provide their own APIs or frameworks on top of
TensorFlow and just want a thin layer to access the TensorFlow runtime from the JVM
* `tensorflow-framework`

* [tensorflow-framework](https://github.com/tensorflow/java/tree/master/tensorflow-framework)
* Primary API for building and training neural networks with TensorFlow
* Intended audience: neural network developers
* For more information: [tensorflow-framework/README.md](tensorflow-framework/README.md)

* `ndarray`

* [ndarray](https://github.com/tensorflow/java/tree/master/ndarray)
* Generic utility library for n-dimensional data I/O operations
* Used by TensorFlow but does not depend on TensorFlow
* Intended audience: any developer who needs a Java n-dimensional array implementation, whether or not they
use it with TensorFlow


## Communication

Expand All @@ -42,117 +49,4 @@ by subscribing to the [[email protected]](https://groups.google.com/a/tensorflo
mailing list, or you can simply send pull requests and raise issues to this repository.
There is also a [sig-jvm Gitter channel](https://gitter.im/tensorflow/sig-jvm).

## Building Sources

See [CONTRIBUTING.md](CONTRIBUTING.md#building).

## Using Maven Artifacts

To include TensorFlow in your Maven application, you first need to add a dependency on either the
`tensorflow-core` or `tensorflow-core-platform` artifacts. The former could be included multiple times
for different targeted systems by their classifiers, while the later includes them as dependencies for
`linux-x86_64`, `macosx-x86_64`, and `windows-x86_64`, with more to come in the future. There are also
`tensorflow-core-platform-mkl`, `tensorflow-core-platform-gpu`, and `tensorflow-core-platform-mkl-gpu`
artifacts that depend on artifacts with MKL and/or CUDA support enabled.

For example, for building a JAR that uses TensorFlow and is targeted to be deployed only on Linux
systems, you should add the following dependencies:
```xml
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-api</artifactId>
<version>0.3.1</version>
</dependency>
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-api</artifactId>
<version>0.3.1</version>
<classifier>linux-x86_64${javacpp.platform.extension}</classifier>
</dependency>
```

On the other hand, if you plan to deploy your JAR on more platforms, you need additional
native dependencies as follows:
```xml
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-api</artifactId>
<version>0.3.1</version>
</dependency>
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-api</artifactId>
<version>0.3.1</version>
<classifier>linux-x86_64${javacpp.platform.extension}</classifier>
</dependency>
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-api</artifactId>
<version>0.3.1</version>
<classifier>macosx-x86_64${javacpp.platform.extension}</classifier>
</dependency>
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-api</artifactId>
<version>0.3.1</version>
<classifier>windows-x86_64${javacpp.platform.extension}</classifier>
</dependency>
```

In some cases, pre-configured starter artifacts can help to automatically include all versions of
the native library for a given configuration. For example, the `tensorflow-core-platform`,
`tensorflow-core-platform-mkl`, `tensorflow-core-platform-gpu`, or `tensorflow-core-platform-mkl-gpu`
artifact includes transitively all the artifacts above as a single dependency:
```xml
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-platform${javacpp.platform.extension}</artifactId>
<version>0.3.1</version>
</dependency>
```

Be aware though that the native library is quite large and including too many versions of it may
significantly increase the size of your JAR. So it is good practice to limit your dependencies to
the platforms you are targeting. For this purpose the `-platform` artifacts include profiles that follow
the conventions established on this page:
* [Reducing the Number of Dependencies](https://github.com/bytedeco/javacpp-presets/wiki/Reducing-the-Number-of-Dependencies)

### Snapshots

Snapshots of TensorFlow Java artifacts are automatically distributed after each update in the code. To use them, you need
to add Sonatype OSS repository in your pom.xml, like the following

```xml
<repositories>
<repository>
<id>tensorflow-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
<dependencies>
<!-- Example of dependency, see section above for more options -->
<dependency>
<groupId>org.tensorflow</groupId>
<artifactId>tensorflow-core-platform</artifactId>
<version>0.4.0-SNAPSHOT</version>
</dependency>
</dependencies>
```

## TensorFlow Version Support

This table shows the mapping between different version of TensorFlow for Java and the core runtime libraries.

| TensorFlow Java Version | TensorFlow Version |
| ------------- | ------------- |
| 0.2.0 | 2.3.1 |
| 0.3.0 | 2.4.1 |
| 0.3.1 | 2.4.1 |
| 0.4.0-SNAPSHOT | 2.4.1

## How to Contribute?

Contributions are welcome, guidelines are located in [CONTRIBUTING.md](CONTRIBUTING.md).
2 changes: 1 addition & 1 deletion docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ the following
*Note: Only official builds distributed by TensorFlow are supported by its
maintainers and custom builds should be used at the user's risk.*

# Example Program
## Example Program

This example shows how to build an Apache Maven project with TensorFlow. First,
add the TensorFlow dependency to the project's `pom.xml` file:
Expand Down