README.md
1# Introduction
2
3This is the documentation page for the Java wrapper of OR-Tools.
4
5This project aim to explain how you build a Java 1.8 native (for win32-x86-64,
6linux-x86-64 and darwin-x86-64) maven multiple package using [`mvn`](http://maven.apache.org/)
7and few [POM.xml](http://maven.apache.org/pom.html).
8
9## Table of Content
10
11* [Requirement](#requirement)
12* [Directory Layout](#directory-layout)
13* [Build Process](#build-process)
14 * [Local Package](#local-package)
15 * [Building a native Package](#building-local-native-package)
16 * [Building a Local Package](#building-local-package)
17 * [Testing the Local Package](#testing-local-package)
18* [Appendices](#appendices)
19 * [Resources](#resources)
20* [Misc](#misc)
21
22## Requirement
23
24You'll need a "Java SDK >= 1.8" and "Maven >= 3.6".
25
26## Directory Layout
27
28* [pom-native.xml.in](pom-native.xml.in) POM template to build the native
29 project.
30* [com/google/ortools/Loader.java](com/google/ortools/Loader.java) Helper to
31 unpack and load the correct native libraries.
32* [pom-local.xml.in](pom-local.xml.in) POM template to build the "pure" Java
33 project.
34* [pom-sample.xml.in](pom-sample.xml.in) POM template used to build samples
35 and examples.
36* [pom-test.xml.in](pom-test.xml.in) POM template used to build tests.
37
38## Build Process
39
40To Create a native dependent package we will split it in two parts:
41
42* A bunch of `com.google.ortools:ortools-{platform}` maven packages for each
43supported platform targeted and containing the native libraries.
44* A java maven package `com.google.ortools:ortools-java` depending on the native
45package and containing the Java code.
46
47[`platform` names](https://github.com/java-native-access/jna/blob/cc1acdac02e4d0dda93ba01bbe3a3435b8933dab/test/com/sun/jna/PlatformTest.java#L31-L100)
48come from the JNA project (Java Native Access) which will be use to find at
49runtime on which platform the code is currently running.
50
51### Local Package
52
53The pipeline for `linux-x86-64` should be as follow: \
54note: The pipeline will be similar for `darwin-x86-64` and `win32-x86-64`
55architecture, don't hesitate to look at the CI log!
56![Local Pipeline](doc/local_pipeline.svg) ![Legend](doc/legend.svg)
57
58#### Building local native Package
59
60Thus we have the C++ shared library `libortools.so` and the SWIG generated JNI
61wrappers `libjniortools.so`.
62
63So first let's create the local `com.google.ortools:ortools-{platform}.jar`
64maven package.
65
66Here some dev-note concerning this `POM.xml`.
67* This package is a native package only containing native libraries.
68
69Then you can generate the package and install it locally using:
70```bash
71mvn package
72mvn install
73```
74note: this will automatically trigger the `mvn compile` phase.
75
76If everything good the package (located in
77`<buildir>/java/ortools-<platform>/target/`) should have this layout:
78```
79{...}/target/ortools-<platform>-1.0.jar:
80\- <platform>
81 \-libortools.so.8.0
82 \-libjniortools.so
83...
84```
85note: `<platform>` could be `linux-x86-64`, `darwin-x86-64` or `win32-x86-64`.
86
87tips: since maven package are just zip archive you can use `unzip -l <package>.jar`
88to study their layout.
89
90#### Building local Package
91
92##### Standard Maven Package
93
94So now, let's create the local `com.google.ortools:ortools-java.jar` maven
95package which will depend on our previous native package.
96
97Here some dev-note concerning this `POM.xml`.
98* Add runtime dependency on each native package(s) available:
99 ```xml
100 <dependency>
101 <groupId>com.google.ortools</groupId>
102 <artifactId>ortools-linux-x86-64</artifactId>
103 <version>[8.0,)</version>
104 <type>jar</type>
105 <scope>runtime</scope>
106 </dependency>
107 ```
108 - Add dependency to jna so we can find at runtime the current `<platform>`:
109 ```xml
110 <dependency>
111 <groupId>net.java.dev.jna</groupId>
112 <artifactId>jna-platform</artifactId>
113 <version>5.5.0</version>
114 </dependency>
115 ```
116
117Then you can generate the package using:
118```bash
119mvn package
120mvn install
121```
122
123If Maven executes these commands successfully, the package (located in
124`<buildir>/temp_java/ortools-java/target/`) should have this layout:
125```
126{...}/target/ortools-java-{build version}.jar:
127\- com/
128 \- google/
129 \- ortools/
130 \- Loader$PathConsumer.class
131 \- Loader$1.class
132 \- Loader.class
133 \- constraintsolver/
134 \- RoutingModel.class
135 \- RoutingIndexManager.class
136 \- ...
137 \- ...
138...
139```
140
141##### Dependency-inclusive Maven Package (fat .jar)
142
143We can also create a Maven package that includes all of its own dependencies, also known as a 'fat .jar'. This is useful
144for situations in which it is more convenient, or even necessary, to use a single .jar as a dependency for a Java
145OR-Tools project.
146
147One example is when OR-Tools is compiled with third-party solver support (such as CPLEX or XPress), and one needs to
148build and execute in an environment that does not have access to one's local Maven repository (for example, a
149remotely-built Docker container).
150
151Building a fat .jar with all dependencies included (including the native package) allows one to have a single
152dependency, namely `com.google.ortools:ortools-java.jar`, which can be marked as `<scope>provided</scope>` in one's
153project `pom.xml`:
154```xml
155<dependency>
156 <groupId>com.google.ortools</groupId>
157 <artifactId>ortools-java</artifactId>
158 <version>{insert build version here}</version>
159 <scope>provided</scope>
160</dependency>
161```
162One would then make this fat .jar available in the execution environment's Java classpath, for example:
163```bash
164java -cp "/path/to/dependency.jar" -jar "/path/to/your/executable/.jar"
165```
166There are several ways to make the fat .jar dependency available to your Java program - please consult
167[JDK documentation](https://devdocs.io/openjdk/) (this links to OpenJDK 15 documentation), as well as documentation for
168any packaging and/or execution frameworks/tools you may be using.
169
170To package a fat .jar with Maven, run
171```bash
172mvn package -Dfatjar=true
173```
174To then (optionally) install it to your local Maven repository, run
175```bash
176mvn install
177```
178Note that this will replace any previously downloaded or built 'non-fat-.jar' ortools-java packages in your local
179Maven repository
180
181[comment]: <> (FIXME show depedencies within .jar structure)
182If Maven executes these commands successfully, the package (located in
183`<buildir>/temp_java/ortools-java/target/`) should have this layout:
184```
185{...}/target/ortools-java-{build version}.jar:
186\- com/
187 \- google/
188 \- ortools/
189 \- Loader$PathConsumer.class
190 \- Loader$1.class
191 \- Loader.class
192 \- constraintsolver/
193 \- RoutingModel.class
194 \- RoutingIndexManager.class
195 \- ...
196 \- ...
197...
198```
199
200#### Testing local Package
201
202We can test everything is working by using any sample project.
203
204First you can build it using:
205```
206cmake --build build
207```
208note: `ortools-java` which is locally installed in the local maven cache
209(`~/.m2/repository/com/google/ortools/ortools-java/...`).
210
211Then you can run it using:
212```sh
213cmake --build build --target test
214```
215or manually using:
216```
217cd <builddir>/java/component/example
218mvn compile
219mvn exec:java
220```
221
222## Appendices
223
224Few links on the subject...
225
226### Resources
227
228* [POM.xml reference](http://maven.apache.org/pom.html)
229* [Maven Central POM requirement](https://central.sonatype.org/pages/requirements.html)
230* [Maven Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/)
231* [Maven Source Plugin](https://maven.apache.org/plugins/maven-source-plugin/)
232* [Maven GPG Plugin](https://maven.apache.org/plugins/maven-gpg-plugin/)
233* [Maven Assembly Plugin](https://maven.apache.org/plugins/maven-assembly-plugin/)
234* [Java Native Access Project](https://github.com/java-native-access/jna)
235
236## Misc
237
238Image has been generated using [plantuml](http://plantuml.com/):
239```bash
240plantuml -Tsvg doc/{file}.dot
241```
242So you can find the dot source files in [doc](doc).
243