Skip to content

Commit 2c0e8fc

Browse files
tomasstupkatomasstupka
committed
added gradle and maven plugin docs
1 parent 9d40408 commit 2c0e8fc

File tree

2 files changed

+212
-32
lines changed

2 files changed

+212
-32
lines changed

‎docs/user/Embedding-Build-Tools.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
layout: docs
3+
toc_group: python
4+
link_title: Embedding Build Tools
5+
permalink: /reference-manual/python/Embedding-Build-Tools/
6+
---
7+
8+
# Embedding Build Tools
9+
10+
The GraalPy Maven and Gradle plugins provide functionality to manage resources required for embedding Python in Java-based applications:
11+
12+
This embedding relevant resources can be one of the following:
13+
- Python application files, for example, Python sources which are part of the project.
14+
- Third-party Python packages which can be accessed either from the projects Python sources or from Java.
15+
- The Standard library which is necessary to make a generated native executable self-contained.
16+
17+
Besides physically managing and distributing this files by the plugins, it is also necessary to make them available at runtime by accordingly
18+
configuring the GraalPy context in your Java code. `GraalPyResources.java` TODO - how link to file/javadoc? provides factory methods
19+
to create a **GraalPy context** suitable for accessing Python embedding relevant resources with a **virtual filessystem** or from a dedicated **external directory**.
20+
21+
### Virtual filesystem
22+
23+
Resource files in a Maven or Gradle project are typically located in dedicated project resource directories, and then distributed in
24+
one application file (JAR or native image).
25+
26+
The GraalPy virtual filesystem can access resource files as standard Java resources and make them available to Python code running in GraalPy so
27+
that it can use standard Python IO to access those files.
28+
29+
Each kind of the resource files is held in a different project resource directory:
30+
- `${project_resources_directory}/org.graalvm.python.vfs/src` - is used for Python application files. Contents of this directory are not directly managed by the plugin,
31+
only added to the final application file (JAR or native image).
32+
- `${project_generated_resources_directory}/org.graalvm.python.vfs/venv` - this directory is used for the Python virtual environment holding third-party Python packages
33+
and its contents are generated and managed entirely by the plugin. Any manual changes may be overwritten.
34+
- `${project_generated_resources_directory}/org.graalvm.python.vfs/home` - this directory is used for the Standard library
35+
and its contents are generated and managed entirely by the plugin. Any manual changes may be overwritten.
36+
37+
`GraalPyResources.java` provides factory methods to create a GraalPy context with a default or custom virtual filesystem configuration.
38+
For more information on how to configure a virtual filesystem, refer to `VirtualFileSystem.Builder` TODO - how link to file/javadoc?.
39+
40+
### Resources in an external directory
41+
42+
As an alternative to the virtual filesystem, it is also possible to configure the plugin to hold the resource files in an external directory.
43+
`GraalPyResources.java` provides methods to create a GraalPy context preconfigured to work with a dedicated resources directory as long at it has the following structure:
44+
- `${resources_directory}/src` - is used for Python application files. Contents of this directory are not directly managed by the plugin,
45+
only added to the final application file (JAR or native image).
46+
- `${resources_directory}/venv` - this directory is used for the Python virtual environment holding third-party Python packages
47+
and its contents are generated and managed entirely by the plugin. Any manual changes may be overwritten.
48+
- `${resources_directory}/home` - this directory is used for the Standard library
49+
and its contents are generated and managed entirely by the plugin. Any manual changes may be overwritten.
50+
51+
Note, that by storing the resource files in an external directory, they are not bundled with the application file (JAR or native image) and must be provided separately.
52+
53+
### GraalPy Context
54+
55+
Regarding the particular resource paths, a GraalPy context instance created by factory methods in `GraalPyResources` is preconfigured in the following way:
56+
- `${resources_root_directory}/home` - is reserved for the GraalPy Standard Library. GraalPy context will be configured to
57+
use this standard library as if set in `PYTHONHOME` environment variable.
58+
- `${resources_root_directory}/venv` - is reserved for a Python virtual environment holding third-party packages.
59+
The context will be configured as if it were executed from this virtual environment. Notably packages installed in this
60+
virtual environment will be automatically available for importing.
61+
- `${resources_root_directory}/src` - is reserved for python application files. GraalPy context will be configured to see those files as if set in `PYTHONPATH` environment variable.
62+
63+
where `${resources_root_directory}` is either the virtual filesystem resource root `/org.graalvm.python.vfs` or an external directory.
64+
65+
### GraalPy Maven Plugin Configuration
66+
67+
Add the plugin configuration in the `configuration` block of `graalpy-maven-plugin` in the _pom.xml_ file:
68+
```xml
69+
<plugin>
70+
<groupId>org.graalvm.python</groupId>
71+
<artifactId>graalpy-maven-plugin</artifactId>
72+
...
73+
<configuration>
74+
...
75+
</configuration>
76+
...
77+
```
78+
79+
The **packages** element declares a list of third-party Python packages to be downloaded and installed by the plugin.
80+
- The Python packages and their versions are specified as if used with `pip`.
81+
```xml
82+
<configuration>
83+
<packages>
84+
<package>termcolor==2.2</package>
85+
...
86+
</packages>
87+
...
88+
</configuration>
89+
```
90+
- The **pythonHome** subsection declares what parts of the standard library should be added to the final JAR file or native executable.
91+
92+
Each `include` and `exclude` element is interpreted as a Java-like regular expression specifying which file paths should be included or excluded.
93+
94+
```xml
95+
<configuration>
96+
<pythonHome>
97+
<includes>
98+
<include>.*</include>
99+
...
100+
</includes>
101+
<excludes>
102+
<exclude></exclude>
103+
...
104+
</excludes>
105+
</pythonHome>
106+
...
107+
</configuration>
108+
```
109+
- If the **pythonResourcesDirectory** element is specified, then the given directory is used for GraalPy resources instead of the standard Maven resource directories.
110+
```xml
111+
<configuration>
112+
<pythonResourcesDirectory>${basedir}/python-resources</pythonResourcesDirectory>
113+
...
114+
</configuration>
115+
```
116+
117+
### GraalPy Gradle Plugin Configuration
118+
119+
Add the plugin configuration in the `GraalPy` block in the _build.gradle_ file:
120+
The **packages** element declares a list of third-party Python packages to be downloaded and installed by the plugin.
121+
- The Python packages and their versions are specified as if used with `pip`.
122+
```
123+
GraalPy {
124+
packages = ["termcolor==2.2"]
125+
...
126+
}
127+
```
128+
- the **pythonHome** subsection declares what parts of the standard library should be added to the final JAR file or native executable.
129+
130+
Each element in the `includes` and `excludes` list is interpreted as a Java-like regular expression specifying which file paths should be included or excluded.
131+
```
132+
GraalPy {
133+
pythonHome {
134+
includes = [".*"]
135+
excludes = []
136+
}
137+
...
138+
}
139+
```
140+
- If the **pythonResourcesDirectory** element is specified, then the given directory is used for GraalPy resources instead of the standard Gradle resource directories.
141+
```
142+
GraalPy {
143+
pythonResourcesDirectory = file("$rootDir/python-resources")
144+
...
145+
}
146+
```

