Skip to content

Commit e5d9d73

Browse files
committed
improve Embedding-Build-Tools.md
1 parent 3294a02 commit e5d9d73

File tree

1 file changed

+84
-99
lines changed

1 file changed

+84
-99
lines changed

docs/user/Embedding-Build-Tools.md

Lines changed: 84 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -7,78 +7,61 @@ permalink: /reference-manual/python/Embedding-Build-Tools/
77

88
# Embedding Build Tools
99

10-
The GraalPy **Maven** and **Gradle** plugins provide functionality to manage Python related resources typically
10+
The GraalPy **Maven** and **Gradle** plugins provide functionality to manage Python related resources
1111
required for embedding Python code in Java-based applications:
12-
1312
- *Python application files* provided by the user, for example, Python sources which are part of the project.
14-
- *Third-party Python packages*: installed by the plugin during the build according to the plugin configuration.
13+
- *Third-party Python packages* installed by the plugin during the build according to the plugin configuration.
1514
- *The Python standard library*, which is necessary to make Native Image generated executables self-contained.
1615

17-
Apart from physically managing and deploying those files, it is also necessary to make them available in Python
18-
at runtime by configuring the **GraalPy Context** in your Java code accordingly. [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) provides
19-
factory methods to create a Context preconfigured for accessing Python embedding relevant resources with
20-
a **Virtual Filesystem** or from a dedicated **external directory**.
16+
Apart from physically managing and deploying those files, it is also necessary to make them available in Python at runtime by configuring the **GraalPy Context** in your Java code accordingly.
17+
The [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) API provides factory methods to create a Context preconfigured for accessing Python, embedding relevant resources with a **Virtual Filesystem** or from a dedicated **external directory**.
2118

2219
## Deployment
2320

24-
There are two modes how to deploy the resources: as Java resources using the Virtual Filesystem
25-
to access them in Python, or as an external directory.
21+
There are two modes how to deploy the resources: as Java resources using the Virtual Filesystem to access them in Python, or as an external directory.
2622

2723
### Virtual Filesystem
2824

2925
The Python related resources are embedded in the application file, either in JAR or Native Image generated
30-
executable, as standard Java resources. The GraalPy Virtual Filesystem accesses resource files as standard
31-
Java resources and makes them available to Python code running in GraalPy. This is transparent to the Python code,
32-
which can use standard Python IO to access those files.
26+
executable, as standard Java resources.
27+
The GraalPy Virtual Filesystem accesses resource files as standard Java resources and makes them available to Python code running in GraalPy.
28+
This is transparent to the Python code, which can use standard Python IO to access those files.
3329

3430
Java resource files in a Maven or Gradle project are typically located in dedicated resources directories.
35-
All resources subdirectories named `org.graalvm.python.vfs` are merged and mapped to a configurable
36-
virtual filesystem mount point at the Python side, by default `/graalpy_vfs`. For example,
37-
a Python file with the real filesystem path
38-
`${project_resources_directory}/org.graalvm.python.vfs/src/foo/bar.py` will be accessible as
39-
`/graalpy_vfs/src/foo/bar.py` in Python.
31+
All resources subdirectories named _org.graalvm.python.vfs_ are merged and mapped to a configurable Virtual Filesystem mount point at the Python side, by default `/graalpy_vfs`.
32+
For example, a Python file with the real filesystem path `${project_resources_directory}/org.graalvm.python.vfs/src/foo/bar.py` will be accessible as `/graalpy_vfs/src/foo/bar.py` in Python.
4033

4134
Use the following [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java)
4235
factory methods to create GraalPy Context preconfigured for the use of the Virtual Filesystem:
43-
4436
* `GraalPyResources.createContext()`
4537
* `GraalPyResources.contextBuilder()`
4638
* `GraalPyResources.contextBuilder(VirtualFileSystem)`
4739

4840
### External Directory
4941

50-
As an alternative to Java resources with the Virtual Filesystem, it is also possible to configure the Maven
51-
or Gradle plugin to manage the contents of an external directory, which will **not be embedded** as Java resource
52-
into the resulting application. The user is then responsible for the deployment of such directory. Python code
53-
will access the files directly from the real filesystem.
54-
55-
Use the following [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java)
56-
factory methods to create GraalPy Context preconfigured for the use of an external directory:
42+
As an alternative to Java resources with the Virtual Filesystem, it is also possible to configure the Maven or Gradle plugin to manage the contents of an external directory, which will **not be embedded** as a Java resource into the resulting application.
43+
A user is then responsible for the deployment of such directory.
44+
Python code will access the files directly from the real filesystem.
5745

46+
Use the following [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) factory methods to create GraalPy Context preconfigured for the use of an external directory:
5847
* `GraalPyResources.createContextBuilder(Path)`
5948

6049
## Conventions
6150

62-
The factory methods in [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) rely on the following conventions, where the `${root}` is either
63-
the external directory, or the Virtual System mount point on the Python side and
64-
`${project_resources_directory}/org.graalvm.python.vfs` on the real filesystem:
65-
66-
- `${root}/src`: used for Python application files. This directory will be configured as the default
67-
search path for Python module files (equivalent of `PYTHONPATH` environment variable).
68-
- `${root}/venv`: used for the Python virtual environment holding installed third-party Python packages.
69-
The Context will be configured as if it were executed from this virtual environment. Notably packages installed in this
51+
The factory methods in [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) rely on the following conventions, where the `${root}` is either an external directory, or a Virtual System mount point on the Python side and `${project_resources_directory}/org.graalvm.python.vfs` on the real filesystem:
52+
- `${root}/src`: used for Python application files. This directory will be configured as the default search path for Python module files (equivalent to `PYTHONPATH` environment variable).
53+
- `${root}/venv`: used for the Python virtual environment holding installed third-party Python packages.
54+
The Context will be configured as if it is executed from this virtual environment. Notably packages installed in this
7055
virtual environment will be automatically available for importing.
71-
- `${root}/home`: used for the Python standard library (equivalent of `PYTHONHOME` environment variable).
56+
- `${root}/home`: used for the Python standard library (equivalent to `PYTHONHOME` environment variable).
7257

