doc: Add internal readme

2020-10-05 21:18:52 +02:00
parent 9a5e54368f
commit f077c5d338
3 changed files with 243 additions and 3 deletions
--- a/ortools/dotnet/README.md
+++ b/ortools/dotnet/README.md
@@ -1,8 +1,10 @@
 # Introduction
-This is the documentation page for the .NETStandard2.0 wrapper of OR-Tools.
+This is the documentation page for the .NET Standard 2.0 wrapper of OR-Tools.
+
+This project aim to explain how you build a .Net native (for win-x64, linux-x64 and osx-x64) nuget package using `dotnet` and few `.csproj`.

 ## Table of Content
-* [Pre-requisites](#pre-requisites)
+* [Requirement](#requirement)
 * [Directory Layout](#directory-layout)
 * [Build](#build)
  * [Build Process](#build-process)
@@ -18,7 +20,7 @@ This is the documentation page for the .NETStandard2.0 wrapper of OR-Tools.
  * [Issues](#issues)
 * [Misc](#misc)

-## Pre-requisites
+# Requirement
 The library is compiled against `netstandard2.0`, so you'll only need: 
 - .Net Core SDK >= 2.1.302

--- a/ortools/java/README.md
+++ b/ortools/java/README.md
@@ -0,0 +1,155 @@
+# 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).
+
+## 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)
+* [Appendices](#appendices)
+  * [Ressources](#ressources)
+* [Misc](#misc)
+
+# 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.
+* [Loader.java](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
+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
+supported platform targeted and containing the native libraries.
+- 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)
+![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`.  
+
+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.
+
+Then you can generate the package and install it locally using:
+```bash
+mvn package
+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:
+```
+{...}/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.
+
+### 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:
+  ```xml
+  <dependency>
+    <groupId>com.google.ortools</groupId>
+    <artifactId>ortools-linux-x86-64</artifactId>
+    <version>[8.0,)</version>
+    <type>jar</type>
+    <scope>runtime</scope>
+  </dependency>
+  ```
+  - Add dependency to jna so we can find at runtime the current `<platform>`:
+  ```xml
+  <dependency>
+    <groupId>net.java.dev.jna</groupId>
+    <artifactId>jna-platform</artifactId>
+    <version>5.5.0</version>
+  </dependency>
+  ```
+
+Then you can generate the package using:
+```bash
+mvn package
+mvn install
+```
+
+If everything good the package (located in `<buildir>/java/ortools-java/target/`) should have this layout:
+```
+{...}/target/ortools-java-8.0.jar:
+\- com/
+   \- google/
+      \- ortools/
+         \- Loader$PathConsumer.class
+         \- Loader$1.class
+         \- Loader.class
+         \- constraintsolver/
+            \- RoutingModel.class
+            \- RoutingIndexManager.class
+            \- ...
+         \- ...
+... 
+```
+
+### Testing local Package 
+We can test everything is working by using any sample project.
+
+First you can build it using:
+```
+cmake --build build
+```
+note: `ortools-java` which is locally installed in the local maven cache
+(`~/.m2/repository/com/google/ortools/ortools-java/...`).
+
+Then you can run it using:
+```sh
+cmake --build build --target test
+```
+or manually using:
+```
+cd <builddir>/java/component/example
+mvn compile
+mvn exec:java
+```
+
+# Appendices
+Few links on the subject...
+
+## 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)
+
+# Misc
+Image has been generated using [plantuml](http://plantuml.com/):
+```bash
+plantuml -Tsvg doc/{file}.dot
+```
+So you can find the dot source files in [doc](doc).
--- a/ortools/python/README.md
+++ b/ortools/python/README.md
@@ -0,0 +1,83 @@
+# Introduction
+This is the documentation page for the Python 3.5+ 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/).
+
+## 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)
+* [Appendices](#appendices)
+  * [Ressources](#ressources)
+* [Misc](#misc)
+
+# Requirement
+You'll need "Python >= 3.5" and few python modules ("wheel" and "six").
+
+# Directory Layout
+* [setup.py.in](setup.py.in) `Setup.py` template to build the python native project.
+
+# 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.
+
+[`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)
+![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.  
+
+Here some dev-note concerning this `setup.py`.
+- This package is a native package containing native libraries.
+
+Then you can generate the package and install it locally using:
+```bash
+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:
+```
+{...}/dist/ortools-8.0.9999-cp38-cp38-<platform>.whl:
+\- ortools
+   \- __init__.py
+   \- .libs
+      \- libortools.so
+   \- constraint_solver
+      \- __init__.py
+      \- pywrapcp.py
+      \- _pywrapcp.so
+   \- ...
+      \- __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.
+
+# Appendices
+Few links on the subject...
+
+## 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/)
+
+# Misc
+Image has been generated using [plantuml](http://plantuml.com/):
+```bash
+plantuml -Tsvg doc/{file}.dot
+```
+So you can find the dot source files in [doc](doc).