‎docs/user/README.md

Lines changed: 66 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,15 @@ Other build systems (Ant, Make, CMake, ...) can also be used with a bit more man
1818

1919
GraalPy can generate a Maven project that embeds Python packages into a Java application using [Maven artefacts](https://mvnrepository.com/artifact/org.graalvm.python).
2020

21-
2221
1. Since version 24.0, the GraalPy project publishes a Maven archetype to generate a starter project:
2322
```bash
2423
mvn archetype:generate \
2524
-DarchetypeGroupId=org.graalvm.python \
2625
-DarchetypeArtifactId=graalpy-archetype-polyglot-app \
27-
-DarchetypeVersion=24.0.0
26+
-DarchetypeVersion=24.2.0
2827
```
2928

30-
2. Build a native executable using the [GraalVM Native Image](https://www.graalvm.org/latest/reference-manual/native-image/) plugin that was added for you automatically:
29+
2. Build a native executable using the [ GraalVM Native Image "tool"](https://www.graalvm.org/latest/reference-manual/native-image/) plugin that was added for you automatically:
3130
```bash
3231
mvn -Pnative package
3332
```
@@ -38,9 +37,10 @@ GraalPy can generate a Maven project that embeds Python packages into a Java app
3837
```
3938
The application prints "hello java" to the console.
4039

41-
The project uses the [GraalVM SDK Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) with additional features to manage Python virtual environments and integrate Python package dependencies with a Maven workflow.
40+
The project uses the [GraalVM Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) with additional features to manage Python virtual environments and integrate Python package dependencies with a Maven workflow.
4241
The Java code and the _pom.xml_ file are heavily documented and the generated code describes available features.
43-
(If you do not wish to use Maven, the archetype Java code also provides guidance to create a custom embedding.)
42+
43+
See also [Embedding Build Tools](Embedding-Build-Tools.md#graalpy-maven-plugin) for more information about the GraalPy Maven Plugin.
4444

4545
### Creating Cross-platform JARs with Native Python Packages
4646

@@ -88,34 +88,14 @@ In order to distribute the resulting application for other systems, follow these
8888
```
8989

9090
2. Open your project configuration file, _app/build.gradle_, and modify it as follows.
91-
- Include the GraalPy support and the [GraalVM SDK Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) in the `dependencies` section:
92-
93-
```
94-
implementation("org.graalvm.polyglot:polyglot:24.0.0")
95-
implementation("org.graalvm.polyglot:python:24.0.0")
96-
```
97-
98-
- We recommend you use the Java modules build. Add the appropriate plugin to the `plugins` section:
99-
```
100-
id("org.javamodularity.moduleplugin") version "1.8.12"
101-
```
91+
- Include the GraalPy support and the [GraalVM Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) in the `dependencies` section:
10292

103-
- To run the application as a module rather than from the classpath, edit the `application` section to look like this:
10493
```
105-
application {
106-
mainClass.set("interop.App")
107-
mainModule.set("interop")
108-
}
94+
implementation("org.graalvm.polyglot:polyglot:24.2.0")
95+
implementation("org.graalvm.polyglot:python:24.2.0")
10996
```
11097

111-
3. Create a new file named _app/src/main/java/module-info.java_ with the following contents:
112-
```java
113-
module interop {
114-
requires org.graalvm.polyglot;
115-
}
116-
```
117-
118-
4. Finally, replace the code in the file named _App.java_ as follows for a small Python embedding:
98+
3. Finally, replace the code in the file named _App.java_ as follows for a small Python embedding:
11999
```java
120100
package interop;
121101
@@ -130,14 +110,68 @@ In order to distribute the resulting application for other systems, follow these
130110
}
131111
```
132112
133-
5. Run the application with Gradle:
113+
4. Run the application with Gradle:
134114
```bash
135115
./gradlew run
136116
```
137117
The application prints "Hello Python!" to the console.
138118
139119
> Note: The performance of the GraalPy runtime depends on the JDK in which you embed it. For more information, see [Runtime Optimization Support](https://www.graalvm.org/latest/reference-manual/embed-languages/#runtime-optimization-support).
140120
121+
5. Optionally, you can also use a third-party Python package:
122+
123+
5.1. In _app/build.gradle_:
124+
- add the graalpy-gradle-plugin to the `plugins` section:
125+
```
126+
id "org.graalvm.python"
127+
```
128+
129+
- configure the GraalPy Gradle plugin:
130+
```
131+
graalPy {
132+
packages = ["termcolor==2.2"]
133+
}
134+
```
135+
136+
5.2, In _settings.gradle_, add the following build script configuration.
137+
Note that all buildscript blocks must appear before any plugins blocks.
138+
```
139+
buildscript {
140+
repositories {
141+
mavenCentral()
142+
maven {
143+
url "https://repo.gradle.org/gradle/libs-releases/"
144+
}
145+
}
146+
dependencies {
147+
classpath "org.graalvm.python:graalpy-gradle-plugin:24.2.0"
148+
}
149+
}
150+
```
151+
152+
5.3. Update the file named _App.java_ as follows:
153+
```java
154+
package interop;
155+
156+
import org.graalvm.polyglot.*;
157+
import org.graalvm.python.embedding.utils.GraalPyResources;
158+
159+
class App {
160+
...
161+
public static void main(String[] args) {
162+
try (Context context = GraalPyResources.createContext()) {
163+
String src = """
164+
from termcolor import colored
165+
colored_text = colored("hello java", "red", attrs=["reverse", "blink"])
166+
print(colored_text)
167+
""";
168+
context.eval("python", src);
169+
}
170+
}
171+
```
172+
173+
See also [Embedding Build Tools](Embedding-Build-Tools.md#graalpy-gradle-plugin) for more information about the GraalPy Gradle Plugin.
174+
141175
## Ant, CMake, Makefile or Other Build Systems Without Direct Support for Maven Dependencies
142176
143177
Some (often older) projects may be using Ant, Makefiles, CMake, or other build systems that do not directly support Maven dependencies.
@@ -160,13 +194,13 @@ GraalPy comes with a tool to obtain the required JAR files from Maven.
160194
In a POSIX shell:
161195
```bash
162196
export GRAALPY_HOME=$(graalpy -c 'print(__graalpython__.home)')
163-
"${GRAALPY_HOME}/libexec/graalpy-polyglot-get" -a python -o lib -v "24.0.0"
197+
"${GRAALPY_HOME}/libexec/graalpy-polyglot-get" -a python -o lib -v "24.2.0"
164198
```
165199
166200
In PowerShell:
167201
```
168202
$GRAALPY_HOME = graalpy -c "print(__graalpython__.home)"
169-
& "$GRAALPY_HOME/libexec/graalpy-polyglot-get" -a python -o lib -v "24.0.0"
203+
& "$GRAALPY_HOME/libexec/graalpy-polyglot-get" -a python -o lib -v "24.2.0"
170204
```
171205
172206
These commands download all GraalPy dependencies into the _lib_ directory.

0 commit comments

Comments
 (0)