document usage of pyinstaller for orekit and orekit data

README.md

@@ -47,24 +47,24 @@ Each model has advantages and disadvantages.
 - Seems to have a slight performance hit (~10% increase in time in some very basic tests)
 
 # Installation
-    
+
     if using mamba/conda:
 
     mamba install -c conda-forge jpype1
 
 
- 
+
     git clone https://gitlab.orekit.org/Petrush/orekit_jpype.git
     pip install . -vv
 
     The pip will also install the orekitdata package from the orekitdata git respotory.
 
- 
+
  # Development
- 
-    To generate stub files, use the stubgenj package 
+
+    To generate stub files, use the stubgenj package
     https://gitlab.cern.ch/scripting-tools/stubgenj
-    
+
     and command line:
     python -m stubgenj --convert-strings --classpath "orekit_jpype/jars/*.jar" org.orekit  org.hipparchus java
 
@@ -74,11 +74,11 @@ Each model has advantages and disadvantages.
 
     To upload to pypi:
 
-    python3 -m twine upload --repository testpypi dist/*     
+    python3 -m twine upload --repository testpypi dist/*
 
     To install (something like):
 
-    pip install -i https://test.pypi.org/simple/ orekit-jpype==12.0.2.dev2     
+    pip install -i https://test.pypi.org/simple/ orekit-jpype==12.0.2.dev2
 
 # usage
 See the example notebooks and the package test folder for examples.
@@ -95,3 +95,46 @@ In the JCC version, the interfaces are implemented as special classes named Pyth
 ### Subclassing of Orekit abstract classes
 In the JCC version of Orekit it is possible to subclass classes from the set of PythonClassName classes. This is not possible in the Jpype version of Orekit, which is limited to implementation of interfaces only.
 
+
+# Packaging a project with `pyinstaller`
+
+This repository contains hooks for `pyinstaller` so that your project relying on Orekit can be packaged into an executable. No additional arguments are needed to `pyinstaller` thanks to the hooks, as long as `orekit_jpype` is installed in your Python packages.
+
+## Packaging the orekit data folder or library
+
+### Using the orekitdata Python library
+
+If you are using the [orekit data repository as a Python library](https://gitlab.orekit.org/orekit/orekit-data#notes-for-orekit-python-users), as the Orekit data files are not Python files, you have to specify the following option to `pyinstaller` to collect them into your executable:
+
+```bash
+pyinstaller --collect-data orekitdata <your main Python script>
+```
+
+This will create a folder `dist/` containing your executable.
+
+### Locally managed orekit data folder
+
+If the `orekit-data` folder is located in the same folder as your main Python script, you can for instance use the following syntax to load the orekit data in your Python code:
+
+```python
+from orekit_jpype.pyhelpers import setup_orekit_data
+dirpath = os.path.dirname(os.path.abspath(__file__))
+setup_orekit_data(filenames=os.path.join(dirpath, "orekit-data"), from_pip_library=False)
+```
+
+Then you can use the following option to package your `orekit-data` folder in your executable.
+
+```bash
+pyinstaller --add-data orekit-data/*:./orekit-data/ <your main Python script>
+```
+
+This will create a folder `dist/` containing your executable.
+
+## For developers: testing the hook
+
+```bash
+python -m PyInstaller.utils.run_tests --include_only orekit_jpype._pyinstaller
+```
+
+This will package a minimal executable containing orekit_jpype, orekitdata and run the test case `test/OrekitDataLoadOnlyLibTest.py` to test that everything works as expected.
+TODO: include this test procedure in a CI pipeline.