Fixup README.md
This commit is contained in:
Corentin Le Molgat
@@ -1,54 +1,70 @@
|
||||
# Introduction
|
||||
|
||||
This is the documentation page for the Java wrapper of OR-Tools.
|
||||
|
||||
This project aim to explain how you build a Java 1.8 native (for win32-x86-64, linux-x86-64 and darwin) maven package using [`mvn`](http://maven.apache.org/) and few [POM.xml](http://maven.apache.org/pom.html).
|
||||
This project aim to explain how you build a Java 1.8 native (for win32-x86-64,
|
||||
linux-x86-64 and darwin) maven package using [`mvn`](http://maven.apache.org/)
|
||||
and few [POM.xml](http://maven.apache.org/pom.html).
|
||||
|
||||
## Table of Content
|
||||
|
||||
* [Requirement](#requirement)
|
||||
* [Directory Layout](#directory-layout)
|
||||
* [Build Process](#build-process)
|
||||
* [Local Package](#local-package)
|
||||
* [Building a native Package](#building-local-native-package)
|
||||
* [Building a Local Package](#building-local-package)
|
||||
* [Testing the Local Package](#testing-local-package)
|
||||
* [Building a native Package](#building-local-native-package)
|
||||
* [Building a Local Package](#building-local-package)
|
||||
* [Testing the Local Package](#testing-local-package)
|
||||
* [Appendices](#appendices)
|
||||
* [Ressources](#ressources)
|
||||
* [Misc](#misc)
|
||||
|
||||
# Requirement
|
||||
## Requirement
|
||||
|
||||
You'll need a "Java SDK >= 1.8" and "Maven >= 3.6".
|
||||
|
||||
# Directory Layout
|
||||
* [pom-native.xml.in](pom-native.xml.in) POM template to build the native project.
|
||||
* [com/google/ortools/Loader.java](com/google/ortools/Loader.java) Helper to unpack and load the correct native libraries.
|
||||
* [pom-local.xml.in](pom-local.xml.in) POM template to build the "pure" Java project.
|
||||
* [pom-sample.xml.in](pom-sample.xml.in) POM template used to build samples and examples.
|
||||
## Directory Layout
|
||||
|
||||
* [pom-native.xml.in](pom-native.xml.in) POM template to build the native
|
||||
project.
|
||||
* [com/google/ortools/Loader.java](com/google/ortools/Loader.java) Helper to
|
||||
unpack and load the correct native libraries.
|
||||
* [pom-local.xml.in](pom-local.xml.in) POM template to build the "pure" Java
|
||||
project.
|
||||
* [pom-sample.xml.in](pom-sample.xml.in) POM template used to build samples
|
||||
and examples.
|
||||
* [pom-test.xml.in](pom-test.xml.in) POM template used to build tests.
|
||||
|
||||
# Build Process
|
||||
## Build Process
|
||||
|
||||
To Create a native dependent package we will split it in two parts:
|
||||
- A bunch of `com.google.ortools:ortools-{platform}` maven packages for each
|
||||
|
||||
* A bunch of `com.google.ortools:ortools-{platform}` maven packages for each
|
||||
supported platform targeted and containing the native libraries.
|
||||
- A java maven package `com.google.ortools:ortools-java` depending on the native
|
||||
* A java maven package `com.google.ortools:ortools-java` depending on the native
|
||||
package and containing the Java code.
|
||||
|
||||
[`platform` names](https://github.com/java-native-access/jna/blob/cc1acdac02e4d0dda93ba01bbe3a3435b8933dab/test/com/sun/jna/PlatformTest.java#L31-L100)
|
||||
come from the JNA project (Java Native Access) which will be use to find at
|
||||
runtime on which platform the code is currently running.
|
||||
|
||||
## Local Package
|
||||
The pipeline for `linux-x86-64` should be as follow:
|
||||
note: The pipeline will be similar for `darwin` and `win32-x86-64` architecture, don't hesitate to look at the CI log!
|
||||
|
||||
### Local Package
|
||||
|
||||
The pipeline for `linux-x86-64` should be as follow: \
|
||||
note: The pipeline will be similar for `darwin` and `win32-x86-64` architecture,
|
||||
don't hesitate to look at the CI log! 
|
||||
|
||||
|
||||
### Building local native Package
|
||||
Thus we have the C++ shared library `libortools.so` and the SWIG generated JNI wrappers `libjniortools.so`.
|
||||
#### Building local native Package
|
||||
|
||||
So first let's create the local `com.google.ortools:ortools-{platform}.jar` maven package.
|
||||
Thus we have the C++ shared library `libortools.so` and the SWIG generated JNI
|
||||
wrappers `libjniortools.so`.
|
||||
|
||||
So first let's create the local `com.google.ortools:ortools-{platform}.jar`
|
||||
maven package.
|
||||
|
||||
Here some dev-note concerning this `POM.xml`.
|
||||
- This package is a native package only containing native libraries.
|
||||
* This package is a native package only containing native libraries.
|
||||
|
||||
Then you can generate the package and install it locally using:
|
||||
```bash
|
||||
@@ -57,23 +73,27 @@ mvn install
|
||||
```
|
||||
note: this will automatically trigger the `mvn compile` phase.
|
||||
|
||||
If everything good the package (located in `<buildir>/java/ortools-<platform>/target/`) should have this layout:
|
||||
If everything good the package (located in
|
||||
`<buildir>/java/ortools-<platform>/target/`) should have this layout:
|
||||
```
|
||||
{...}/target/ortools-<platform>-1.0.jar:
|
||||
\- <platform>
|
||||
\-libortools.so.8.0
|
||||
\-libjniortools.so
|
||||
...
|
||||
...
|
||||
```
|
||||
note: `<platform>` could be `linux-x86-64`, `darwin` or `win32-x86-64`.
|
||||
|
||||
tips: since maven package are just zip archive you can use `unzip -l <package>.jar` to study their layout.
|
||||
tips: since maven package are just zip archive you can use `unzip -l <package>.jar`
|
||||
to study their layout.
|
||||
|
||||
### Building local Package
|
||||
So now, let's create the local `com.google.ortools:ortools-java.jar` maven package which will depend on our previous native package.
|
||||
#### Building local Package
|
||||
|
||||
So now, let's create the local `com.google.ortools:ortools-java.jar` maven
|
||||
package which will depend on our previous native package.
|
||||
|
||||
Here some dev-note concerning this `POM.xml`.
|
||||
- Add runtime dependency on each native package(s) availabe:
|
||||
- Add runtime dependency on each native package(s) available:
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.google.ortools</groupId>
|
||||
@@ -98,7 +118,8 @@ mvn package
|
||||
mvn install
|
||||
```
|
||||
|
||||
If everything good the package (located in `<buildir>/java/ortools-java/target/`) should have this layout:
|
||||
If everything good the package (located in
|
||||
`<buildir>/java/ortools-java/target/`) should have this layout:
|
||||
```
|
||||
{...}/target/ortools-java-8.0.jar:
|
||||
\- com/
|
||||
@@ -112,10 +133,11 @@ If everything good the package (located in `<buildir>/java/ortools-java/target/`
|
||||
\- RoutingIndexManager.class
|
||||
\- ...
|
||||
\- ...
|
||||
...
|
||||
...
|
||||
```
|
||||
|
||||
### Testing local Package
|
||||
#### Testing local Package
|
||||
|
||||
We can test everything is working by using any sample project.
|
||||
|
||||
First you can build it using:
|
||||
@@ -136,18 +158,20 @@ mvn compile
|
||||
mvn exec:java
|
||||
```
|
||||
|
||||
# Appendices
|
||||
## Appendices
|
||||
|
||||
Few links on the subject...
|
||||
|
||||
## Ressources
|
||||
### Ressources
|
||||
|
||||
- [POM.xml reference](http://maven.apache.org/pom.html)
|
||||
- [Maven Central POM requirement](https://central.sonatype.org/pages/requirements.html)
|
||||
- [Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/)
|
||||
- [Java Source Plugin](https://maven.apache.org/plugins/maven-source-plugin/)
|
||||
- [Java Native Access Project](https://github.com/java-native-access/jna)
|
||||
* [POM.xml reference](http://maven.apache.org/pom.html)
|
||||
* [Maven Central POM requirement](https://central.sonatype.org/pages/requirements.html)
|
||||
* [Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/)
|
||||
* [Java Source Plugin](https://maven.apache.org/plugins/maven-source-plugin/)
|
||||
* [Java Native Access Project](https://github.com/java-native-access/jna)
|
||||
|
||||
## Misc
|
||||
|
||||
# Misc
|
||||
Image has been generated using [plantuml](http://plantuml.com/):
|
||||
```bash
|
||||
plantuml -Tsvg doc/{file}.dot
|
||||
|
||||
@@ -1,43 +1,54 @@
|
||||
# Introduction
|
||||
|
||||
This is the documentation page for the Python 3.6+ wrapper of OR-Tools.
|
||||
|
||||
|
||||
This project aim to explain how you build a Python native wheel package using [`setup.py`](https://packaging.python.org/tutorials/packaging-projects/).
|
||||
This project aim to explain how you build a Python native wheel package using
|
||||
[`setup.py`](https://packaging.python.org/tutorials/packaging-projects/).
|
||||
|
||||
## Table of Content
|
||||
|
||||
* [Requirement](#requirement)
|
||||
* [Directory Layout](#directory-layout)
|
||||
* [Build Process](#build-process)
|
||||
* [Local Package](#local-package)
|
||||
* [Building a native Package](#building-local-native-package)
|
||||
* [Building a native Package](#building-local-native-package)
|
||||
* [Appendices](#appendices)
|
||||
* [Ressources](#ressources)
|
||||
* [Misc](#misc)
|
||||
|
||||
# Requirement
|
||||
## Requirement
|
||||
|
||||
You'll need "Python >= 3.6" and few python modules ("wheel" and "absl-py").
|
||||
|
||||
# Directory Layout
|
||||
* [setup.py.in](setup.py.in) `Setup.py` template to build the python native project.
|
||||
## Directory Layout
|
||||
|
||||
* [setup.py.in](setup.py.in) `Setup.py` template to build the python native
|
||||
project.
|
||||
|
||||
## Build Process
|
||||
|
||||
# Build Process
|
||||
To Create a native dependent package which will contains two parts:
|
||||
- A bunch of native libraries for the supported platform targeted.
|
||||
- The Python code depending on it.
|
||||
* A bunch of native libraries for the supported platform targeted.
|
||||
* The Python code depending on it.
|
||||
|
||||
[`platform` names](https://github.com/java-native-access/jna/blob/cc1acdac02e4d0dda93ba01bbe3a3435b8933dab/test/com/sun/jna/PlatformTest.java#L31-L100) come from the JNA project (Java Native Access) which will be use to find at runtime on which platform the code is currently running.
|
||||
[`platform` names](https://github.com/java-native-access/jna/blob/cc1acdac02e4d0dda93ba01bbe3a3435b8933dab/test/com/sun/jna/PlatformTest.java#L31-L100)
|
||||
come from the JNA project (Java Native Access) which will be use to find at
|
||||
runtime on which platform the code is currently running.
|
||||
|
||||
## Local Package
|
||||
The pipeline for `linux-x86-64` should be as follow:
|
||||
note: The pipeline will be similar for other architectures, don't hesitate to look at the CI log!
|
||||
|
||||
### Local Package
|
||||
|
||||
The pipeline for `linux-x86-64` should be as follow: \
|
||||
note: The pipeline will be similar for other architectures, don't hesitate to
|
||||
look at the CI log! 
|
||||
|
||||
|
||||
### Building local native Package
|
||||
Thus we have the C++ shared library `libortools.so` and the SWIG generated Python wrappers e.g. `pywrapsat.py` in the same package.
|
||||
#### Building local native Package
|
||||
|
||||
Thus we have the C++ shared library `libortools.so` and the SWIG generated
|
||||
Python wrappers e.g. `pywrapsat.py` in the same package.
|
||||
|
||||
Here some dev-note concerning this `setup.py`.
|
||||
- This package is a native package containing native libraries.
|
||||
* This package is a native package containing native libraries.
|
||||
|
||||
Then you can generate the package and install it locally using:
|
||||
```bash
|
||||
@@ -45,7 +56,8 @@ python3 setup.py bdist_wheel
|
||||
python3 -m pip install --user --find-links=dist ortools
|
||||
```
|
||||
|
||||
If everything good the package (located in `<buildir>/python/dist`) should have this layout:
|
||||
If everything good the package (located in `<buildir>/python/dist`) should have
|
||||
this layout:
|
||||
```
|
||||
{...}/dist/ortools-8.0.9999-cp38-cp38-<platform>.whl:
|
||||
\- ortools
|
||||
@@ -60,22 +72,25 @@ If everything good the package (located in `<buildir>/python/dist`) should have
|
||||
\- __init__.py
|
||||
\- pywrap....py
|
||||
\- _pywrap....so
|
||||
...
|
||||
...
|
||||
```
|
||||
note: `<platform>` could be `manylinux2010_x86_64`, `macosx_10_9_x86_64` or `win-amd64`.
|
||||
|
||||
tips: since wheel package are just zip archive you can use `unzip -l <package>.whl` to study their layout.
|
||||
tips: since wheel package are just zip archive you can use `unzip -l <package>.whl`
|
||||
to study their layout.
|
||||
|
||||
## Appendices
|
||||
|
||||
# Appendices
|
||||
Few links on the subject...
|
||||
|
||||
## Ressources
|
||||
### Ressources
|
||||
|
||||
- [Packaging Python Project](https://packaging.python.org/tutorials/packaging-projects/)
|
||||
- [PEP 513 -- A Platform Tag for Portable Linux Built Distributions](https://www.python.org/dev/peps/pep-0513/)
|
||||
- [PEP 571 -- The manylinux2010 Platform Tag](https://www.python.org/dev/peps/pep-0571/)
|
||||
* [Packaging Python Project](https://packaging.python.org/tutorials/packaging-projects/)
|
||||
* [PEP 513 -- A Platform Tag for Portable Linux Built Distributions](https://www.python.org/dev/peps/pep-0513/)
|
||||
* [PEP 571 -- The manylinux2010 Platform Tag](https://www.python.org/dev/peps/pep-0571/)
|
||||
|
||||
## Misc
|
||||
|
||||
# Misc
|
||||
Image has been generated using [plantuml](http://plantuml.com/):
|
||||
```bash
|
||||
plantuml -Tsvg doc/{file}.dot
|
||||
|
||||
Reference in New Issue
Block a user