diff --git a/ortools/java/README.md b/ortools/java/README.md index d4ef05ab61..ec921a9add 100644 --- a/ortools/java/README.md +++ b/ortools/java/README.md @@ -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 Pipeline](doc/local_pipeline.svg) +### 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 Pipeline](doc/local_pipeline.svg) ![Legend](doc/legend.svg) -### 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 `/java/ortools-/target/`) should have this layout: +If everything good the package (located in +`/java/ortools-/target/`) should have this layout: ``` {...}/target/ortools--1.0.jar: \- \-libortools.so.8.0 \-libjniortools.so -... +... ``` note: `` could be `linux-x86-64`, `darwin` or `win32-x86-64`. -tips: since maven package are just zip archive you can use `unzip -l .jar` to study their layout. +tips: since maven package are just zip archive you can use `unzip -l .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 com.google.ortools @@ -98,7 +118,8 @@ mvn package mvn install ``` -If everything good the package (located in `/java/ortools-java/target/`) should have this layout: +If everything good the package (located in +`/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 `/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 diff --git a/ortools/python/README.md b/ortools/python/README.md index cddd0529c5..b41f072c2e 100644 --- a/ortools/python/README.md +++ b/ortools/python/README.md @@ -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 Pipeline](doc/local_pipeline.svg) +### 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 Pipeline](doc/local_pipeline.svg) ![Legend](doc/legend.svg) -### 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 `/python/dist`) should have this layout: +If everything good the package (located in `/python/dist`) should have +this layout: ``` {...}/dist/ortools-8.0.9999-cp38-cp38-.whl: \- ortools @@ -60,22 +72,25 @@ If everything good the package (located in `/python/dist`) should have \- __init__.py \- pywrap....py \- _pywrap....so -... +... ``` note: `` 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 .whl` to study their layout. +tips: since wheel package are just zip archive you can use `unzip -l .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