73-
The Maven or Gradle plugin will fully manage the contents of the `vevn` and `home` subdirectories.
58+
The Maven or Gradle plugin will fully manage the contents of the `venv` and `home` subdirectories.
7459
Any manual changes in these directories will be overridden by the plugin during the build.
75-
76-
- `${root}/venv`: the plugin creates virtual environment and installs required packages according
77-
to the plugin configuration in `pom.xml` or `build.gradle`.
60+
- `${root}/venv`: the plugin creates a virtual environment and installs required packages according to the plugin configuration in _pom.xml_ or _build.gradle_.
7861
- `${root}/home`: the plugin copies the required (also configurable) parts of the Python standard library into this directory.
7962
By default, the full standard library is used.
8063

81-
The `src` subdirectory is left to be manually populated by the user with custom Python scripts or modules.
64+
The _src_ subdirectory is left to be manually populated by the user with custom Python scripts or modules.
8265

8366
## GraalPy Maven Plugin Configuration
8467

@@ -92,77 +75,79 @@ Add the plugin configuration in the `configuration` block of `graalpy-maven-plug
9275
...
9376
</configuration>
9477
...
78+
</plugin>
9579
```
96-
9780
The **packages** element declares a list of third-party Python packages to be downloaded and installed by the plugin.
98-
- The Python packages and their versions are specified as if used with `pip`.
99-
```xml
100-
<configuration>
101-
<packages>
102-
<package>termcolor==2.2</package>
103-
...
104-
</packages>
105-
...
106-
</configuration>
107-
```
81+
- The Python packages and their versions are specified as if used with `pip`:
82+
```xml
83+
<configuration>
84+
<packages>
85+
<package>termcolor==2.2</package>
86+
...
87+
</packages>
88+
...
89+
</configuration>
90+
```
10891
- The **pythonHome** subsection declares what parts of the standard library should be deployed.
10992

11093
Each `include` and `exclude` element is interpreted as a Java-like regular expression specifying which file paths should be included or excluded.
111-
112-
```xml
113-
<configuration>
114-
<pythonHome>
115-
<includes>
116-
<include>.*</include>
117-
...
118-
</includes>
119-
<excludes>
120-
<exclude></exclude>
121-
...
122-
</excludes>
123-
</pythonHome>
124-
...
125-
</configuration>
126-
```
127-
- If the **pythonResourcesDirectory** element is specified, then the given directory is used
128-
as [external directory](#external-directory) and no Java resources are embedded.
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 as an [external directory](#external-directory) and no Java resources are embedded.
129110
Remember to use the appropriate `GraalPyResources` API to create the Context.
130-
```xml
131-
<configuration>
132-
<pythonResourcesDirectory>${basedir}/python-resources</pythonResourcesDirectory>
133-
...
134-
</configuration>
135-
```
111+
```xml
112+
<configuration>
113+
<pythonResourcesDirectory>${basedir}/python-resources</pythonResourcesDirectory>
114+
...
115+
</configuration>
116+
```
136117

137118
## GraalPy Gradle Plugin Configuration
138119

139-
Add the plugin configuration in the `GraalPy` block in the _build.gradle_ file:
120+
Add the plugin configuration in the `GraalPy` block in the _build.gradle_ file.
140121
The **packages** element declares a list of third-party Python packages to be downloaded and installed by the plugin.
141122
- The Python packages and their versions are specified as if used with `pip`.
142-
```
143-
GraalPy {
144-
packages = ["termcolor==2.2"]
145-
...
146-
}
147-
```
148-
- the **pythonHome** subsection declares what parts of the standard library should be deployed.
123+
```
124+
graalPy {
125+
packages = ["termcolor==2.2"]
126+
...
127+
}
128+
```
129+
- The **pythonHome** subsection declares what parts of the standard library should be deployed.
149130

150131
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.
151-
```
152-
GraalPy {
153-
pythonHome {
154-
includes = [".*"]
155-
excludes = []
132+
```
133+
graalPy {
134+
pythonHome {
135+
includes = [".*"]
136+
excludes = []
137+
}
138+
...
156139
}
157-
...
158-
}
159-
```
160-
- If the **pythonResourcesDirectory** element is specified, then the given directory is used
161-
as [external directory](#external-directory) and no Java resources are embedded.
162-
Remember to use the appropriate `GraalPyResources` API to create the Context.
163-
```
164-
GraalPy {
165-
pythonResourcesDirectory = file("$rootDir/python-resources")
166-
...
167-
}
168-
```
140+
```
141+
- If the **pythonResourcesDirectory** element is specified, then the given directory is used as an [external directory](#external-directory) and no Java resources are embedded.
142+
Remember to use the appropriate `GraalPyResources` API to create the Context.
143+
```
144+
graalPy {
145+
pythonResourcesDirectory = file("$rootDir/python-resources")
146+
...
147+
}
148+
```
149+
150+
### Related Documentation
151+
152+
* [Embedding Graal languages in Java](https://www.graalvm.org/reference-manual/embed-languages/)
153+
* [Permissions for Python Embeddings](Embedding-Permissions.md)

0 commit comments

Comments
 (0)