Skip to content

Commit f47b640

Browse files
MarkDaoustMarkDaoust
authored
Create a docs directory and pull install instructions from tensorflow/docs. (#278)
* Copy install instructions from tensorflow/docs * Copy readme to docs/index.md * add _toc.yaml * rename lang_java to install
1 parent 7768333 commit f47b640

File tree

3 files changed

+395
-0
lines changed

3 files changed

+395
-0
lines changed

‎_toc.yaml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Copyright 2019 The TensorFlow Authors. All Rights Reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
#
15+
# ==============================================================================
16+
toc:
17+
- title: Install
18+
path: /jvm/install

‎docs/index.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# TensorFlow for Java
2+
3+
## Welcome to the Java world of TensorFlow!
4+
5+
TensorFlow can run on any JVM for building, training and running machine learning models. It comes with
6+
a series of utilities and frameworks that help achieve most of the tasks common to data scientists
7+
and developers working in this domain. Java and other JVM languages, such as Scala or Kotlin, are
8+
frequently used in small-to-large enterprises all over the world, which makes TensorFlow a strategic
9+
choice for adopting machine learning at a large scale.
10+
11+
## This Repository
12+
13+
In the early days, the Java language bindings for TensorFlow were hosted in the [main repository](https://github.com/tensorflow/tensorflow)
14+
and released only when a new version of the core library was ready to be distributed, which happens only
15+
a few times a year. Now, all Java-related code has been moved to this repository so that it can evolve and
16+
be released independently from official TensorFlow releases. In addition, most of the build tasks have been
17+
migrated from Bazel to Maven, which is more familiar for most Java developers.
18+
19+
The following describes the layout of the repository and its different artifacts:
20+
21+
* `tensorflow-core`
22+
* All artifacts that build up the core language bindings of TensorFlow for Java
23+
* Intended audience: projects that provide their own APIs or frameworks on top of
24+
TensorFlow and just want a thin layer to access the TensorFlow runtime from the JVM
25+
26+
* `tensorflow-framework`
27+
* Primary API for building and training neural networks with TensorFlow
28+
* Intended audience: neural network developers
29+
* For more information: [tensorflow-framework/README.md](tensorflow-framework/README.md)
30+
31+
* `ndarray`
32+
* Generic utility library for n-dimensional data I/O operations
33+
* Used by TensorFlow but does not depend on TensorFlow
34+
* Intended audience: any developer who needs a Java n-dimensional array implementation, whether or not they
35+
use it with TensorFlow
36+
37+
38+
## Communication
39+
40+
This repository is maintained by TensorFlow JVM Special Interest Group (SIG). You can easily join the group
41+
by subscribing to the [[email protected]](https://groups.google.com/a/tensorflow.org/forum/#!forum/jvm)
42+
mailing list, or you can simply send pull requests and raise issues to this repository.
43+
There is also a [sig-jvm Gitter channel](https://gitter.im/tensorflow/sig-jvm).
44+
45+
## Building Sources
46+
47+
See [CONTRIBUTING.md](CONTRIBUTING.md#building).
48+
49+
## Using Maven Artifacts
50+
51+
To include TensorFlow in your Maven application, you first need to add a dependency on either the
52+
`tensorflow-core` or `tensorflow-core-platform` artifacts. The former could be included multiple times
53+
for different targeted systems by their classifiers, while the later includes them as dependencies for
54+
`linux-x86_64`, `macosx-x86_64`, and `windows-x86_64`, with more to come in the future. There are also
55+
`tensorflow-core-platform-mkl`, `tensorflow-core-platform-gpu`, and `tensorflow-core-platform-mkl-gpu`
56+
artifacts that depend on artifacts with MKL and/or CUDA support enabled.
57+
58+
For example, for building a JAR that uses TensorFlow and is targeted to be deployed only on Linux
59+
systems, you should add the following dependencies:
60+
```xml
61+
<dependency>
62+
<groupId>org.tensorflow</groupId>
63+
<artifactId>tensorflow-core-api</artifactId>
64+
<version>0.3.1</version>
65+
</dependency>
66+
<dependency>
67+
<groupId>org.tensorflow</groupId>
68+
<artifactId>tensorflow-core-api</artifactId>
69+
<version>0.3.1</version>
70+
<classifier>linux-x86_64${javacpp.platform.extension}</classifier>
71+
</dependency>
72+
```
73+
74+
On the other hand, if you plan to deploy your JAR on more platforms, you need additional
75+
native dependencies as follows:
76+
```xml
77+
<dependency>
78+
<groupId>org.tensorflow</groupId>
79+
<artifactId>tensorflow-core-api</artifactId>
80+
<version>0.3.1</version>
81+
</dependency>
82+
<dependency>
83+
<groupId>org.tensorflow</groupId>
84+
<artifactId>tensorflow-core-api</artifactId>
85+
<version>0.3.1</version>
86+
<classifier>linux-x86_64${javacpp.platform.extension}</classifier>
87+
</dependency>
88+
<dependency>
89+
<groupId>org.tensorflow</groupId>
90+
<artifactId>tensorflow-core-api</artifactId>
91+
<version>0.3.1</version>
92+
<classifier>macosx-x86_64${javacpp.platform.extension}</classifier>
93+
</dependency>
94+
<dependency>
95+
<groupId>org.tensorflow</groupId>
96+
<artifactId>tensorflow-core-api</artifactId>
97+
<version>0.3.1</version>
98+
<classifier>windows-x86_64${javacpp.platform.extension}</classifier>
99+
</dependency>
100+
```
101+
102+
In some cases, pre-configured starter artifacts can help to automatically include all versions of
103+
the native library for a given configuration. For example, the `tensorflow-core-platform`,
104+
`tensorflow-core-platform-mkl`, `tensorflow-core-platform-gpu`, or `tensorflow-core-platform-mkl-gpu`
105+
artifact includes transitively all the artifacts above as a single dependency:
106+
```xml
107+
<dependency>
108+
<groupId>org.tensorflow</groupId>
109+
<artifactId>tensorflow-core-platform${javacpp.platform.extension}</artifactId>
110+
<version>0.3.1</version>
111+
</dependency>
112+
```
113+
114+
Be aware though that the native library is quite large and including too many versions of it may
115+
significantly increase the size of your JAR. So it is good practice to limit your dependencies to
116+
the platforms you are targeting. For this purpose the `-platform` artifacts include profiles that follow
117+
the conventions established on this page:
118+
* [Reducing the Number of Dependencies](https://github.com/bytedeco/javacpp-presets/wiki/Reducing-the-Number-of-Dependencies)
119+
120+
### Snapshots
121+
122+
Snapshots of TensorFlow Java artifacts are automatically distributed after each update in the code. To use them, you need
123+
to add Sonatype OSS repository in your pom.xml, like the following
124+
125+
```xml
126+
<repositories>
127+
<repository>
128+
<id>tensorflow-snapshots</id>
129+
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
130+
<snapshots>
131+
<enabled>true</enabled>
132+
</snapshots>
133+
</repository>
134+
</repositories>
135+
<dependencies>
136+
<!-- Example of dependency, see section above for more options -->
137+
<dependency>
138+
<groupId>org.tensorflow</groupId>
139+
<artifactId>tensorflow-core-platform</artifactId>
140+
<version>0.4.0-SNAPSHOT</version>
141+
</dependency>
142+
</dependencies>
143+
```
144+
145+
## TensorFlow Version Support
146+
147+
This table shows the mapping between different version of TensorFlow for Java and the core runtime libraries.
148+
149+
| TensorFlow Java Version | TensorFlow Version |
150+
| ------------- | ------------- |
151+
| 0.2.0 | 2.3.1 |
152+
| 0.3.0 | 2.4.1 |
153+
| 0.3.1 | 2.4.1 |
154+
| 0.4.0-SNAPSHOT | 2.4.1
155+
156+
## How to Contribute?
157+
158+
Contributions are welcome, guidelines are located in [CONTRIBUTING.md](CONTRIBUTING.md).

‎docs/install.md

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# Install TensorFlow Java
2+
3+
[TensorFlow Java](https://github.com/tensorflow/java) can run on any JVM for
4+
building, training and deploying machine learning models. It supports both CPU
5+
and GPU execution, in graph or eager mode, and presents a rich API for using
6+
TensorFlow in a JVM environment. Java and other JVM languages, like Scala and
7+
Kotlin, are frequently used in large and small enterprises all over the world,
8+
which makes TensorFlow Java a strategic choice for adopting machine learning at
9+
a large scale.
10+
11+
Caution: The TensorFlow Java API is *not* covered by the TensorFlow
12+
[API stability guarantees](../guide/versions.md).
13+
14+
## Requirements
15+
16+
TensorFlow Java runs on Java 8 and above, and supports out-of-the-box the
17+
following platforms:
18+
19+
* Ubuntu 16.04 or higher; 64-bit, x86
20+
* macOS 10.12.6 (Sierra) or higher; 64-bit, x86
21+
* Windows 7 or higher; 64-bit, x86
22+
23+
*Note: To use TensorFlow on Android, see
24+
[TensorFlow Lite](https://tensorflow.org/lite)*
25+
26+
## Versions
27+
28+
TensorFlow Java has its own release cycle, independent from the
29+
[TensorFlow runtime](https://github.com/tensorflow/tensorflow). Consequently,
30+
its version does not match the version of TensorFlow runtime it runs on. Consult
31+
the TensorFlow Java
32+
[versioning table](https://github.com/tensorflow/java/#tensorflow-version-support)
33+
to list all versions available and their mapping with the TensorFlow runtime.
34+
35+
## Artifacts
36+
37+
There are
38+
[several ways](https://github.com/tensorflow/java/#using-maven-artifacts) to add
39+
TensorFlow Java to your project. The easiest one is to add a dependency on the
40+
`tensorflow-core-platform` artifact, which includes both the TensorFlow Java
41+
Core API and the native dependencies it requires to run on all supported
42+
platforms.
43+
44+
You can also select one of the following extensions instead of the pure CPU
45+
version:
46+
47+
* `tensorflow-core-platform-mkl`: Support for Intel® MKL-DNN on all platforms
48+
* `tensorflow-core-platform-gpu`: Support for CUDA® on Linux and Windows
49+
platforms
50+
* `tensorflow-core-platform-mkl-gpu`: Support for Intel® MKL-DNN and CUDA® on
51+
Linux platform.
52+
53+
In addition, a separate dependency on the `tensorflow-framework` library can be
54+
added to benefit from a rich set of utilities for TensorFlow-based machine
55+
learning on the JVM.
56+
57+
## Installing with Maven
58+
59+
To include TensorFlow in your [Maven](http://maven.apache.org) application, add
60+
a dependency on its [artifacts](#artifacts) to your project's `pom.xml` file.
61+
For example,
62+
63+
```xml
64+
<dependency>
65+
<groupId>org.tensorflow</groupId>
66+
<artifactId>tensorflow-core-platform</artifactId>
67+
<version>0.3.1</version>
68+
</dependency>
69+
```
70+
71+
### Reducing Number of Dependencies
72+
73+
It is important to note that adding a dependency on a `tensorflow-core-platform`
74+
artifact will import native libraries for all supported platforms, which can
75+
significantly increase the size of your project.
76+
77+
If you wish to target a subset of the available platforms then you can exclude
78+
the unnecessary artifacts from the other platforms using the
79+
[Maven Dependency Exclusion](https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#dependency-exclusions)
80+
feature.
81+
82+
Another way to select which platforms you want to include in your application is
83+
to set JavaCPP system properties, in your Maven command line or in your
84+
`pom.xml`. Please see JavaCPP
85+
[documentation](https://github.com/bytedeco/javacpp-presets/wiki/Reducing-the-Number-of-Dependencies)
86+
for more details.
87+
88+
### Using Snapshots
89+
90+
The latest TensorFlow Java development snapshots from the TensorFlow Java source
91+
repository are available on the [OSS Sonatype](https://oss.sonatype.org) Nexus
92+
repository. To depend on these artifacts, make sure to configure the OSS
93+
snapshots repository in your `pom.xml`.
94+
95+
```xml
96+
<repositories>
97+
<repository>
98+
<id>tensorflow-snapshots</id>
99+
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
100+
<snapshots>
101+
<enabled>true</enabled>
102+
</snapshots>
103+
</repository>
104+
</repositories>
105+
106+
<dependencies>
107+
<dependency>
108+
<groupId>org.tensorflow</groupId>
109+
<artifactId>tensorflow-core-platform</artifactId>
110+
<version>0.4.0-SNAPSHOT</version>
111+
</dependency>
112+
</dependencies>
113+
```
114+
115+
## Installing with Gradle
116+
117+
To include TensorFlow in your [Gradle](https://gradle.org) application, add a
118+
dependency on its [artifacts](#artifacts) to your project's `build.gradle` file.
119+
For example,
120+
121+
```groovy
122+
repositories {
123+
mavenCentral()
124+
}
125+
126+
dependencies {
127+
compile group: 'org.tensorflow', name: 'tensorflow-core-platform', version: '0.3.1'
128+
}
129+
```
130+
131+
### Reducing Number of Dependencies
132+
133+
Excluding native artifacts from TensorFlow Java with Gradle is not as easy as
134+
with Maven. We recommend that you use Gradle JavaCPP plugins to reduce this
135+
number of dependencies.
136+
137+
Please read at Gradle JavaCPP
138+
[documentation](https://github.com/bytedeco/gradle-javacpp) for more details.
139+
140+
## Installing from Sources
141+
142+
To build TensorFlow Java from sources, and possibly customize it, please read
143+
the following
144+
[instructions](https://github.com/tensorflow/java/blob/master/CONTRIBUTING.md#building).
145+
146+
*Note: Only official builds distributed by TensorFlow are supported by its
147+
maintainers and custom builds should be used at the user's risk.*
148+
149+
# Example Program
150+
151+
This example shows how to build an Apache Maven project with TensorFlow. First,
152+
add the TensorFlow dependency to the project's `pom.xml` file:
153+
154+
```xml
155+
<project>
156+
<modelVersion>4.0.0</modelVersion>
157+
<groupId>org.myorg</groupId>
158+
<artifactId>hellotensorflow</artifactId>
159+
<version>1.0-SNAPSHOT</version>
160+
161+
<properties>
162+
<exec.mainClass>HelloTensorFlow</exec.mainClass>
163+
<!-- Minimal version for compiling TensorFlow Java is JDK 8 -->
164+
<maven.compiler.source>1.8</maven.compiler.source>
165+
<maven.compiler.target>1.8</maven.compiler.target>
166+
</properties>
167+
168+
<dependencies>
169+
<!-- Include TensorFlow (pure CPU only) for all supported platforms -->
170+
<dependency>
171+
<groupId>org.tensorflow</groupId>
172+
<artifactId>tensorflow-core-platform</artifactId>
173+
<version>0.3.1</version>
174+
</dependency>
175+
</dependencies>
176+
</project>
177+
```
178+
179+
Create the source file `src/main/java/HelloTensorFlow.java`:
180+
181+
```java
182+
import org.tensorflow.ConcreteFunction;
183+
import org.tensorflow.Signature;
184+
import org.tensorflow.Tensor;
185+
import org.tensorflow.TensorFlow;
186+
import org.tensorflow.op.Ops;
187+
import org.tensorflow.op.core.Placeholder;
188+
import org.tensorflow.op.math.Add;
189+
import org.tensorflow.types.TInt32;
190+
191+
public class HelloTensorFlow {
192+
193+
public static void main(String[] args) throws Exception {
194+
System.out.println("Hello TensorFlow " + TensorFlow.version());
195+
196+
try (ConcreteFunction dbl = ConcreteFunction.create(HelloTensorFlow::dbl);
197+
TInt32 x = TInt32.scalarOf(10);
198+
Tensor dblX = dbl.call(x)) {
199+
System.out.println(x.getInt() + " doubled is " + ((TInt32)dblX).getInt());
200+
}
201+
}
202+
203+
private static Signature dbl(Ops tf) {
204+
Placeholder<TInt32> x = tf.placeholder(TInt32.class);
205+
Add<TInt32> dblX = tf.math.add(x, x);
206+
return Signature.builder().input("x", x).output("dbl", dblX).build();
207+
}
208+
}
209+
```
210+
211+
Compile and execute:
212+
213+
<pre class="devsite-terminal prettyprint lang-bsh">
214+
mvn -q compile exec:java
215+
</pre>
216+
217+
The command prints TensorFlow version and a simple calculation.
218+
219+
Success! TensorFlow Java is configured.

0 commit comments

Comments
 (0)