You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Substrate VM is an internal project name for the technology behind [GraalVM Native Image](../README.md).
4
4
This guide shows how to set up a development environment for the project.
5
5
6
-
To get started, install [mx](https://github.com/graalvm/mx).
7
-
Then point the `JAVA_HOME` variable to a JDK that supports a compatible version
8
-
of the JVM Compiler Interface (JVMCI). JVMCI is a privileged, low-level interface
9
-
to the JVM that can read metadata from the VM, such as method bytecode, and
10
-
install machine code into the VM. Obtain JVMCI-enabled:
11
-
* JDK 8 from [GitHub](https://github.com/graalvm/openjdk8-jvmci-builder/releases)
12
-
* JDK 11 from [GitHub](https://github.com/graalvm/labs-openjdk-11/releases)
13
-
14
-
#### Prerequisites
15
-
For compilation, `native-image` depends on the local toolchain. Install
16
-
`glibc-devel`, `zlib-devel` (header files for the C library and `zlib`) and
17
-
`gcc`, using a package manager available on your OS. Some Linux distributions
18
-
may additionally require `libstdc++-static`.
19
-
20
-
On Windows, Native Image requires Visual Studio 2022 version 17.1.0 or later.
6
+
## Quick Start Guide
7
+
8
+
This quick start guide walks you through building Native Image on a Linux computer.
9
+
For other operating systems, some commands need to be adjusted.
10
+
11
+
### Prerequisites
12
+
For compilation, `native-image` depends on the local toolchain.
13
+
Install `glibc-devel`, `zlib-devel` (header files for the C library and `zlib`) and `gcc`, using a package manager available on your OS.
14
+
Some Linux distributions may additionally require `libstdc++-static`.
15
+
16
+
On Windows, Native Image requires Visual Studio 2022 version 17.6.0 or later.
17
+
18
+
For our build system `mx` you will need an installation of Python, version 3.8 or later.
19
+
20
+
### Clone the Required Repositories
21
+
22
+
First, clone [mx](https://github.com/graalvm/mx), which is GraalVM's build system.
23
+
Add the `mx` directory to the `PATH` environment variable.
24
+
25
+
Then clone or download the [graal](https://github.com/oracle/graal) repository.
26
+
27
+
It is good practice to have `mx` and `graal` as sibling directories.
28
+
If you later add additional GraalVM projects, like Truffle-based languages, they need to be in sibling directories of `graal`.
29
+
30
+
```
31
+
workspace
32
+
|- mx
33
+
|- graal
34
+
|- graal-js (optional)
35
+
|- graalpython (optional)
36
+
|- ...
37
+
```
38
+
39
+
### Install a Compatible JDK
40
+
41
+
GraalVM Native Image is bleeding-edge technology that relies on the latest Java version.
42
+
Therefore, you must also use the latest JVM.
43
+
The easiest way to download a compatible version is to use `mx`:
44
+
45
+
```shell
46
+
mx fetch-jdk
47
+
export JAVA_HOME=... (path to the JDK downloaded by fetch-jdk)
48
+
```
49
+
50
+
Note that you might have to repeat this step if you pull a newer version of the `graal` repository.
51
+
The JDK updates typically happen in a weekly cadence.
52
+
53
+
### Build and Test Native Image
54
+
55
+
Once you have all the requirements in place, you can build `substratevm`:
21
56
22
57
```shell
58
+
cd /path/to/graal
23
59
cd substratevm
24
60
mx build
61
+
```
62
+
63
+
The build should terminate without any error.
64
+
On a built `substratevm`, you can try your first Hello World example:
25
65
66
+
```shell
26
67
echo"public class HelloWorld { public static void main(String[] args) { System.out.println(\"Hello World\"); } }"> HelloWorld.java
27
68
$JAVA_HOME/bin/javac HelloWorld.java
28
69
mx native-image HelloWorld
29
70
./helloworld
30
71
```
31
72
32
-
To build polyglot images, refer to the documentation in the [VM suite](../../../../vm/README.md).
33
-
34
-
## Build Native Image
73
+
### Use an IDE for Development
35
74
36
-
Using Native Image in a development environment requires the `mx` tool to be installed first, so that it is on your `PATH`.
37
-
Visit the [MX Homepage](https://github.com/graalvm/mx) for more details.
75
+
Common IDEs like IntelliJ IDEA can be used for development.
76
+
To initialize the required project files, use the `ideinit` command:
38
77
39
-
In the main directory, invoke `mx help` to see the list of commands.
40
-
Most of the commands are inherited from the [Graal](https://github.com/oracle/graal) and [Truffle](https://github.com/oracle/graal/tree/master/truffle) code bases.
41
-
More information on a specific command is available by running `mx help <command>`.
42
-
The most important commands are:
78
+
```shell
79
+
cd substratevm
80
+
mx ideinit
81
+
```
43
82
44
-
*`build`: compile all Java and native code
45
-
*`clean`: remove all compilation artifacts
46
-
*`ideinit`: create project files for Eclipse and other common IDEs
47
83
See the [documentation on IDE integration](../../../../compiler/docs/IDEs.md) for details.
48
84
49
-
## Build Native Executables
50
-
51
-
After running `mx build` you can use `mx native-image` to build a native executable.
52
-
You can specify the main entry point, that is, the application for wish you want to create the executable. For more information run `mx native-image --help`.
85
+
## Debug the Native Image Build Process
53
86
54
-
A native image generation is performed by a Java program, a Native Image builder, that runs on a JVMCI-enabled JDK. You can debug it with a regular Java debugger.
87
+
A native image generation is performed by a Java program, the Native Image builder.
88
+
You can debug it with a regular Java debugger.
55
89
Use `mx native-image --debug-attach` to start native image generation so that it waits for a Java debugger to attach first (by default, at port 8000).
56
-
In Eclipse, use the debugging configuration _substratevm-localhost-8000_ to attach to it. This debugging configuration is automatically generated by `mx ideinit`.
90
+
In IDEA, use the debugging configuration _substratevm-localhost-8000_ to attach to it.
91
+
This debugging configuration is automatically generated by `mx ideinit`.
57
92
58
93
If you have to debug the compiler graphs that are built as part of an image, proceed to the [debugging](../../../../compiler/docs/Debugging.md) page.
59
94
You can use the [Ideal Graph Visualizer (IGV)](https://www.graalvm.org/latest/tools/igv/) tool to view individual compilation steps:
For information how to debug a built image, see [Debug Information](../DebugInfo.md).
103
+
A broader overview of the topic is shown in [Debugging and Diagnostics](../DebuggingAndDiagnostics.md).
104
+
65
105
## Options
66
106
107
+
The build process can be configured by **Hosted options**.
108
+
These options use the prefix `-H:` and influence, for example, what is included in the native binary and how it is built.
109
+
110
+
In contrast, **Runtime options** are consumed later, at image runtime.
111
+
Their initial value(s) can be set at image build time, using the prefix `-R:`.
112
+
At runtime, the default prefix for such options is `-XX:` (this is application-specific and not mandated by Native Image).
113
+
67
114
More information about options and the important distinction between hosted and runtime options is available [here](../docs/reference-manual/native-image/BuildOptions.md).
68
115
69
-
## Project Structure
116
+
## Build System: mx
70
117
71
-
The list of projects is defined in a custom format in the file `mx.substratevm/suite.py`. It is never necessary to create new projects in the IDE.
72
-
Instead, a new project is created by adding it in `suite.py` and running `mx ideinit` to generate a corresponding IDE project.
118
+
`mx` is GraalVM's own build system.
119
+
Invoke `mx help` to see the list of commands.
120
+
Most of the commands are inherited from the [Graal](https://github.com/oracle/graal) and [Truffle](https://github.com/oracle/graal/tree/master/truffle) code bases.
121
+
More information on a specific command is available by running `mx help <command>`.
122
+
The most important commands are:
73
123
74
-
## Code Formatting
124
+
*`build`: compile all Java and native code
125
+
*`clean`: remove all compilation artifacts
126
+
*`ideinit`: create project files for IDEA, Eclipse, or other common IDEs
75
127
76
-
Style rules and procedures for checking adherence are described in the [style guide](CodeStyle.md).
128
+
### Suites
129
+
Applications based on `mx` are structured in so-called "suites", implemented in subdirectories.
130
+
For `graal`, the most prominent ones are `compiler` and `substratevm`.
131
+
Many of the `mx` commands only work when executed from inside a suite (i.e. you need to `cd` into the directory first).
132
+
133
+
### Projects
134
+
The list of projects is defined in a custom format in the file _mx.substratevm/suite.py_.
135
+
A new project is created by adding it in _suite.py_ and running `mx ideinit` to generate a corresponding IDE project.
136
+
Do not manually create them in the IDE, such projects would be deleted by `mx ideinit`.
77
137
78
-
## Troubleshooting Eclipse
138
+
## Troubleshoot IDEs
79
139
80
-
Sometimes, Eclipse gives strange error messages, especially after pulling a
81
-
bigger changeset. Also, projects are frequently added or removed, leading to
82
-
error messages about missing projects if you do not import new projects. The
83
-
following should reset everything:
140
+
Sometimes, IDEs give strange error messages, especially after pulling a bigger changeset.
141
+
Also, projects are frequently added or removed, leading to error messages about missing projects if you do not import new projects.
142
+
The following should reset everything:
84
143
85
-
* Delete all projects in Eclipse
144
+
* Delete all projects the IDE
86
145
*`mx clean`
87
146
*`mx ideclean`
88
147
*`mx fsckprojects`
89
148
*`mx build`
90
149
*`mx ideinit`
91
-
* Import all projects into Eclipse again
150
+
* Import all projects into IDE again
92
151
93
152
## Usage Documentation
94
153
95
154
The documentation on how to use Native Image is available [here](../README.md) or [on the website](https://www.graalvm.org/reference-manual/native-image/).
96
155
156
+
## Code Formatting
157
+
158
+
Style rules and procedures for checking adherence are described in the [style guide](CodeStyle.md).
159
+
97
160
## License
98
161
99
162
The Substrate VM project is licensed under the GPL 2 with Classpath Exception.
0 commit comments