From a4a281346899cdafb76e5cb6ee214038c1c14bec Mon Sep 17 00:00:00 2001 From: Olga Gupalo Date: Mon, 13 Dec 2021 14:08:40 +0200 Subject: [PATCH 1/4] Use rel paths on URLs instead of permalinks --- .../architecture-overview.md | 55 ++++++++-------- .../enterprise-overview/solutions-overview.md | 2 +- docs/examples/java-kotlin-aot.md | 2 +- docs/examples/mle-oracle.md | 6 +- docs/examples/native-image-examples.md | 2 +- docs/examples/polyglot-javascript-java-r.md | 2 +- .../graalvm-ce-container-images.md | 3 +- .../get-started-graalvm-community.md | 65 +++++++++---------- .../graalvm-community/linux-aarch64.md | 6 +- .../graalvm-community/linux.md | 22 +++---- .../graalvm-community/macos.md | 22 +++---- .../graalvm-community/windows.md | 19 +++--- .../get-started-graalvm-enterprise.md | 64 +++++++++--------- .../installation-linux-aarch64.md | 6 +- .../graalvm-enterprise/installation-linux.md | 24 ++++--- .../graalvm-enterprise/installation-macos.md | 24 ++++--- .../installation-windows.md | 23 ++++--- .../oci/compute-instances.md | 2 +- 18 files changed, 170 insertions(+), 179 deletions(-) diff --git a/docs/enterprise-overview/architecture-overview.md b/docs/enterprise-overview/architecture-overview.md index 512e250d54ff..5b97c800bfa0 100644 --- a/docs/enterprise-overview/architecture-overview.md +++ b/docs/enterprise-overview/architecture-overview.md @@ -10,12 +10,12 @@ It is designed to accelerate the execution of applications written in Java and o GraalVM Enterprise's polyglot capabilities make it possible to mix multiple programming languages in a single application while eliminating any foreign language call costs. This page provides developers, solution architects, and infrastructure architects with an architectural overview of GraalVM Enterprise, as well as information about runtime modes, supported platforms, available distributions, core and additional functionalities, and support levels for various features. -The conceptual overview and advantages of GraalVM Enterprise are described on the [Solutions Overview](https://docs.oracle.com/en/graalvm/enterprise/21/docs/overview/) page. +The conceptual overview and advantages of GraalVM Enterprise are described on the [Solutions Overview](solutions-overview.md) page. * [GraalVM Enterprise Architecture](#graalvm-enterprise-architecture) * [Runtime Modes](#runtime-modes) * [Available Distributions](#available-distributions) -* [Supported Platforms](#supported-platforms) +* [Certified Platforms](#certified-platforms) * [Distribution Components List](#distribution-components-list) * [Licensing and Support](#licensing-and-support) * [Experimental and Early Adopter Features](#experimental-and-early-adopter-features) @@ -29,38 +29,38 @@ The conceptual overview and advantages of GraalVM Enterprise are described on th The preceding diagram illustrates a complete high-level architecture of GraalVM Enterprise. -GraalVM adds an [advanced just-in-time (JIT) optimizing compiler](/reference-manual/compiler/), which is written in Java, to the HotSpot Java Virtual Machine. +GraalVM adds an [advanced just-in-time (JIT) optimizing compiler](../reference-manual/compiler.md), which is written in Java, to the HotSpot Java Virtual Machine. -In addition to running Java and JVM-based languages, GraalVM's [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) makes it possible to run JavaScript, Ruby, Python, and a number of other popular languages on the JVM. -With GraalVM Truffle, Java and other supported languages can directly interoperate with each other and pass data back and forth in the same memory space. +In addition to running Java and JVM-based languages, [GraalVM's language implementation framework (Truffle)](../../truffle/docs/README.md), makes it possible to run JavaScript, Ruby, Python, and a number of other popular languages on the JVM. +With Truffle, Java and other supported languages can directly interoperate with each other and pass data back and forth in the same memory space. ## Runtime Modes GraalVM Enterprise is unique as a runtime environment offering several modes of operation: JVM runtime mode, Native Image, Java on Truffle (the same Java applications can be run on either). #### JVM Runtime Mode -When running programs on the HotSpot JVM, GraalVM defaults to the [GraalVM compiler](/reference-manual/compiler/) as the top-tier JIT compiler. +When running programs on the HotSpot JVM, GraalVM defaults to the [GraalVM compiler](../reference-manual/compiler.md) as the top-tier JIT compiler. At runtime, an application is loaded and executed normally on the JVM. The JVM passes bytecodes for Java or any other JVM-native language to the compiler, which compiles that to the machine code and returns it to the JVM. -Interpreters for supported languages, written on top of the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/), are themselves Java programs that run on the JVM. +Interpreters for supported languages, written on top of the [Truffle framework](../../truffle/docs/README.md), are themselves Java programs that run on the JVM. #### Native Image -[Native Image](/reference-manual/native-image/) is an innovative technology that compiles Java code into a standalone binary executable or a native shared library. +[Native Image](../reference-manual/native-image/README.md) is an innovative technology that compiles Java code into a standalone binary executable or a native shared library. The Java bytecode that is processed during the native image build includes all application classes, dependencies, third party dependent libraries, and any JDK classes that are required. A generated self-contained native executable is specific to each individual operating systems and machine architecture that does not require a JVM. #### Java on Truffle -[Java on Truffle](/reference-manual/java-on-truffle/) is an implementation of the Java Virtual Machine Specification, built with the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/). +[Java on Truffle](../reference-manual/java-on-truffle/README.md) is an implementation of the Java Virtual Machine Specification, built with the [Truffle framework](../../truffle/docs/README.md). It is a complete Java VM that includes all core components, implements the same API as the Java Runtime Environment library, and reuses all JARs and native libraries from GraalVM. Java on Trufle is an experimental technology in GraalVM, available as of version 21.0.0. ## Available Distributions -GraalVM Enterprise distributions are based on Oracle JDK 8, 11, and 16. +GraalVM Enterprise distributions are based on Oracle JDK 8, 11, and 17. GraalVM Enterprise releases include all Oracle Java critical patch updates (CPUs), which are released on a regular schedule to remedy defects and known vulnerabilities. GraalVM Enterprise is available for Linux, macOS, and Windows platforms on x86 64-bit systems, and for Linux on ARM 64-bit system. -The GraalVM Enterprise distribution based on Oracle JDK 16 is experimental with [several known limitations](https://docs.oracle.com/en/graalvm/enterprise/21/docs/overview/known-issues/). +The GraalVM Enterprise distribution based on Oracle JDK 17 is experimental with [several known limitations](https://docs.oracle.com/en/graalvm/enterprise/21/docs/overview/known-issues/). Depending on the platform, the distributions are shipped as *.tar.gz* or *.zip* archives. ## Certified Platforms @@ -69,10 +69,10 @@ The following are the certified platforms for GraalVM Enterprise 21: | Operating System | Version | Architecture | Installation Guide | |------------------------------------ |-------------- |-------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Oracle Linux | 7, 8 | x86 64-bit, ARM 64-bit | [Installation Guide for Linux](/getting-started/installation-linux/) | -| Red Hat Enterprise Linux(RHEL) | 7, 8 | x86 64-bit | [Installation Guide for Linux](/getting-started/installation-linux/) | -| macOS | 10.14 (Mojave), 10.15 (Catalina) | x86 64-bit | [Installation Guide for macOS](/getting-started/installation-macos/) | -| Microsoft Windows | Server 2016, 2019 | x86 64-bit | [Installation Guide for Windows](/getting-started/installation-windows/) | +| Oracle Linux | 7, 8 | x86 64-bit, ARM 64-bit | [Installation Guide for Linux](../getting-started/graalvm-enterprise/oci/compute-instances.md) | +| Red Hat Enterprise Linux(RHEL) | 7, 8 | x86 64-bit | [Installation Guide for Linux](../getting-started/graalvm-enterprise/installation-linux.md) | +| macOS | 10.14 (Mojave), 10.15 (Catalina) | x86 64-bit | [Installation Guide for macOS](../getting-started/graalvm-enterprise/installation-macos.md) | +| Microsoft Windows | Server 2016, 2019 | x86 64-bit | [Installation Guide for Windows](../getting-started/graalvm-enterprise/installation-windows.md) | ## Distribution Components List @@ -91,24 +91,24 @@ GraalVM Enterprise consists of core and additional functionalities. **Utilities** * JavaScript REPL with the JavaScript interpreter * `lli` tool to directly execute programs from LLVM bitcode -* [GraalVM Updater](/reference-manual/graalvm-updater/) to install additional functionalities +* [GraalVM Updater](../reference-manual/graalvm-updater.md) to install additional functionalities ### Additional Functionalities GraalVM Enterprise core installation can be extended with more languages runtimes and utilities. Tools/Utilities: -* [Native Image](/reference-manual/native-image/) -- a technology to compile an application ahead-of-time into a native platform executable. -* [LLVM toolchain](/reference-manual/llvm/) -- a set of tools and APIs for compiling native programs to bitcode that can be executed on GraalVM. -* [Java on Truffle](/reference-manual/java-on-truffle/) -- a JVM implementation built upon the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/) to run Java via a Java bytecode interpreter. +* [Native Image](../reference-manual/native-image/README.md) -- a technology to compile an application ahead-of-time into a native platform executable. +* [LLVM toolchain](../reference-manual/llvm/README.md) -- a set of tools and APIs for compiling native programs to bitcode that can be executed on GraalVM. Runtimes: -* [Node.js](/reference-manual/js/) -- the Node.js 14.16.1 runtime for JavaScript -* [Python](/reference-manual/python/) -- Python 3.8.5 compatible -* [Ruby](/reference-manual/ruby/) -- Ruby 2.7.3 compatible -* [R](/reference-manual/r/) -- GNU R 4.0.3 compatible -* [GraalWasm](/reference-manual/wasm/) -- WebAssembly (Wasm) +* [Java on Truffle](../reference-manual/java-on-truffle/README.md) -- a JVM implementation built upon the [Truffle framework](../../truffle/docs/README.md) to run Java via a Java bytecode interpreter. +* [Node.js](../reference-manual/js/README.md) -- the Node.js 14.17.6 runtime for JavaScript +* [Python](../reference-manual/python/README.md) -- Python 3.8.5 compatible +* [Ruby](../reference-manual/ruby/README.md) -- Ruby 2.7.3 compatible +* [R](../reference-manual/r/README.md) -- GNU R 4.0.3 compatible +* [GraalWasm](../reference-manual/wasm/README.md) -- WebAssembly (Wasm) ## Licensing and Support @@ -143,9 +143,8 @@ The following table lists supported and experimental features in GraalVM Enterpr ## What to Read Next -Users who are new to GraalVM Enterprise or have little experience using it, continue to [Getting Started with GraalVM Enterprise](/getting-started//#install-graalvm-enterprise). +Users who are new to GraalVM Enterprise or have little experience using it, continue to [Getting Started with GraalVM Enterprise](../getting-started/graalvm-enterprise/get-started-graalvm-enterprise.md). Download and install GraalVM Enterprise on your local machine, try running the examples provided in the guide, or test GraalVM Enterprise with your workload. -We suggest you then look at more complex [Examples Applications](/docs/examples/). +We suggest you then look at more complex [Examples Applications](../examples/examples.md). -Developers, who have GraalVM Enterprise already installed or have experience using it in the past, can skip the getting started guide and proceed to the [Reference Manuals](/reference-manual/) for -in-depth coverage of GraalVM Enterprise technologies. +Developers, who have GraalVM Enterprise already installed or have experience using it in the past, can skip the getting started guide and proceed to the [Reference Manuals](../reference-manual/reference-manuals.md) for in-depth coverage of GraalVM Enterprise technologies. diff --git a/docs/enterprise-overview/solutions-overview.md b/docs/enterprise-overview/solutions-overview.md index 1f7a5dc3b625..25bcd89418b9 100644 --- a/docs/enterprise-overview/solutions-overview.md +++ b/docs/enterprise-overview/solutions-overview.md @@ -96,7 +96,7 @@ vulnerabilities. ## Get Started with GraalVM Enterprise -[Get started with GraalVM Enterprise](/getting-started/) and: +[Get started with GraalVM Enterprise](../getting-started/graalvm-enterprise/get-started-graalvm-enterprise.md) and: * reduce IT and storage costs * provide customers with quicker response time * employ fewer resources, freeing up CPU diff --git a/docs/examples/java-kotlin-aot.md b/docs/examples/java-kotlin-aot.md index 725c4b71cf6f..dcca8454177f 100644 --- a/docs/examples/java-kotlin-aot.md +++ b/docs/examples/java-kotlin-aot.md @@ -38,7 +38,7 @@ export GRAALVM_HOME=/Users/${current_user}/path/to/graalvm/Contents/Home ``` Note that your paths are likely to be different depending on the download location. -3. [Install Native Image](../reference-manual/native-image/README.md/#install-native-image) to make use of the `native-image` utility. +3. [Install Native Image](../reference-manual/native-image/README.md#install-native-image) to make use of the `native-image` utility. 4. Then execute: ```shell diff --git a/docs/examples/mle-oracle.md b/docs/examples/mle-oracle.md index 3806fd535cfe..be336d69dca2 100644 --- a/docs/examples/mle-oracle.md +++ b/docs/examples/mle-oracle.md @@ -46,9 +46,9 @@ END; / ``` -Please also note the EXCEPTION clause which makes sure that the context gets dropped either way. This is important to avoid resource leakage. +Note: There is the `EXCEPTION` clause which makes sure that the context gets dropped either way. This is important to avoid resource leakage. -2. Now here's an example that shows how values can be passed between PL/SQL and MLE. As expected, the output is `49`: +2. Now here is an example that shows how values can be passed between PL/SQL and MLE. As expected, the output is `49`: ```sql SET SERVEROUTPUT ON; DECLARE @@ -139,6 +139,7 @@ END; ``` ## Type Conversions + Let us now have a closer look at conversions from Oracle types (as retrieved by SQL queries) to JavaScript types. By default, Oracle data types get automatically converted to regular, native JavaScript types, which can lead to a loss of precision. @@ -249,6 +250,7 @@ END; ``` ## Further Reading + Here is a set of resources that we recommend for further reading about MLE: - [Multilingual Engine: Executing JavaScript in Oracle Database](https://medium.com/graalvm/mle-executing-javascript-in-oracle-database-c545feb1a010) provides further insight into the MLE architecture based on GraalVM. - [MLE and the Future of Server-Side Programming in Oracle APEX](https://blogs.oracle.com/apex/mle-and-the-future-of-server-side-programming-in-oracle-apex) shows step-by-step how to set up a free Oracle Cloud account, provision a database instance and run some JavaScript code in Oracle APEX (powered by MLE). diff --git a/docs/examples/native-image-examples.md b/docs/examples/native-image-examples.md index b1412280e053..cc24d0c1bbb2 100644 --- a/docs/examples/native-image-examples.md +++ b/docs/examples/native-image-examples.md @@ -38,7 +38,7 @@ export GRAALVM_HOME=/Users/${current_user}/path/to/graalvm/Contents/Home ``` Note that your paths are likely to be different depending on the download location. -3. [Install Native Image](../reference-manual/native-image/README.md/#install-native-image) to make use of the `native-image` utility. +3. [Install Native Image](../reference-manual/native-image/README.md#install-native-image) to make use of the `native-image` utility. 4. Then execute: ```shell diff --git a/docs/examples/polyglot-javascript-java-r.md b/docs/examples/polyglot-javascript-java-r.md index 9dd251a389d9..32c82e4ae8d4 100644 --- a/docs/examples/polyglot-javascript-java-r.md +++ b/docs/examples/polyglot-javascript-java-r.md @@ -17,7 +17,7 @@ git clone https://github.com/graalvm/graalvm-demos cd graalvm-demos/polyglot-javascript-java-r ``` -2. [Install GraalVM](/docs/getting-started/#install-graalvm) on your platform. +2. [Install GraalVM](../getting-started/graalvm-community/get-started-graalvm-community.md#install-graalvm) on your platform. 3. To run the demo, you need to enable Node.js support in GraalVM: ```shell diff --git a/docs/getting-started/graalvm-community/container-images/graalvm-ce-container-images.md b/docs/getting-started/graalvm-community/container-images/graalvm-ce-container-images.md index a16a8e3b7014..ed2edb613a87 100644 --- a/docs/getting-started/graalvm-community/container-images/graalvm-ce-container-images.md +++ b/docs/getting-started/graalvm-community/container-images/graalvm-ce-container-images.md @@ -50,9 +50,8 @@ bash-4.4# ``` Please note that the image contains only the components immediately available in the GraalVM Community core download. -However, the [GraalVM Updater](/reference-manual/graalvm-updater/) utility is on the `PATH` and you can install the support for additional languages and runtimes like Node.js, Ruby, R, Python or WebAssembly at will. +However, the [GraalVM Updater, `gu`](../../../reference-manual/graalvm-updater.md), utility is included in the container image and may be used to install additional languages and runtimes like Node.js, Ruby, R, Python or WebAssembly. -However, the [GraalVM Updater, `gu`](/reference-manual/graalvm-updater/), utility is included in the container image and may be used to install additional languages and runtimes like Node.js, Ruby, R, Python or WebAssembly. For example, the following command installs the Ruby support (the output below is truncated for brevity): ```shell diff --git a/docs/getting-started/graalvm-community/get-started-graalvm-community.md b/docs/getting-started/graalvm-community/get-started-graalvm-community.md index 4945739eea13..85118aad1b3e 100644 --- a/docs/getting-started/graalvm-community/get-started-graalvm-community.md +++ b/docs/getting-started/graalvm-community/get-started-graalvm-community.md @@ -14,18 +14,18 @@ GraalVM's polyglot capabilities make it possible to mix multiple programming lan Here you will find information about installing GraalVM Community Edition, running basic applications with it, and adding support for accompanying features. Further, you will learn about the polyglot capabilities of GraalVM and see how to build platform-specific native executables of JVM-based applications. -If you are new to GraaVM, we recommend starting with [Introduction to GraalVM](/docs/introduction/), where you will find information about GraalVM's architecture, distributions available, supported platforms, core and additional features, and much more. +If you are new to GraaVM, we recommend starting with [Introduction to GraalVM](../../introduction.md), where you will find information about GraalVM's architecture, distributions available, supported platforms, core and additional features, and much more. -If you have GraalVM already installed and have experience using it, you can skip this getting started guide and proceed to the in-depth [Reference Manuals](/reference-manual/). +If you have GraalVM already installed and have experience using it, you can skip this getting started guide and proceed to the in-depth [Reference Manuals](../../reference-manual/reference-manuals.md). ## Install GraalVM Getting GraalVM installed and ready-to-go should take a few minutes. Choose the operating system and proceed to the installation steps: -* [Linux](/docs/getting-started/linux/) -* [Linux AArch64](/docs/getting-started/linux-aarch64/) -* [macOS](/docs/getting-started/macos/) -* [Windows](/docs/getting-started/windows/) +* [Linux](linux.md) +* [Linux AArch64](linux-aarch64.md) +* [macOS](macos.md) +* [Windows](windows.md) ## Start Running Applications @@ -73,10 +73,10 @@ java HelloWorld Hello World! ``` -You can find a collection of larger Java examples on the [Examples Applications](/examples/) page. +You can find a collection of larger Java examples on the [Examples Applications](../../examples/examples.md) page. For more information on the GraalVM -compiler, go to [Compiler](/reference-manual/compiler/). -For more extensive documentation on running Java, proceed to [JVM Languages](/reference-manual/java/). +compiler, go to [Compiler](../../reference-manual/compiler.md). +For more extensive documentation on running Java, proceed to [JVM Languages](../../reference-manual/java/README.md). ## Run JavaScript and Node.js @@ -92,7 +92,7 @@ Node.js support is not installed by default, but can be easily added with GraalV ```shell gu install nodejs node -v -v14.16.1 +v14.17.6 ``` More than 100,000 npm packages are regularly tested and are compatible with GraalVM, including modules like express, react, async, request, browserify, grunt, mocha, and underscore. @@ -123,8 +123,7 @@ Run _app.js_ on GraalVM Enterprise using the `node` command: node app.js ``` -For more detailed documentation and information on compatibility with Node.js, -proceed to [JavaScript and Node.js](/reference-manual/js/). +For more detailed documentation and information on compatibility with Node.js, proceed to [JavaScript and Node.js](../../reference-manual/js/README.md). ## Run LLVM Languages @@ -154,12 +153,12 @@ $LLVM_TOOLCHAIN/clang hello.c -o hello lli hello ``` -For in-depth documentation and more examples of running LLVM bitcode on GraalVM, go to [LLVM Languages](/reference-manual/llvm/). +For in-depth documentation and more examples of running LLVM bitcode on GraalVM, go to [LLVM Languages](../../reference-manual/llvm/README.md). ## Run Python With GraalVM you can run Python applications in the Python 3 runtime environment. -The support is not available by default, but you can quickly add it to GraalVM using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The support is not available by default, but you can quickly add it to GraalVM using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install python ``` @@ -173,12 +172,12 @@ graalpython >>> exit() ``` -More examples and additional information on Python support in GraalVM can be found in the [Python reference manual](/reference-manual/python/). +More examples and additional information on Python support in GraalVM can be found in the [Python reference manual](../../reference-manual/python/README.md). ## Run Ruby GraalVM provides a high-performance Ruby runtime environment including the `gem` command that allows you to interact with RubyGems, Ruby Bundler, and much more. -The Ruby runtime is not available by default in GraalVM, but can be easily added using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The Ruby runtime is not available by default in GraalVM, but can be easily added using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install ruby ``` @@ -189,7 +188,7 @@ ruby [options] program.rb ``` GraalVM Ruby runtime environment uses the -[same options as the standard implementation of Ruby](/reference-manual/ruby/Options/), +[same options as the standard implementation of Ruby](../../reference-manual/ruby/options.md), with some additions. For example: ```shell gem install chunky_png @@ -197,12 +196,12 @@ ruby -r chunky_png -e "puts ChunkyPNG::Color.to_hex(ChunkyPNG::Color('mintcream #f5fffa80 ``` -More examples and in-depth documentation can be found in the [Ruby reference manual](/reference-manual/ruby/). +More examples and in-depth documentation can be found in the [Ruby reference manual](../../reference-manual/ruby/README.md). ## Run R GraalVM provides a GNU-compatible environment to run R programs directly or in the REPL mode. -Although the R language support is not available by default, you can add it to GraalVM using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +Although the R language support is not available by default, you can add it to GraalVM using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install R ``` @@ -217,12 +216,12 @@ R version 4.0.3 (FastR) [1] 2 ``` -More examples and in-depth documentation can be found in the [R reference manual](/reference-manual/r/). +More examples and in-depth documentation can be found in the [R reference manual](../../reference-manual/r/README.md). ## Run WebAssembly With GraalVM you can run programs compiled to WebAssembly. -The support is not available by default, but you can add it to GraalVM using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The support is not available by default, but you can add it to GraalVM using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install wasm ``` @@ -256,7 +255,7 @@ Then you can run the compiled WebAssembly binary on GraalVM as follows: wasm --Builtins=wasi_snapshot_preview1 floyd.wasm ``` -More details can be found in the [WebAssembly reference manual](/reference-manual/wasm/). +More details can be found in the [WebAssembly reference manual](../../reference-manual/wasm/README.md). ## Combine Languages @@ -265,12 +264,12 @@ To enable interoperability, GraalVM provides the `--polyglot` flag. For example, running `js --jvm --polyglot example.js` executes `example.js` in a polyglot context. If the program calls any code in other supported languages, GraalVM executes that code in the same runtime as the `example.js` application. -For more information on running polyglot applications, see [Polyglot Programming](/reference-manual/polyglot-programming/). +For more information on running polyglot applications, see [Polyglot Programming](../../reference-manual/polyglot-programming.md). ## Native Images With GraalVM you can compile Java bytecode into a platform-specific, self-contained, native executable - a native image - to achieve faster startup and smaller footprint for your application. -The [Native Image](/reference-manual/native-image/) functionality is not available by default, but can be easily installed with the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The [Native Image](../../reference-manual/native-image/README.md) functionality is not available by default, but can be easily installed with the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install native-image ``` @@ -285,7 +284,7 @@ public class HelloWorld { } ``` -> Note: For compilation `native-image` depends on the local toolchain. Make sure your system meets the [prerequisites](/reference-manual/native-image/#prerequisites). +> Note: For compilation `native-image` depends on the local toolchain. Make sure your system meets the [prerequisites](../../reference-manual/native-image/README.md#prerequisites). Compile _HelloWorld.java_ to bytecode and then build a native image: ```shell @@ -300,7 +299,7 @@ Invoking it executes the natively compiled code of the `HelloWorld` class as fol Hello, World! ``` -More detailed documentation on this innovative technology is available in the [Native Image reference manual](/reference-manual/native-image/). +More detailed documentation on this innovative technology is available in the [Native Image reference manual](../../reference-manual/native-image/README.md). ## Polyglot Capabilities of Native Images @@ -336,7 +335,7 @@ javac PrettyPrintJSON.java native-image --language:js --initialize-at-build-time PrettyPrintJSON ``` The native image generatation will take several minutes as it does not just build the `PrettyPrintJSON` class, but also builds JavaScript. -Additionally, the image building requires large amounts of physical memory, especially if you build an image with the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) included, which is the case here. +Additionally, the image building requires large amounts of physical memory, especially if you build an image with the [Truffle language implementation framework](../../../truffle/docs/README.md) included, which is the case here. The resulting executable can now perform JSON pretty-printing: ```shell @@ -384,14 +383,14 @@ sys 0m0.016s ## What to Read Next ### New Users -Since this guide is intended mainly for users new to GraalVM, or users who are familiar with GraalVM but may have little experience using it, please consider investigating more complex [Example Applications](/examples/). -We also recommend checking our [GraalVM Team Blog](/blog/). +Since this guide is intended mainly for users new to GraalVM, or users who are familiar with GraalVM but may have little experience using it, please consider investigating more complex [Example Applications](../../examples/examples.md). +We also recommend checking our [GraalVM Team Blog](https://medium.com/graalvm). ### Advanced Users -If you are mostly interested in GraalVM support for a specific language, or want more in-depth details about GraalVM's diverse technologies, proceed to [Reference Manuals](/reference-manual/). +If you are mostly interested in GraalVM support for a specific language, or want more in-depth details about GraalVM's diverse technologies, proceed to [Reference Manuals](../../reference-manual/reference-manuals.md). -If you are looking for the tooling support GraalVM offers, proceed to [Debugging and Monitoring Tools](/tools/). +If you are looking for the tooling support GraalVM offers, proceed to [Debugging and Monitoring Tools](../../tools/tools.md). -If you are considering GraalVM as a platform for your future language or tool implementation, go to [GraalVM as a Platform](/graalvm-as-a-platform/language-implementation-framework/). +If you are considering GraalVM as a platform for your future language or tool implementation, go to [GraalVM as a Platform](../../../truffle/docs/README.md). -You can find information on GraalVM's security model in the [Security Guide](/security-guide/), and rich API documentation in [GraalVM SDK Javadoc](https://www.graalvm.org/sdk/javadoc/) and [Truffle Javadoc](https://www.graalvm.org/truffle/javadoc/). +You can find information on GraalVM's security model in the [Security Guide](../../security/security-guide.md), and rich API documentation in [GraalVM SDK Javadoc](https://www.graalvm.org/sdk/javadoc/) and [Truffle Javadoc](https://www.graalvm.org/truffle/javadoc/). diff --git a/docs/getting-started/graalvm-community/linux-aarch64.md b/docs/getting-started/graalvm-community/linux-aarch64.md index e4fb8d221c09..eb9aea7b63eb 100644 --- a/docs/getting-started/graalvm-community/linux-aarch64.md +++ b/docs/getting-started/graalvm-community/linux-aarch64.md @@ -15,7 +15,7 @@ Note: The base GraalVM Community distribution including all components is **expe You can install the GraalVM distribution for Linux ARM64 systems from an archive file (_.tar.gz_). This allows you to install GraalVM for the current user into any location, without affecting other JDK installations. -1. Navigate to the [GraalVM Releases repository on GitHub](https://github.com/graalvm/graalvm-ce-builds/releases). Depending on the workload, select Java 11 or 16 based distribution for the Linux AArch64 architecture, and download. +1. Navigate to the [GraalVM Releases repository on GitHub](https://github.com/graalvm/graalvm-ce-builds/releases). Depending on the workload, select Java 11 or 17 based distribution for the Linux AArch64 architecture, and download. 2. Change the directory to the location where you want to install GraalVM, then move the _.tar.gz_ archive to it. 3. Unzip the archive: ```shell @@ -38,6 +38,6 @@ For Oracle GraalVM Enterprise Edition users, find the installation instructions ## Supported Functionalities -The 64-bit GraalVM Community distribution for Linux platforms includes OpenJDK with the GraalVM compiler enabled, the [GraalVM Updater, `gu`](/reference-manual/graalvm-updater/), tool, the JavaScript runtime, and some developer tools (e.g., Chrome inspector based debugger, Visual VM). -Support for [Native Image](/reference-manual/native-image/), Node.js, LLVM and WebAssembly runtimes can be installed with `gu`. +The 64-bit GraalVM Community distribution for Linux platforms includes OpenJDK with the GraalVM compiler enabled, the [GraalVM Updater, `gu`](../../reference-manual/graalvm-updater.md), tool, the JavaScript runtime, and some developer tools (e.g., Chrome inspector based debugger, Visual VM). +Support for [Native Image](../../reference-manual/native-image/README.md), Node.js, LLVM and WebAssembly runtimes can be installed with `gu`. Runtimes for Python, FastR, and Ruby languages are not available in this distribution yet. diff --git a/docs/getting-started/graalvm-community/linux.md b/docs/getting-started/graalvm-community/linux.md index 8b152d3abfda..fa4cf5873ff6 100644 --- a/docs/getting-started/graalvm-community/linux.md +++ b/docs/getting-started/graalvm-community/linux.md @@ -36,20 +36,18 @@ The base distribution of GraalVM Community Edition for Linux (AMD64) platforms i The base installation can be extended with: Tools/Utilities: -* [Native Image](/reference-manual/native-image/) -- a technology to compile an application ahead-of-time into a native executable -* [LLVM toolchain](/reference-manual/llvm/Compiling/#llvm-toolchain-for-compiling-cc) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime -* [Java on Truffle](/reference-manual/java-on-truffle/) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Native Image](../../reference-manual/native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable +* [LLVM toolchain](../../reference-manual/llvm/Compiling.md#llvm-toolchain-for-compiling-cc) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime Runtimes: -* [Node.js](/reference-manual/js/) -- Node.js 14.16.1 compatible -* [Python](/reference-manual/python/) -- Python 3.8.5 compatible -* [Ruby](/reference-manual/ruby/) -- Ruby 2.7.2 compatible -* [R](/reference-manual/r/) -- GNU R 4.0.3 compatible -* [Wasm](/reference-manual/wasm/) -- WebAssembly (Wasm) +* [Java on Truffle](../../reference-manual/java-on-truffle/README.md) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Node.js](../../reference-manual/js/README.md) -- Node.js v14.17.6 compatible +* [Python](../../reference-manual/python/README.md) -- Python 3.8.5 compatible +* [Ruby](../../reference-manual/ruby/README.md) -- Ruby 2.7.2 compatible +* [R](/../../reference-manual/r/README.md) -- GNU R 4.0.3 compatible +* [Wasm](../../reference-manual/wasm/README.md) -- WebAssembly (Wasm) ​ These runtimes are not part of the GraalVM Community base distribution and must be installed separately. -To assist a user with installation, GraalVM includes -**GraalVM Updater**, a command line utility to install and manage additional -functionalities. Proceed to the [installation steps](/reference-manual/graalvm-updater/#component-installation){:target="_blank"} -to add any necessary language runtime or utility from above to GraalVM. +To assist a user with installation, GraalVM includes **GraalVM Updater**, a command line utility to install and manage additional functionalities. +Proceed to the [installation steps](../../reference-manual/graalvm-updater.md#component-installation) to add any necessary language runtime or utility from above to GraalVM. diff --git a/docs/getting-started/graalvm-community/macos.md b/docs/getting-started/graalvm-community/macos.md index 4828d64b6229..3ed2bc31fe32 100644 --- a/docs/getting-started/graalvm-community/macos.md +++ b/docs/getting-started/graalvm-community/macos.md @@ -66,20 +66,18 @@ The base distribution of GraalVM Community Edition for macOS includes OpenJDK wi The base installation can be extended with: Tools/Utilities: -* [Native Image](/reference-manual/native-image/) -- a technology to compile an application ahead-of-time into a native executable -* [LLVM toolchain](/reference-manual/llvm/Compiling/#llvm-toolchain-for-compiling-cc) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime -* [Java on Truffle](/reference-manual/java-on-truffle/) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Native Image](../../reference-manual/native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable +* [LLVM toolchain](../../reference-manual/llvm/Compiling.md#llvm-toolchain-for-compiling-cc) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime Runtimes: -* [Node.js](/reference-manual/js/) -- Node.js 14.16.1 compatible -* [Python](/reference-manual/python/) -- Python 3.8.5 compatible -* [Ruby](/reference-manual/ruby/) -- Ruby 2.7.2 compatible -* [R](/reference-manual/r/) -- GNU R 4.0.3 compatible -* [Wasm](/reference-manual/wasm/) -- WebAssembly (Wasm) +* [Java on Truffle](../../reference-manual/java-on-truffle/README.md) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Node.js](../../reference-manual/js/README.md) -- Node.js v14.17.6 compatible +* [Python](../../reference-manual/python/README.md) -- Python 3.8.5 compatible +* [Ruby](../../reference-manual/ruby/README.md) -- Ruby 2.7.2 compatible +* [R](/../../reference-manual/r/README.md) -- GNU R 4.0.3 compatible +* [Wasm](../../reference-manual/wasm/README.md) -- WebAssembly (Wasm) ​ These runtimes are not part of the GraalVM Community base distribution and must be installed separately. -To assist a user with installation, GraalVM includes -**GraalVM Updater**, a command line utility to install and manage additional -functionalities. Proceed to the [installation steps](/reference-manual/graalvm-updater/#component-installation){:target="_blank"} -to add any necessary language runtime or utility from above to GraalVM. +To assist a user with installation, GraalVM includes **GraalVM Updater**, a command line utility to install and manage additional functionalities. +Proceed to the [installation steps](../../reference-manual/graalvm-updater.md#component-installation) to add any necessary language runtime or utility from above to GraalVM. diff --git a/docs/getting-started/graalvm-community/windows.md b/docs/getting-started/graalvm-community/windows.md index 75bd7134e958..b48ac12cfac7 100644 --- a/docs/getting-started/graalvm-community/windows.md +++ b/docs/getting-started/graalvm-community/windows.md @@ -39,16 +39,17 @@ To run GraalVM Community Edition based on OpenJDK 8u292 on a Windows platform, t ## Supported Functionalities -The GraalVM Community distribution for Windows platforms includes OpenJDK with the GraalVM compiler enabled, the [GraalVM Updater](/reference-manual/graalvm-updater/) tool to install additional functionalities, the JavaScript runtime, and the developer tools (e.g., Chrome inspector based debugger, Profiler, etc.). -Currently, the GraalVM environment on Windows can be extended with [Native Image](/reference-manual/native-image/), [Java on Trufle](/reference-manual/java-on-truffle/), WebAssembly, and Node.js support. +The GraalVM Community distribution for Windows platforms includes OpenJDK with the GraalVM compiler enabled, the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool to install additional functionalities, the JavaScript runtime, and the developer tools (e.g., Chrome inspector based debugger, Profiler, etc.). +Currently, the GraalVM environment on Windows can be extended with [Native Image](../../reference-manual/native-image/README.md), [Java on Trufle](../../reference-manual/java-on-truffle/README.md), WebAssembly, and Node.js support. ## Prerequisites for Using Native Image on Windows -To make use of Native Image on Windows, observe the following recommendations. -The required Microsoft Visual C++ (MSVC) version depends on the JDK version that GraalVM is based on. -For GraalVM based on JDK 8, you will need MSVC 2010 SP1 version. The recommended installation method is using Microsoft Windows SDK 7.1: -1. Download the SDK file `GRMSDKX_EN_DVD.iso` for from [Microsoft](https://www.microsoft.com/en-gb/download). -2. Mount the image by opening `F:\Setup\SDKSetup.exe` directly. +On Windows, Native Image requires Visual Studio Code and Microsoft Visual C++(MSVC). +You can use Visual Studio 2017 version 15.9 or later. +There are two installation options: +- Install the Visual Studio Code Build Tools with the Windows 10 SDK +- Install Visual Studio Code with the Windows 10 SDK -For GraalVM distribution based on JDK 11, you will need MSVC 2017 15.5.5 or later version. +The last prerequisite is the proper [Developer Command Prompt](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts) for your version of [Visual Studio](https://visualstudio.microsoft.com/vs/). +On Windows the `native-image` tool only works when it is executed from the **x64 Native Tools Command Prompt**. -The last prerequisite, common for both distributions, is the proper [Developer Command Prompt](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts) for your version of [Visual Studio](https://visualstudio.microsoft.com/vs/). On Windows the `native-image` tool only works when it is executed from the **x64 Native Tools Command Prompt**. +Step by step instructions on installing Visual Studio Build Tools and Windows 10 SDK, and starting using Native Image can be found [here](https://medium.com/graalvm/using-graalvm-and-native-image-on-windows-10-9954dc071311). diff --git a/docs/getting-started/graalvm-enterprise/get-started-graalvm-enterprise.md b/docs/getting-started/graalvm-enterprise/get-started-graalvm-enterprise.md index 24c251a1b064..234b8fffa004 100644 --- a/docs/getting-started/graalvm-enterprise/get-started-graalvm-enterprise.md +++ b/docs/getting-started/graalvm-enterprise/get-started-graalvm-enterprise.md @@ -8,10 +8,10 @@ permalink: /getting-started/ Here you will find information about downloading and installing GraalVM Enterprise, running basic applications with it, and adding support for its accompanying features. Further, you will learn about the polyglot capabilities of GraalVM Enterprise and see how to build platform-specific native executables of JVM-based applications. -If you are new to GraalVM Enterprise or have little experience using it, we recommend starting with the [GraalVM Enterprise Overview](https://docs.oracle.com/en/graalvm/enterprise/21/docs/overview/architecture/) page. +If you are new to GraalVM Enterprise or have little experience using it, we recommend starting with the [GraalVM Enterprise Overview](../../enterprise-overview/architecture-overview.md) page. There you will find information about GraalVM Enterprise's architecture, the distributions available, supported platforms, licensing and support, core and additional features, and much more. -If you have GraalVM Enterprise already installed and have experience using it, you can skip this getting started guide and proceed to the in-depth [Reference Manuals](/reference-manual/). +If you have GraalVM Enterprise already installed and have experience using it, you can skip this getting started guide and proceed to the in-depth [Reference Manuals](../../reference-manual/reference-manuals.md). ## Download GraalVM Enterprise @@ -25,11 +25,11 @@ You can get Oracle GraalVM Enterprise Edition by: Getting GraalVM Enterprise installed and ready-to-go should take a few minutes. Choose your operating system and proceed to the installation steps for your specific platform: -* [Linux](/getting-started/installation-linux/) -* [Linux ARM64](/getting-started/installation-linux-aarch64/) -* [Oracle Linux](/getting-started/oci/compute-instances/) -* [macOS](/getting-started/installation-macos/) -* [Windows](/getting-started/installation-windows/) +* [Linux](installation-linux.md) +* [Linux ARM64](installation-linux-aarch64.md) +* [Oracle Linux](oci/compute-instances.md) +* [macOS](installation-macos.md) +* [Windows](installation-windows.md) ## Start Running Applications @@ -78,9 +78,9 @@ java HelloWorld Hello World! ``` -You can find a collection of larger Java examples on the [Examples Applications](/examples/) page. -For more information on the GraalVM compiler, go to [Compiler](/reference-manual/compiler/). -For more extensive documentation on running Java, proceed to [JVM Languages](/reference-manual/java/). +You can find a collection of larger Java examples on the [Examples Applications](../../examples/examples.md) page. +For more information on the GraalVM compiler, go to [Compiler](../../reference-manual/compiler.md). +For more extensive documentation on running Java, proceed to [JVM Languages](../../reference-manual/java/README.md). ### JavaScript and Node.js GraalVM Enterprise can execute plain JavaScript code, both in REPL mode and by executing script files directly: @@ -95,7 +95,7 @@ Node.js support is not installed by default, but can be easily added with GraalV ```shell gu install nodejs node -v -v15.12.0 +v14.17.6 ``` More than 100,000 npm packages are regularly tested and are compatible with GraalVM Enterprise, including modules like express, react, async, request, browserify, grunt, mocha, and underscore. @@ -127,7 +127,7 @@ Run _app.js_ on GraalVM Enterprise using the `node` command: node app.js ``` -For more detailed documentation and information on compatibility with Node.js, proceed to [JavaScript and Node.js](/reference-manual/js/). +For more detailed documentation and information on compatibility with Node.js, proceed to [JavaScript and Node.js](../../reference-manual/js/README.md). ### LLVM Languages @@ -161,12 +161,12 @@ $LLVM_TOOLCHAIN/clang hello.c -o hello lli hello ``` -For in-depth documentation and more examples of running LLVM bitcode on GraalVM Enterprise, go to [LLVM Languages](/reference-manual/llvm/). +For in-depth documentation and more examples of running LLVM bitcode on GraalVM Enterprise, go to [LLVM Languages](../../reference-manual/llvm/README.md). ### Python With GraalVM Enterprise you can run Python applications in the Python 3 runtime environment. -The support is not available by default, but you can quickly add it to GraalVM using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The support is not available by default, but you can quickly add it to GraalVM using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install python ``` @@ -180,12 +180,12 @@ graalpython >>> exit() ``` -More examples and additional information on Python support in GraalVM can be found in the [Python reference manual](/reference-manual/python/). +More examples and additional information on Python support in GraalVM can be found in the [Python reference manual](../../reference-manual/python/README.md). ### Ruby GraalVM Enterprise provides a high-performance Ruby runtime environment including the `gem` command that allows you to interact with RubyGems, Ruby Bundler, and much more. -The Ruby runtime is not available by default in GraalVM, but can be easily added using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The Ruby runtime is not available by default in GraalVM, but can be easily added using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install ruby ``` @@ -196,7 +196,7 @@ ruby [options] program.rb ``` GraalVM Ruby runtime environment uses the -[same options as the standard implementation of Ruby](/reference-manual/ruby/Options/), +[same options as the standard implementation of Ruby](../../reference-manual/ruby/Options.md), with some additions. For example: ```shell gem install chunky_png @@ -204,12 +204,12 @@ ruby -r chunky_png -e "puts ChunkyPNG::Color.to_hex(ChunkyPNG::Color('mintcream #f5fffa80 ``` -More examples and in-depth documentation can be found in the [Ruby reference manual](/reference-manual/ruby/). +More examples and in-depth documentation can be found in the [Ruby reference manual](../../reference-manual/ruby/README.md). ### R GraalVM Enterprise provides a GNU-compatible environment to run R programs directly or in the REPL mode. -Although the R language support is not available by default, you can add it to GraalVM Enterprise using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +Although the R language support is not available by default, you can add it to GraalVM Enterprise using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install R ``` @@ -224,12 +224,12 @@ R version 4.0.3 (FastR) [1] 2 ``` -More examples and in-depth documentation can be found in the [R reference manual](/reference-manual/r/). +More examples and in-depth documentation can be found in the [R reference manual](../../reference-manual/r/README.md). ### WebAssembly With GraalVM Enterprise you can run programs compiled to WebAssembly. -The support is not available by default, but you can add it to GraalVM using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The support is not available by default, but you can add it to GraalVM using the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install wasm ``` @@ -264,12 +264,12 @@ Then you can run the compiled WebAssembly binary on GraalVM as follows: wasm --Builtins=wasi_snapshot_preview1 floyd.wasm ``` -More details can be found in the [WebAssembly reference manual](/reference-manual/wasm/). +More details can be found in the [WebAssembly reference manual](../../reference-manual/wasm/README.md). ## Native Images With GraalVM Enterprise you can compile Java bytecode into a platform-specific, self-contained, native executable - a native image - to achieve faster startup and a smaller footprint for your application. -The [Native Image](/reference-manual/native-image/) functionality is not available by default, but can be easily installed with the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The [Native Image](../../reference-manual/native-image/README.md) functionality is not available by default, but can be easily installed with the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool: ```shell gu install native-image ``` @@ -284,7 +284,7 @@ public class HelloWorld { } ``` -> Note: For compilation `native-image` depends on the local toolchain. Make sure your system meets the [prerequisites](/reference-manual/native-image/#prerequisites). +> Note: For compilation `native-image` depends on the local toolchain. Make sure your system meets the [prerequisites](../../reference-manual/native-image/README.md#prerequisites). Compile _HelloWorld.java_ to bytecode and then build a native image: ```shell @@ -299,7 +299,7 @@ Invoking it executes the natively compiled code of the `HelloWorld` class as fol Hello, World! ``` -More detailed documentation on this innovative technology is available in the [Native Image reference manual](/reference-manual/native-image/). +More detailed documentation on this innovative technology is available in the [Native Image reference manual](../../reference-manual/native-image/README.md). ## Polyglot Capabilities of Native Images @@ -335,7 +335,7 @@ native-image --language:js --initialize-at-build-time PrettyPrintJSON The native image generatation will take several minutes as it does not just build the `PrettyPrintJSON` class, but also builds JavaScript. Additionally, the image building requires large amounts of physical memory, especially if you build an image with -the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) included, which is the case here. +the [Truffle language implementation framework](../../../truffle/docs/README.md) included, which is the case here. The resulting executable can now perform JSON pretty-printing: @@ -388,24 +388,24 @@ To enable interoperability, GraalVM Enterprise provides the `--polyglot` flag. For example, running `js --jvm --polyglot example.js` executes `example.js` in a polyglot context. If the program calls any code in other supported languages, GraalVM Enterprise executes that code in the same runtime as the `example.js` application. -For more information on running polyglot applications, see [Polyglot Programming](/reference-manual/polyglot-programming/). +For more information on running polyglot applications, see [Polyglot Programming](../../reference-manual/polyglot-programming.md). ## What to Read Next ### New Users Since this guide is intended mainly for users new to GraalVM Enterprise, or users -who are familiar with GraalVM Enterprise but may have little experience using it, consider investigating more complex [Example Applications](/examples/). +who are familiar with GraalVM Enterprise but may have little experience using it, consider investigating more complex [Example Applications](../../examples/examples.md). ### Oracle Cloud Users Oracle Cloud users considering GraalVM Enterprise for their cloud workloads are -invited to read [GraalVM Enterprise on OCI](/getting-started/oci/compute-instances/). +invited to read [GraalVM Enterprise on OCI](oci/compute-instances.md). This page focuses on using GraalVM Enterprise with the Oracle Cloud Infrastructure Virtual Machine compute instance. ### Advanced Users -If you are mostly interested in GraalVM Enterprise support for a specific language, or want more in-depth details about GraalVM Enterprise's diverse features, proceed to [Reference Manuals](/reference-manual/). +If you are mostly interested in GraalVM Enterprise support for a specific language, or want more in-depth details about GraalVM Enterprise's diverse features, proceed to [Reference Manuals](../../reference-manual/reference-manuals.md). -If you are looking for the tooling support GraalVM Enterprise offers, proceed to [Debugging and Monitoring Tools](/tools/). +If you are looking for the tooling support GraalVM Enterprise offers, proceed to [Debugging and Monitoring Tools](../../tools/tools.md). -If you are considering GraalVM Enterprise as a platform for your future language or tool implementation, go to [GraalVM Enterprise as a Platform](/graalvm-as-a-platform/). +If you are considering GraalVM Enterprise as a platform for your future language or tool implementation, go to [GraalVM Enterprise as a Platform](../../../truffle/docs/README.md). You can find information on GraalVM Enterprise's security model in the [Security Guide](/security-guide/), and rich API documentation in [GraalVM SDK Javadoc](https://docs.oracle.com/en/graalvm/enterprise/21/sdk/index.html). diff --git a/docs/getting-started/graalvm-enterprise/installation-linux-aarch64.md b/docs/getting-started/graalvm-enterprise/installation-linux-aarch64.md index 320ef5e8a66d..4f486a86bc16 100644 --- a/docs/getting-started/graalvm-enterprise/installation-linux-aarch64.md +++ b/docs/getting-started/graalvm-enterprise/installation-linux-aarch64.md @@ -14,7 +14,7 @@ You can install the GraalVM distribution for Linux ARM64 systems from an archive This allows you to install GraalVM for the current user into any location, without affecting other JDK installations. 1. Navigate to [Oracle GraalVM Downloads](https://www.oracle.com/downloads/graalvm-downloads.html?selected_tab=21). -2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **11** or **16** for the Java version, **Linux** for the operating system, and **aarch64** for the architecture. +2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **11** or **17** for the Java version, **Linux** for the operating system, and **aarch64** for the architecture. 3. Click on the **GraalVM Enterprise Core** download link. Before you download a file, you must accept the [Oracle License Agreement](https://www.oracle.com/downloads/licenses/graalvm-otn-license.html) in the popup window. 4. When the download button becomes active, press it to start downloading **graalvm-ee-java11-linux-aarch64-.tar.gz**. 5. Change the directory to the location where you want to install GraalVM Enterprise, then move the _.tar.gz_ archive to it. @@ -37,6 +37,6 @@ Optionally, you can specify GraalVM Enterprise as the default JRE or JDK install ## Supported Functionalities -The 64-bit GraalVM Enterprise distribution for Linux platforms includes Oracle JDK with the GraalVM compiler enabled, the [GraalVM Updater, `gu`](/reference-manual/graalvm-updater/) tool, the JavaScript runtime, and some developer tools (e.g., Chrome inspector based debugger, Visual VM). -Support for [Native Image](/reference-manual/native-image/), Node.js, LLVM and WebAssembly runtimes can be installed with `gu`. +The 64-bit GraalVM Enterprise distribution for Linux platforms includes Oracle JDK with the GraalVM compiler enabled, the [GraalVM Updater, `gu`](../../reference-manual/graalvm-updater.md) tool, the JavaScript runtime, and some developer tools (e.g., Chrome inspector based debugger, Visual VM). +Support for [Native Image](../../reference-manual/native-image/README.md), Node.js, LLVM and WebAssembly runtimes can be installed with `gu`. Runtimes for Python, FastR, and Ruby languages are not available in this distribution yet. diff --git a/docs/getting-started/graalvm-enterprise/installation-linux.md b/docs/getting-started/graalvm-enterprise/installation-linux.md index 84c9c4e1a3a2..e40d026bc347 100644 --- a/docs/getting-started/graalvm-enterprise/installation-linux.md +++ b/docs/getting-started/graalvm-enterprise/installation-linux.md @@ -8,7 +8,7 @@ permalink: /getting-started/installation-linux/ Follow these steps to install Oracle GraalVM Enterprise Edition on the Linux operating system: 1. Navigate to [Oracle GraalVM Downloads](https://www.oracle.com/downloads/graalvm-downloads.html?selected_tab=21). -2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **8**, **11**, or **16** for the Java version, **Linux** for the operating system, and **amd64** for the architecture. +2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **8**, **11**, or **17** for the Java version, **Linux** for the operating system, and **amd64** for the architecture. 3. Click on the **GraalVM Enterprise Core** download link. Before you download a file, you must accept the [Oracle License Agreement](https://www.oracle.com/downloads/licenses/graalvm-otn-license.html) in the popup window. 4. When the download button becomes active, press it to start downloading **graalvm-ee-java-linux-amd64-.tar.gz**. 5. Change the directory to the location where you want to install GraalVM Enterprise, then move the _.tar.gz_ archive to it. @@ -35,20 +35,18 @@ The base distribution of GraalVM Enterprise for Linux (AMD64) platforms includes The base installation can be extended with: Tools/Utilities: -* [Native Image](/reference-manual/enterprise-native-image/) -- a technology to compile an application ahead-of-time into a native executable -* [LLVM toolchain](/reference-manual/llvm/) -- a set of tools and APIs for compiling native programs to bitcode that can be executed on GraalVM Enterprise -* [Java on Truffle](/reference-manual/java-on-truffle/) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM Enterprise +* [Native Image](../../reference-manual/native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable +* [LLVM toolchain](../../reference-manual/llvm/Compiling.md#llvm-toolchain-for-compiling-cc) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime Runtimes: -* [Node.js](/reference-manual/js/) -- Node.js 14.16.1 compatible -* [Python](/reference-manual/python/) -- Python 3.8.5 compatible -* [Ruby](/reference-manual/ruby/) -- Ruby 2.7.3 compatible -* [R](/reference-manual/r/) -- GNU R 4.0.3 compatible -* [Wasm](/reference-manual/wasm/) -- WebAssembly (Wasm) +* [Java on Truffle](../../reference-manual/java-on-truffle/README.md) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Node.js](../../reference-manual/js/README.md) -- Node.js v14.17.6 compatible +* [Python](../../reference-manual/python/README.md) -- Python 3.8.5 compatible +* [Ruby](../../reference-manual/ruby/README.md) -- Ruby 2.7.2 compatible +* [R](/../../reference-manual/r/README.md) -- GNU R 4.0.3 compatible +* [Wasm](../../reference-manual/wasm/README.md) -- WebAssembly (Wasm) ​ These runtimes are not part of the GraalVM Enterprise base distribution and must be installed separately. -To assist a user with installation, GraalVM Enterprise includes -**GraalVM Updater**, a command line utility to install and manage additional -functionalities. Proceed to the [installation steps](/reference-manual/graalvm-updater/#component-installation){:target="_blank"} -to add any necessary language runtime or utility from above to the GraalVM Enterprise core. +To assist a user with installation, GraalVM includes **GraalVM Updater**, a command line utility to install and manage additional functionalities. +Proceed to the [installation steps](../../reference-manual/graalvm-updater.md#component-installation) to add any necessary language runtime or utility from above to GraalVM. diff --git a/docs/getting-started/graalvm-enterprise/installation-macos.md b/docs/getting-started/graalvm-enterprise/installation-macos.md index 086dc63feb9d..dbd2f65e64fc 100644 --- a/docs/getting-started/graalvm-enterprise/installation-macos.md +++ b/docs/getting-started/graalvm-enterprise/installation-macos.md @@ -17,7 +17,7 @@ the JDK installation path is: Follow these steps to install Oracle GraalVM Enterprise Edition on the macOS operating system: 1. Navigate to[ Oracle GraalVM Downloads](https://www.oracle.com/downloads/graalvm-downloads.html). -2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **8**, **11**, or **16** for the Java version, and **macOS** for the operating system. +2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **8**, **11**, or **17** for the Java version, and **macOS** for the operating system. 3. Click on the **GraalVM Enterprise Core** download link. Before you download a file, you must accept the [Oracle License Agreement](https://www.oracle.com/downloads/licenses/graalvm-otn-license.html) in the popup window. 4. When the download button becomes active, press it to start downloading **graalvm-ee-java-darvin-amd64-.tar.gz**. 5. Unzip the archive: @@ -66,20 +66,18 @@ The base distribution of GraalVM Enterprise for macOS platforms includes Oracle The base installation can be extended with: Tools/Utilities: -* [Native Image](/reference-manual/native-image/) -- a technology to compile an application ahead-of-time into a native executable -* [LLVM toolchain](/reference-manual/llvm/) -- a set of tools and APIs for compiling native programs to bitcode that can be executed on GraalVM Enterprise -* [Java on Truffle](/reference-manual/java-on-truffle/) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM Enterprise +* [Native Image](../../reference-manual/native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable +* [LLVM toolchain](../../reference-manual/llvm/Compiling.md#llvm-toolchain-for-compiling-cc) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime Runtimes: -* [Node.js](/reference-manual/js/) -- Node.js 14.16.1 compatible -* [Python](/reference-manual/python/) -- Python 3.8.5 compatible -* [Ruby](/reference-manual/ruby/) -- Ruby 2.7.3 compatible -* [R](/reference-manual/r/) -- GNU R 4.0.3 compatible -* [Wasm](/reference-manual/wasm/) -- WebAssembly (Wasm) +* [Java on Truffle](../../reference-manual/java-on-truffle/README.md) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Node.js](../../reference-manual/js/README.md) -- Node.js v14.17.6 compatible +* [Python](../../reference-manual/python/README.md) -- Python 3.8.5 compatible +* [Ruby](../../reference-manual/ruby/README.md) -- Ruby 2.7.2 compatible +* [R](/../../reference-manual/r/README.md) -- GNU R 4.0.3 compatible +* [Wasm](../../reference-manual/wasm/README.md) -- WebAssembly (Wasm) ​ These runtimes are not part of the GraalVM Enterprise base distribution and must be installed separately. -To assist users with installation, GraalVM Enterprise includes -**GraalVM Updater**, a command line utility to install and manage additional -functionalities. Proceed to the [installation steps](/reference-manual/graalvm-updater/#component-installation){:target="_blank"} -to add any necessary language runtime or utility from above to the GraalVM Enterprise core. +To assist a user with installation, GraalVM includes **GraalVM Updater**, a command line utility to install and manage additional functionalities. +Proceed to the [installation steps](../../reference-manual/graalvm-updater.md#component-installation) to add any necessary language runtime or utility from above to GraalVM. diff --git a/docs/getting-started/graalvm-enterprise/installation-windows.md b/docs/getting-started/graalvm-enterprise/installation-windows.md index 0807a4a50643..78d933cbe076 100644 --- a/docs/getting-started/graalvm-enterprise/installation-windows.md +++ b/docs/getting-started/graalvm-enterprise/installation-windows.md @@ -9,7 +9,7 @@ You can install Oracle GraalVM Enterprise Edition on the Windows operating syste Follow these steps: 1. Navigate to [Oracle GraalVM Downloads](https://www.oracle.com/downloads/graalvm-downloads.html). -2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **8**, **11**, or **16** for the Java version, and **Windows** for the operating system. +2. Select the preferable GraalVM Enterprise version in the Release Version dropdown, **8**, **11**, or **17** for the Java version, and **Windows** for the operating system. 3. Click on the **GraalVM Enterprise Core** download link. Before you download a file, you must accept the [Oracle License Agreement](https://www.oracle.com/downloads/licenses/graalvm-otn-license.html) in the popup window. 4. When the download button becomes active, press it to start downloading graalvm-ee-java-windows-amd64-.zip. 5. Change the directory to the location where you want to install GraalVM Enterprise, then move the _.zip_ archive to it. @@ -36,18 +36,17 @@ Optionally, you can specify GraalVM Enterprise as the JRE or JDK installation in ## Supported Functionalities -The GraalVM Enterprise distribution for Windows platforms includes Oracle JDK with the GraalVM compiler enabled, the [GraalVM Updater](/reference-manual/graalvm-updater/) tool, the JavaScript runtime, and the developer tools (e.g., Chrome inspector based debugger, Profiler, etc.). -Currently, the GraalVM Enterprise environment on Windows can be extended with [Native Image](/reference-manual/native-image/), [Java on Trufle](/reference-manual/java-on-truffle/), WebAssembly, and Node.js support. +The GraalVM Enterprise distribution for Windows platforms includes Oracle JDK with the GraalVM compiler enabled, the [GraalVM Updater](../../reference-manual/graalvm-updater.md) tool, the JavaScript runtime, and the developer tools (e.g., Chrome inspector based debugger, Profiler, etc.). +Currently, the GraalVM Enterprise environment on Windows can be extended with [Native Image](../../reference-manual/native-image/README.md), [Java on Trufle](../../reference-manual/java-on-truffle/README.md), WebAssembly, and Node.js support. ## Prerequisites for Using Native Image on Windows -To make use of Native Image on Windows, observe the following recommendations. The -required Microsoft Visual C++ (MSVC) version depends on the JDK version that -GraalVM is based on. For GraalVM Enterprise distribution based on JDK 8, you will need MSVC -2010 SP1 version. The recommended installation method is using Microsoft Windows -SDK 7.1: -1. Download the SDK file `GRMSDKX_EN_DVD.iso` for from [Microsoft](https://www.microsoft.com/en-gb/download). -2. Mount the image by opening `F:\Setup\SDKSetup.exe` directly. +On Windows, Native Image requires Visual Studio Code and Microsoft Visual C++(MSVC). +You can use Visual Studio 2017 version 15.9 or later. +There are two installation options: +- Install the Visual Studio Code Build Tools with the Windows 10 SDK +- Install Visual Studio Code with the Windows 10 SDK -For GraalVM Enterprise distribution based on JDK 11, you will need MSVC 2017 15.5.5 or later version. +The last prerequisite is the proper [Developer Command Prompt](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts) for your version of [Visual Studio](https://visualstudio.microsoft.com/vs/). +On Windows the `native-image` tool only works when it is executed from the **x64 Native Tools Command Prompt**. -The last prerequisite, common for both distributions, is the proper [Developer Command Prompt](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts) for your version of [Visual Studio](https://visualstudio.microsoft.com/vs/). On Windows the `native-image` tool only works when it is executed from the **x64 Native Tools Command Prompt**. +Step by step instructions on installing Visual Studio Build Tools and Windows 10 SDK, and starting using Native Image can be found [here](https://medium.com/graalvm/using-graalvm-and-native-image-on-windows-10-9954dc071311). diff --git a/docs/getting-started/graalvm-enterprise/oci/compute-instances.md b/docs/getting-started/graalvm-enterprise/oci/compute-instances.md index 341a50daaa77..221d231b9537 100644 --- a/docs/getting-started/graalvm-enterprise/oci/compute-instances.md +++ b/docs/getting-started/graalvm-enterprise/oci/compute-instances.md @@ -79,7 +79,7 @@ Now you have a ready-to-go VM instance with GraalVM Enterprise installed and rea ``` 2. Look up the necessary RPM package name and add it to GraalVM Enterprise with the `yum install command` command. -For example, to install [Native Image](/reference-manual/native-image/), which is a technology to ahead-of-time compile Java code to a standalone native executable, run this command: +For example, to install [Native Image](../../../reference-manual/native-image/README.md), which is a technology to ahead-of-time compile Java code to a standalone native executable, run this command: ```shell sudo yum install graalvm21-ee-11-native-image From 0a0bb6127f10a9c46d76fd2f95235905e3ec2d5f Mon Sep 17 00:00:00 2001 From: Olga Gupalo Date: Mon, 13 Dec 2021 17:10:33 +0200 Subject: [PATCH 2/4] Use rel paths on URLs instead of permalinks --- .../graalvm-as-a-platform.md | 8 +- .../implement-instrument.md | 105 +++++++-------- .../implement-language.md | 90 +++++-------- docs/guides/guides.md | 8 +- .../embedding/embed-languages.md | 13 +- .../embedding/sandbox-options.md | 2 +- docs/reference-manual/java/Operations.md | 126 +++++++----------- docs/reference-manual/java/README.md | 8 +- 8 files changed, 146 insertions(+), 214 deletions(-) diff --git a/docs/graalvm-as-a-platform/graalvm-as-a-platform.md b/docs/graalvm-as-a-platform/graalvm-as-a-platform.md index 10e957fb8e01..7c5af0090264 100644 --- a/docs/graalvm-as-a-platform/graalvm-as-a-platform.md +++ b/docs/graalvm-as-a-platform/graalvm-as-a-platform.md @@ -8,21 +8,21 @@ toc_group: graalvm-as-a-platform # GraalVM as a Platform -GraalVM is an open ecosystem and allows users to implement a custom language or tool on top of it with the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) which offers APIs for writing interpreters for programming languages in the form of Java programs. +GraalVM is an open ecosystem and allows users to implement a custom language or tool on top of it with the [Truffle language implementation framework](../../truffle/docs/README.md) which offers APIs for writing interpreters for programming languages in the form of Java programs. GraalVM loads and runs the Truffle framework, which itself is a Java program -- a collection of JAR files -- together with interpreters. These get optimized at runtime into efficient machine code for executing loaded programs. -Learn more about this framework from its [reference documentation](/graalvm-as-a-platform/language-implementation-framework/). +Learn more about this framework from its [reference documentation](../../truffle/docs/README.md). ## Implement Your Language With the [Language API](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/package-summary.html) offered by the Truffle framework, you can implement a language interpreter on top of GraalVM. -To get started, proceed to [Implement Your Language](/graalvm-as-a-platform/implement-language/). +To get started, proceed to [Implement Your Language](implement-language.md). ## Implement Your Tool With the [Instrument API](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/package-summary.html) offered by the Truffle framework, you can create language-agnostic tools like debuggers, profilers, or other instruments on top of GraalVM. -To get started, proceed to [Implement Your Tool](/graalvm-as-a-platform/implement-instrument/). +To get started, proceed to [Implement Your Tool](implement-instrument.md). diff --git a/docs/graalvm-as-a-platform/implement-instrument.md b/docs/graalvm-as-a-platform/implement-instrument.md index 1a2eb62b6290..a4a3f54ea8e6 100644 --- a/docs/graalvm-as-a-platform/implement-instrument.md +++ b/docs/graalvm-as-a-platform/implement-instrument.md @@ -14,22 +14,18 @@ Instruments can track very fine-grained, VM-level runtime events to profile, ins ## Simple Tool -To provide an easier starting point for tool developers we have created a -[Simple Tool](https://github.com/graalvm/simpletool) example project. This is a -javadoc-rich Maven project which implements a simple code coverage tool. +To provide an easier starting point for tool developers we have created a [Simple Tool](https://github.com/graalvm/simpletool) example project. +This is a javadoc-rich Maven project which implements a simple code coverage tool. -We recommend cloning the repository and exploring the source code as a starting -point for tool development. The following sections will provide a guided tour of -the steps needed to build and run a GraalVM tool, using Simple Tool source code -as the running example. These sections do not cover all of the features of the -[Instrument API](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/package-summary.html) so we encourage you to check the javadoc for more details. +We recommend cloning the repository and exploring the source code as a starting point for tool development. +The following sections will provide a guided tour of the steps needed to build and run a GraalVM tool, using Simple Tool source code as the running example. +These sections do not cover all of the features of the [Instrument API](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/package-summary.html) so we encourage you to check the javadoc for more details. ### Requirements -As mentioned before, Simple Tool is a code coverage tool. Ultimately, it -should provide the developer with information on what percentage of source code -lines was executed, as well as exactly which lines were executed. With that in -mind, we can define some high-level requirements from our tool: +As mentioned before, Simple Tool is a code coverage tool. +Ultimately, it should provide the developer with information on what percentage of source code lines was executed, as well as exactly which lines were executed. +With that in mind, we can define some high-level requirements from our tool: 1. The tool keeps track of loaded source code. 2. The tool keeps track of executed source code. @@ -40,21 +36,17 @@ mind, we can define some high-level requirements from our tool: The main starting point for tools is subclassing the [TruffleInstrument](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/TruffleInstrument.html) class. Unsurprisingly, the simple tool code base does exactly this, creating the [SimpleCoverageInstrument](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L84) class. -The -[Registration](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/TruffleInstrument.Registration.html) -annotation on the class ensures that the newly created instrument is registered -with the Instrument API, i.e., that it will be automatically -discovered by the framework. It also provides some metadata about the -instrument: ID, name, version, which services the instrument provides, and -whether the instrument is internal or not. In order for this annotation to be -effective the DSL processor needs to process this class. This is, in the case of Simple Tool, done automatically by having the DSL processor as a dependency in the [Maven configuration](https://github.com/graalvm/simpletool/blob/master/pom.xml#L83). +The [Registration](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/TruffleInstrument.Registration.html) annotation on the class ensures that the newly created instrument is registered with the Instrument API, i.e., that it will be automatically discovered by the framework. +It also provides some metadata about the instrument: ID, name, version, which services the instrument provides, and whether the instrument is internal or not. +In order for this annotation to be effective the DSL processor needs to process this class. +This is, in the case of Simple Tool, done automatically by having the DSL processor as a dependency in the [Maven configuration](https://github.com/graalvm/simpletool/blob/master/pom.xml#L83). Now we will look back at the implementation of the `SimpleCoverageInstrument` class, namely which methods from `TruffleInstrument` it overrides. These are [onCreate](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L130), [onDispose](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L182), and [getOptionDescriptors](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L245). The `onCreate` and `onDispose` methods are self-explanatory: they are called by the framework when the instrument is created and disposed. We will discuss their implementations later, but first let us discuss the remaining one: `getOptionDescriptors`. -The [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) comes with its own system for specifying command-line options. +The [Truffle language implementation framework](../../truffle/docs/README.md) comes with its own system for specifying command-line options. These options allow tool users to control the tool either from the command line or when creating [polyglot contexts](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.html). It is annotation-based, and examples for such options are the [ENABLED](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L91) and [PRINT_COVERAGE](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L97) fields of `SimpleCoverageInstrument`. Both of these are static final fields of the type [OptionKey](https://www.graalvm.org/truffle/javadoc/org/graalvm/options/OptionKey.html) annotated with [Option](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/Option.html) which, similar to the `Registration` annotation, provides some metadata for the option. @@ -68,6 +60,7 @@ Similarly, in the `onDispose` method we check the options for the state of the ` What does it mean "to enable a tool?" In general, it means that we tell the framework about the events we are interested in and how we want to react to them. Looking at our `enable` method, it does the following: + - First, it defines [SourceSectionFilter](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/SourceSectionFilter.html). This filter is a declarative definition of the parts of the source code we are interested in. In our example, we care about all nodes that are considered expressions, and we do not care about internal language parts. @@ -89,22 +82,14 @@ The instrument keeps a mapping from each `Source` to a [Coverage](https://github ### Execution Event Node Guest languages are implemented as Abstract Syntax Tree (AST) interpreters. -The language implementers annotate certain nodes with tags, which allows us to -select which nodes we are interested in, by using the aforementioned -`SourceSectionFilter`, in a language-agnostic manner. - -The main power of the Instrument API lies in its ability to insert specialised -nodes in the AST which "wrap" the nodes of interest. These nodes are built using -the same infrastructure that the language developers use, and are, from the -perspective of the runtime, indistinguishable from the language nodes. This -means that all of the techniques used to optimize guest languages into such high -performing language implementations are available to the tool developers as -well. +The language implementers annotate certain nodes with tags, which allows us to select which nodes we are interested in, by using the aforementioned `SourceSectionFilter`, in a language-agnostic manner. + +The main power of the Instrument API lies in its ability to insert specialised nodes in the AST which "wrap" the nodes of interest. +These nodes are built using the same infrastructure that the language developers use, and are, from the perspective of the runtime, indistinguishable from the language nodes. +This means that all of the techniques used to optimize guest languages into such high performing language implementations are available to the tool developers as well. More information about these techniques is available in the [language implementation documentation](https://github.com/oracle/graal/tree/master/truffle/docs). -Suffice it to say that for Simple Tool to meet its second requirement, we need to -instrument all expressions with our own node that will notify us when that -expression is executed. +Suffice it to say that for Simple Tool to meet its second requirement, we need to instrument all expressions with our own node that will notify us when that expression is executed. For this task we use the [CoverageNode](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/CoverageNode.java). It is a subclass of [ExecutionEventNode](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/ExecutionEventNode.html) which, as the name implies, is used to instrument events during execution. @@ -113,16 +98,13 @@ This method is invoked when the "wrapped" node returns a value, i.e., is success The implementation is rather simple. We just notify the instrument that the node with this particular `SourceSection` has been executed, and the instrument updates the `Coverage` object in its coverage map. The instrument is notified only once per node, as the logic is guarded by the [flag](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/CoverageNode.java#L60). -The fact that this flag is annotated with [CompilationFinal](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/CompilerDirectives.CompilationFinal.html) and that the call to the instrument is preceded by a call to [transferToInterpreterAndInvalidate()](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/CompilerDirectives.html#transferToInterpreterAndInvalidate--) is a standard technique in Truffle which ensures that once this instrumentation is no longer needed (i.e., a node has been executed), the instrumentation is removed from further compilations, along with any performance overhead. +The fact that this flag is annotated with [CompilationFinal](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/CompilerDirectives.CompilationFinal.html) and that the call to the instrument is preceded by a call to [transferToInterpreterAndInvalidate()](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/CompilerDirectives.html#transferToInterpreterAndInvalidate--) is a standard technique in Truffle, which ensures that once this instrumentation is no longer needed (i.e., a node has been executed), the instrumentation is removed from further compilations, along with any performance overhead. -In order for the framework to know how to instantiate the `CoverageNode` when it -is needed, we need to provide a factory for it. +In order for the framework to know how to instantiate the `CoverageNode` when it is needed, we need to provide a factory for it. The factory is the [CoverageEventFactory](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/CoverageEventFactory.java), a subclass of [ExecutionEventNodeFactory](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/ExecutionEventNodeFactory.html). This class just ensures that each `CoverageNode` knows the `SourceSection` it is instrumenting by looking it up in the provided [EventContext](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/EventContext.html). -Finally, when we are [enabling the instrument](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L173), -we tell the instrumenter to use our factory to "wrap" the nodes selected by our -filter. +Finally, when we are [enabling the instrument](https://github.com/graalvm/simpletool/blob/master/src/main/java/com/oracle/truffle/st/SimpleCoverageInstrument.java#L173), we tell the instrumenter to use our factory to "wrap" the nodes selected by our filter. ### Interaction Between Users and Instruments @@ -146,7 +128,7 @@ As mentioned before, Simple Tool is a Maven project. Setting `JAVA_HOME` to a GraalVM installation and running `mvn package` produces a `target/simpletool-.jar`. This is the Simple Tool distribution form. -The [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/) offers a clear separation between the language/tooling code and the application code. +The [Truffle framework](../../truffle/docs/README.md) offers a clear separation between the language/tooling code and the application code. For this reason, putting the JAR on the class path will not result in the framework realizing a new tool is needed. To achieve this we use `--vm.Dtruffle.class.path.append=/path/to/simpletool-.jar` as is illustrated in a [launcher script for our simple tool](https://github.com/graalvm/simpletool/blob/master/simpletool). This script also shows we can [set the CLI options](https://github.com/graalvm/simpletool/blob/master/simpletool#L19) we specified for Simple Tool. @@ -325,7 +307,10 @@ Execution event nodes can implement certain callback methods to intercept runtim 2. `onReturnValue`: executed after a source code element returns a value. 3. `onReturnExceptional`: executed in case the filtered source code element throws an exception. -Execution event nodes are created on a _per code location_ basis. Therefore, they can be used to store data specific to a given source code location in the instrumented application. As an example, an instrumentation node can simply keep track of all code locations that have already been visited using a node-local flag. Such a node-local `boolean` flag can be used to track the execution of AST nodes in the following way: +Execution event nodes are created on a _per code location_ basis. +Therefore, they can be used to store data specific to a given source code location in the instrumented application. +As an example, an instrumentation node can simply keep track of all code locations that have already been visited using a node-local flag. +Such a node-local `boolean` flag can be used to track the execution of AST nodes in the following way: ```java // To keep track of all source code locations executed @@ -349,10 +334,13 @@ public ExecutionEventNode create(final EventContext ec) { } ``` -As the above code shows, an `ExecutionEventNode` is a valid AST node. This implies that the instrumentation code will be optimized by the GraalVM runtime together with the instrumented application, resulting in minimal instrumentation overhead. Furthermore, this allows instrument developers to use the [Truffle framework compiler directives](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/CompilerDirectives.html) directly from instrumentation nodes. In the example, compiler directives are used to inform the GraalVM compiler that `visited` can be considered compilation-final. +As the above code shows, an `ExecutionEventNode` is a valid AST node. +This implies that the instrumentation code will be optimized by the GraalVM runtime together with the instrumented application, resulting in minimal instrumentation overhead. Furthermore, this allows instrument developers to use the [Truffle framework compiler directives](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/CompilerDirectives.html) directly from instrumentation nodes. +In the example, compiler directives are used to inform the GraalVM compiler that `visited` can be considered compilation-final. -Each instrumentation node is bound to a specific code location. Such locations can be accessed by the agent using the provided [`EventContext`](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/EventContext.html) object. -The context object gives instrumentation nodes access to a variety of information about the current AST nodes being executed. Examples of query APIs available to instrumentation agents through `EventContext` include: +Each instrumentation node is bound to a specific code location. +Such locations can be accessed by the agent using the provided [`EventContext`](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/EventContext.html) object. The context object gives instrumentation nodes access to a variety of information about the current AST nodes being executed. +Examples of query APIs available to instrumentation agents through `EventContext` include: 1. `hasTag`: to query an instrumented node for a certain node `Tag` (e.g., to check if a statement node is also a conditional node). 2. `getInstrumentedSourceSection`: to access the [`SourceSection`](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/source/SourceSection.html) associated with the current node. @@ -376,7 +364,10 @@ SourceSectionFilter inputGeneratingLocations = SourceSectionFilter.newBuilder() instrumenter.attachExecutionEventFactory(sourceSectionFilter, inputGeneratingLocations, factory); ``` -The first source section filter (`sourceSectionFilter`, in the example) is a normal filter equivalent to other filters described before, and is used to identify the source code locations to be monitored. The second section filter, `inputGeneratingLocations`, is used by the agent to specify the _intermediate values_ that should be monitored for a certain source section. Intermediate values correspond to _all_ observable values that are involved in the execution of a monitored code element, and are reported to the instrumentation agent by means of the `onInputValue` callback. As an example, let us assume an agent needs to profile all _operand_ values provided to sum operations (i.e., `+`) in JavaScript: +The first source section filter (`sourceSectionFilter`, in the example) is a normal filter equivalent to other filters described before, and is used to identify the source code locations to be monitored. +The second section filter, `inputGeneratingLocations`, is used by the agent to specify the _intermediate values_ that should be monitored for a certain source section. +Intermediate values correspond to _all_ observable values that are involved in the execution of a monitored code element, and are reported to the instrumentation agent by means of the `onInputValue` callback. +As an example, let us assume an agent needs to profile all _operand_ values provided to sum operations (i.e., `+`) in JavaScript: ```javascript var a = 3; @@ -421,13 +412,19 @@ onEnter - VariableWrite onReturnValue - VariableWrite ``` -The `onInputValue` method can be used in combination with source section filters to intercept very fine-grained execution events such as intermediate values used by language expressions. The intermediate values that are accessible to the Instrumentation framework greatly depend on the instrumentation support provided by each language. Moreover, languages may provide additional metadata associated with language-specific `Tag` classes. +The `onInputValue` method can be used in combination with source section filters to intercept very fine-grained execution events such as intermediate values used by language expressions. +The intermediate values that are accessible to the Instrumentation framework greatly depend on the instrumentation support provided by each language. +Moreover, languages may provide additional metadata associated with language-specific `Tag` classes. ### Altering the Execution Flow of an Application -The instrumentation capabilities that we have presented so far enable users to _observe_ certain aspects of a running application. In addition to passive monitoring of an application's behavior, the Instrument API features support for actively _altering_ the behavior of an application at runtime. Such capabilities can be used to write complex instrumentation agents that affect the behavior of a running application to achieve specific runtime semantics. For example, one could alter the semantics of a running application to ensure that certain methods or functions are never executed (e.g., by throwing an exception when they are called). +The instrumentation capabilities that we have presented so far enable users to _observe_ certain aspects of a running application. +In addition to passive monitoring of an application's behavior, the Instrument API features support for actively _altering_ the behavior of an application at runtime. +Such capabilities can be used to write complex instrumentation agents that affect the behavior of a running application to achieve specific runtime semantics. +For example, one could alter the semantics of a running application to ensure that certain methods or functions are never executed (e.g., by throwing an exception when they are called). -Instrumentation agents with such capabilities can be implemented by leveraging the `onUnwind` callback in execution event listeners and factories. As an example, let's consider the following JavaScript code: +Instrumentation agents with such capabilities can be implemented by leveraging the `onUnwind` callback in execution event listeners and factories. +As an example, let's consider the following JavaScript code: ```javascript function inc(x) { @@ -484,6 +481,10 @@ public static class UniversalAnswerInstrument extends TruffleInstrument { } ``` -When enabled, the instrument will execute its `onReturnValue` callback each time a function call returns. The callback reads the associated source section (using `getInstrumentedSourceSection`) and looks for a specific source code pattern (the function call `inc(c)`, in this case). As soon as such code pattern is found, the instrument throws a special runtime exception, called `UnwindException`, that instructs the Instrumentation framework about a change in the current application's execution flow. The exception is intercepted by the `onUnwind` callback of the instrumentation agent, which can be used to return _any_ arbitrary value to the original instrumented application. +When enabled, the instrument will execute its `onReturnValue` callback each time a function call returns. +The callback reads the associated source section (using `getInstrumentedSourceSection`) and looks for a specific source code pattern (the function call `inc(c)`, in this case). +As soon as such code pattern is found, the instrument throws a special runtime exception, called `UnwindException`, that instructs the Instrumentation framework about a change in the current application's execution flow. +The exception is intercepted by the `onUnwind` callback of the instrumentation agent, which can be used to return _any_ arbitrary value to the original instrumented application. -In the example, all calls to `inc(c)` will return `42` regardless of any application-specific data. A more realistic instrument might access and monitor several aspects of an application, and might not rely on source code locations, but rather on object instances or other application-specific data. +In the example, all calls to `inc(c)` will return `42` regardless of any application-specific data. +A more realistic instrument might access and monitor several aspects of an application, and might not rely on source code locations, but rather on object instances or other application-specific data. diff --git a/docs/graalvm-as-a-platform/implement-language.md b/docs/graalvm-as-a-platform/implement-language.md index 28c182776fc9..07b0a70facc2 100644 --- a/docs/graalvm-as-a-platform/implement-language.md +++ b/docs/graalvm-as-a-platform/implement-language.md @@ -11,7 +11,7 @@ toc_group: graalvm-as-a-platform We have found that the easiest way to get started with implementing your own language is by extending an existing language such as SimpleLanguage. [SimpleLanguage](https://github.com/graalvm/simplelanguage) is a demonstration language built using the [Language API](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/package-summary.html). The SimpleLanguage project provides a showcase on how to use the Language APIs for writing your own language. -It aims to use most of the available [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) (henceforth "Truffle") features, and documents their use extensively with inline source documentation. +It aims to use most of the available [Truffle language implementation framework](../../truffle/docs/README.md) (henceforth "Truffle") features, and documents their use extensively with inline source documentation. To start, ensure [Maven3](https://maven.apache.org/download.cgi) and GraalVM are available in your system. @@ -29,12 +29,7 @@ For macOS, use: export JAVA_HOME=/path/to/graalvm/Contents/Home export PATH=/path/to/graalvm/Contents/Home/bin:$PATH ``` -4. Execute `mvn package` from the SimpleLanguage folder to build the language. -The command also builds a `slnative` executable in the `simplelanguage/native` -directory and a `sl-component.jar` language component which later can be installed -into GraalVM using the [GraalVM Updater](../reference-manual/graalvm-updater.md) tool. -Please verify ithat the `native-image` plugin is available in your GraalVM distribution -to avoid build failure: +4. Execute `mvn package` from the SimpleLanguage folder to build the language. The command also builds a `slnative` executable in the `simplelanguage/native` directory and a `sl-component.jar` language component which later can be installed into GraalVM using the [GraalVM Updater](../reference-manual/graalvm-updater.md) tool. Please verify ithat the `native-image` plugin is available in your GraalVM distribution to avoid build failure: ```shell gu list gu install native-image @@ -53,7 +48,8 @@ The SimpleLanguage demonstration language is licensed under the [Universal Permi ## IDE Setup -The [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/) provides language-agnostic infrastructure to realize standard IDE features by providing additional APIs. If you would like to experiment with your language and get the benefits of an IDE, consider importing SimpleLanguage as an example. +The [Truffle framework](../../truffle/docs/README.md) provides language-agnostic infrastructure to realize standard IDE features by providing additional APIs. +If you would like to experiment with your language and get the benefits of an IDE, consider importing SimpleLanguage as an example. ### Eclipse @@ -117,13 +113,10 @@ gu -L install /path/to/sl-component.jar ## SimpleLanguage Native Image -A language built with Truffle can be AOT compiled using [Native Image](../reference-manual/native-image/README.md). Running -`mvn package` in the SimpleLanguage folder also builds a `slnative` executable -in the `native` directory. This executable is the full SimpleLanguage -implementation as a single native application, and has no need for GraalVM in -order to execute SimpleLanguage code. Besides this, a big advantage of using the -native executable when compared to running on GraalVM is the greatly faster -startup time as shown bellow: +A language built with Truffle can be AOT compiled using [Native Image](../reference-manual/native-image/README.md). +Running `mvn package` in the SimpleLanguage folder also builds a `slnative` executable in the `native` directory. +This executable is the full SimpleLanguage implementation as a single native application, and has no need for GraalVM in order to execute SimpleLanguage code. +Besides this, a big advantage of using the native executable when compared to running on GraalVM is the greatly faster startup time as shown bellow: ```shell time ./sl language/tests/HelloWorld.sl == running on org.graalvm.polyglot.Engine@2db0f6b2 @@ -143,23 +136,17 @@ user 0m0.000s sys 0m0.000s ``` -This snipped shows a timed execution of a "Hello World" program using the `sl` -launcher script, which runs SimpleLanguage on GraalVM, using Native -Image. We can see that when running on GraalVM the execution takes 405ms. Since -our SimpleLanguage program does just one print statement, we can conclude that -almost all of this time is spent starting up GraalVM and initializing the -language itself. When using the native executable we see that the execution takes -only 4ms, showing two orders of magnitude faster startup than running on -GraalVM. +This snipped shows a timed execution of a "Hello World" program using the `sl` launcher script, which runs SimpleLanguage on GraalVM, using Native Image. +We can see that when running on GraalVM the execution takes 405ms. +Since our SimpleLanguage program does just one print statement, we can conclude that almost all of this time is spent starting up GraalVM and initializing the language itself. +When using the native executable we see that the execution takes only 4ms, showing two orders of magnitude faster startup than running on GraalVM. For more information on the `native-image` tool consider reading the [reference manual](../reference-manual/native-image/README.md). ### Disable SimpleLanguage Native Image Build -Building the native executable through Maven is attached to the Maven `package` -phase. Since the native executable build can take a bit of time, we provide the -option to skip this build by setting the `SL_BUILD_NATIVE` environment variable -to `false` like so: +Building the native executable through Maven is attached to the Maven `package` phase. +Since the native executable build can take a bit of time, we provide the option to skip this build by setting the `SL_BUILD_NATIVE` environment variable to `false` like so: ```shell export SL_BUILD_NATIVE=false @@ -180,8 +167,7 @@ Skipping the native image build because SL_BUILD_NATIVE is set to false. ## Run SimpleLanguage with the Newest Compiler 21.2.0 -In the outstanding case that you need to execute SimpleLanguage with the newest -version of the GraalVM compiler, please follow these instructions: +In the outstanding case that you need to execute SimpleLanguage with the newest version of the GraalVM compiler, please follow these instructions: 1. Download the latest [JVMCI JDK 8](https://github.com/graalvm/graal-jvmci-8/releases/) and point JAVA_HOME at it: ```shell @@ -215,16 +201,12 @@ mx -v --jdk=jvmci vm -cp /path/to/simplelanguage/launcher/target/launcher-21.2.0 ## Run SimpleLanguage Using Command Line -Executing SimpleLanguage code is normally done with the `sl` script which sets -up the necessary command line depending on whether `JAVA_HOME` points to -GraalVM or another JVM installation. The following subsections describe the -command line for both cases. +Executing SimpleLanguage code is normally done with the `sl` script which sets up the necessary command line depending on whether `JAVA_HOME` points to GraalVM or another JVM installation. +The following subsections describe the command line for both cases. ### Run SimpleLanguage with GraalVM as JAVA_HOME -Assuming `JAVA_HOME` points to the GraalVM installation and that the current -working directory is the `simplelanguage` directory, to run SimpleLanguage one -should execute the following command: +Assuming `JAVA_HOME` points to the GraalVM installation and that the current working directory is the `simplelanguage` directory, to run SimpleLanguage one should execute the following command: ```shell $JAVA_HOME/bin/java \ @@ -233,25 +215,18 @@ $JAVA_HOME/bin/java \ com.oracle.truffle.sl.launcher.SLMain language/tests/Add.sl ``` -In short, we place the launcher JAR on the class path and execute its main -class, but we inform GraalVM of the presence of SimpleLanguage by using the -`-Dtruffle.class.path.append` option and providing it the path to the fat -language JAR. Having the language on a separate class path ensures a strong -separation between the language implementation and its embedding context (in -this case, the launcher). +In short, we place the launcher JAR on the class path and execute its main class, but we inform GraalVM of the presence of SimpleLanguage by using the `-Dtruffle.class.path.append` option and providing it the path to the fat language JAR. +Having the language on a separate class path ensures a strong separation between the language implementation and its embedding context (in this case, the launcher). #### Disable Class Path Separation *NOTE! This should only be used during development.* -For development purposes it is useful to disable the class path separation and enable having the -language implementation on the application class path (for example, for testing +For development purposes it is useful to disable the class path separation and enable having the language implementation on the application class path (for example, for testing the internals of the language). -For the GraalVM distribution based on JDK 8, you can add the `-XX:-UseJVMCIClassLoader` -option. This disables the class path isolation, enabling the language -implementation to be placed on the application class path. The command line can -be as follows: +For the GraalVM distribution based on JDK 8, you can add the `-XX:-UseJVMCIClassLoader` option. +This disables the class path isolation, enabling the language implementation to be placed on the application class path. The command line can be as follows: ```shell $JAVA_HOME/bin/java \ @@ -260,11 +235,11 @@ $JAVA_HOME/bin/java \ com.oracle.truffle.sl.launcher.SLMain language/tests/Add.sl ``` -For the JDK 11-based distribution of GraalVM, the `-XX:-UseJVMCIClassLoader` option -is not valid. The Java Module System isolation is used. You can achieve the same behavior -using `--add-exports` or `--upgrade-module-path`. The latter is preferable. +For the JDK 11-based distribution of GraalVM, the `-XX:-UseJVMCIClassLoader` option is not valid. +The Java Module System isolation is used. You can achieve the same behavior using `--add-exports` or `--upgrade-module-path`. The latter is preferable. -The Language API JAR on Maven Central exports all API packages in its module-info. Apply the `--upgrade-module-path` option together with `-Dgraalvm.locatorDisabled=true` and this JAR to export Language API packages: +The Language API JAR on Maven Central exports all API packages in its module-info. +Apply the `--upgrade-module-path` option together with `-Dgraalvm.locatorDisabled=true` and this JAR to export Language API packages: ```shell -Dgraalvm.locatorDisabled=true --module-path=:${truffle.dir} --upgrade-module-path=${truffle.dir}/truffle-api.jar ``` @@ -273,15 +248,10 @@ A sample POM using `--upgrade-module-path` to export Language API packages can b ### Other JVM Implementations -Unlike GraalVM, which includes all the dependencies needed to run a language -implemented with [Truffle](/graalvm-as-a-platform/language-implementation-framework/), other JVM implementations need additional -JARs to be present on the class path. These are the Language API and GraalVM SDK -JARs available from Maven Central. +Unlike GraalVM, which includes all the dependencies needed to run a language implemented with [Truffle](../../truffle/docs/README.md), other JVM implementations need additional JARs to be present on the class path. +These are the Language API and GraalVM SDK JARs available from Maven Central. -Assuming `JAVA_HOME` points to a stock JDK installation, and that the current -working directory is the `simplelanguage` directory and the Language API and -GraalVM SDK JARs are present in that directory, one can execute SimpleLanguage -with the following command: +Assuming `JAVA_HOME` points to a stock JDK installation, and that the current working directory is the `simplelanguage` directory and the Language API and GraalVM SDK JARs are present in that directory, one can execute SimpleLanguage with the following command: ```shell $JAVA_HOME/bin/java \ diff --git a/docs/guides/guides.md b/docs/guides/guides.md index cddfe00d279a..ee499535af58 100644 --- a/docs/guides/guides.md +++ b/docs/guides/guides.md @@ -21,10 +21,10 @@ At runtime, an application is loaded and executed normally by the JVM. In order to follow the steps in this guide, you must have GraalVM installed. In case you do not have it installed, getting GraalVM downloaded and ready-to-go should only take a few minutes. Choose your operating system and proceed to the installation steps: -- [Linux](/docs/getting-started/linux/) -- [Linux AArch64](/docs/getting-started/linux-aarch64/) -- [macOS](/docs/getting-started/macos/) -- [Windows](/docs/getting-started/windows/) +- [Linux](../getting-started/graalvm-community/linux.md) +- [Linux AArch64](../getting-started/graalvm-community/linux-aarch64.md) +- [macOS](../getting-started/graalvm-community/macos.md) +- [Windows](../getting-started/graalvm-community/windows.md) For the purpose of this guide, GraalVM Enterprise based on Java 11 distribution for macOS platform is used. To ensure you have successfully installed GraalVM, verify it is available in the `PATH` environment variable and the `JAVA_HOME` points to it. diff --git a/docs/reference-manual/embedding/embed-languages.md b/docs/reference-manual/embedding/embed-languages.md index 24bc455db339..af23ca87db09 100644 --- a/docs/reference-manual/embedding/embed-languages.md +++ b/docs/reference-manual/embedding/embed-languages.md @@ -17,11 +17,10 @@ permalink: /reference-manual/embed-languages/ * [Build Native Images from Polyglot Applications](#build-native-images-from-polyglot-applications) * [Code Caching Across Multiple Contexts](#code-caching-across-multiple-contexts) * [Embed languages in Guest Languages](#embed-languages-in-guest-languages) -* [Step Through with Execution Listeners](#step-through-with-execution-listeners) * [Build a Shell for Many Languages](#build-a-shell-for-many-languages) +* [Step Through with Execution Listeners](#step-through-with-execution-listeners) * [Configure Sandbox Resource Limits](#configure-sandbox-resource-limits) - The GraalVM Polyglot API lets you embed and run code from guest languages in JVM-based host applications. Throughout this section, you will learn how to create a host application in Java that @@ -31,7 +30,7 @@ beneath each code example to choose between JavaScript, R, Ruby, and Python. Ensure you set up GraalVM before you begin. ## Compile and Run a Polyglot Application -GraalVM can run polyglot applications written in any language implemented with the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/). +GraalVM can run polyglot applications written in any language implemented with the [Truffle language implementation framework](../../../truffle/docs/README.md). These languages are henceforth referenced as **guest languages**. Complete the steps in this section to create a sample polyglot @@ -493,7 +492,7 @@ Caching may be disabled explicitly by setting [cached(boolean cached)](https:// Consider the following code snippet as an example: -``` +```java public class Main { public static void main(String[] args) { try (Engine engine = Engine.create()) { @@ -543,12 +542,12 @@ public class Main { public static void main(String[] args) { try (Context outer = Context.newBuilder() .allowAllAccess(true) - .build()) { + .build()) { outer.eval("js", "inner = Java.type('org.graalvm.polyglot.Context').create()"); outer.eval("js", "value = inner.eval('js', '({data:42})')"); int result = outer.eval("js", "value.data").asInt(); outer.eval("js", "inner.close()"); - + System.out.println("Valid " + (result == 42)); } } @@ -600,8 +599,6 @@ for (;;) { } ``` - - ## Step Through with Execution Listeners The GraalVM Polyglot API allows users to instrument the execution of guest languages through [ExecutionListener class](http://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/management/ExecutionListener.html). For example, it lets you attach an execution listener that is invoked for every statement of the guest language program. Execution listeners diff --git a/docs/reference-manual/embedding/sandbox-options.md b/docs/reference-manual/embedding/sandbox-options.md index 116e08e0aef6..2c20f3904650 100644 --- a/docs/reference-manual/embedding/sandbox-options.md +++ b/docs/reference-manual/embedding/sandbox-options.md @@ -6,7 +6,7 @@ The following document describes how to configure sandbox resource limits using In general all resource limit options are prefixed with `sandbox` option group and they can be listed using the help of any language launcher provided in GraalVM e.g. `js --help:tools`. Polyglot options can be provided through the language launcher, using the polyglot embedding API of the Graal SDK, or on the JVM using a system property. -For better understanding of the examples it is recommended to read the [polyglot embedding guide](/reference-manual/embed-languages/) of the reference manual first. +For better understanding of the examples it is recommended to read the [polyglot embedding guide](embed-languages.md) of the reference manual first. Currently all sandbox options are experimental therefore in these examples it is assumed that experimental options are enabled (e.g. with `--experimental-options`). The options are a best effort approach to limiting resource usage of guest applications. diff --git a/docs/reference-manual/java/Operations.md b/docs/reference-manual/java/Operations.md index d295a86b7e84..88064a7c2416 100644 --- a/docs/reference-manual/java/Operations.md +++ b/docs/reference-manual/java/Operations.md @@ -9,75 +9,55 @@ permalink: /reference-manual/java/operations/ ## Running the GraalVM Compiler in Native Image vs on the JVM -When running the GraalVM compiler on the JVM, it goes through the same warm-up phase that the -rest of the Java application does. That is, it is first interpreted before -its hot methods are compiled. This can translate into slightly longer times -until the application reaches peak performance when compared to the native compilers -in the JVM such as C1 and C2. - -To address the issue of taking longer to reach to peak performance, **libgraal** -was introduced -- a shared library, produced using [Native Image](../native-image/README.md) to ahead-of-time compile the compiler itself. That means the GraalVM Enterprise -compiler is deployed as a native shared library. - -In this mode, the -compiler uses memory separate from the HotSpot heap, and it runs compiled from -the start. Therefore it has execution properties similar to other native HotSpot -compilers such as C1 and C2. Currently, this is the **default mode** of -operation. It can be disabled with `-XX:-UseJVMCINativeLibrary`. +When running the GraalVM compiler on the JVM, it goes through the same warm-up phase that the rest of the Java application does. +That is, it is first interpreted before its hot methods are compiled. +This can translate into slightly longer times until the application reaches peak performance when compared to the native compilers in the JVM such as C1 and C2. + +To address the issue of taking longer to reach to peak performance, **libgraal** was introduced -- a shared library, produced using [Native Image](../native-image/README.md) to ahead-of-time compile the compiler itself. +That means the GraalVM Enterprise compiler is deployed as a native shared library. + +In this mode, the compiler uses memory separate from the HotSpot heap, and it runs compiled from the start. +Therefore it has execution properties similar to other native HotSpot compilers such as C1 and C2. +Currently, this is the **default mode** of operation. +It can be disabled with `-XX:-UseJVMCINativeLibrary`. ## Measuring Performance The first thing to be sure of when measuring performance is to ensure the JVM is using the GraalVM Enterprise compiler. -In the GraalVM binary, the JVM is configured to use the GraalVM compiler -as the top tier compiler by default. You can confirm this by adding `-Dgraal.ShowConfiguration=info` -to the command line. It will produce a line of output similar to the one below -when the compiler is initialized: +In the GraalVM binary, the JVM is configured to use the GraalVM compiler as the top tier compiler by default. +You can confirm this by adding `-Dgraal.ShowConfiguration=info` to the command line. +It will produce a line of output similar to the one below when the compiler is initialized: ```shell Using Graal compiler configuration 'community' provided by org.graalvm.compiler.hotspot.CommunityCompilerConfigurationFactory loaded from jar:file:/Users/dsimon/graal/graal/compiler/mxbuild/dists/graal.jar!/org/graalvm/compiler/hotspot/CommunityCompilerConfigurationFactory.class ``` -Note: The GraalVM compiler is only initialized on the first top-tier JIT compilation request -so if your application is short-lived, you may not see this output. +Note: The GraalVM compiler is only initialized on the first top-tier JIT compilation request so if your application is short-lived, you may not see this output. -Optimizing JVM-based applications is a science in itself. The compilation may not -even be a factor in the case of poor performance as the problem may -lie in any other part of the VM (I/O, garbage collection, threading, etc), or in -a poorly written application or 3rd party library code. For this reason, it's -worth utilizing the [JDK Mission Control](https://www.oracle.com/java/technologies/jdk-mission-control.html) tool chain to -diagnose the application behavior. +Optimizing JVM-based applications is a science in itself. The compilation may not even be a factor in the case of poor performance as the problem may +lie in any other part of the VM (I/O, garbage collection, threading, etc), or in a poorly written application or 3rd party library code. +For this reason, it's worth utilizing the [JDK Mission Control](https://www.oracle.com/java/technologies/jdk-mission-control.html) tool chain to diagnose the application behavior. -You can also compare performance against the native top-tier compiler in the JVM by -adding `-XX:-UseJVMCICompiler` to the command line. +You can also compare performance against the native top-tier compiler in the JVM by adding `-XX:-UseJVMCICompiler` to the command line. -If you observe a significant performance regression when using the GraalVM compiler, please -open an issue on GitHub. Attaching a Java Flight Recorder log and instructions -to reproduce the issue makes investigation easier and thus the -chances of a fix higher. Even better is if you can submit a [JMH](http://openjdk.java.net/projects/code-tools/jmh/) -benchmark that represents the hottest parts of your application (as identified -by a profiler). This allows us to very quickly pinpoint missing optimization -opportunities or to offer suggestions on how to restructure the code to -avoid or reduce performance bottlenecks. +If you observe a significant performance regression when using the GraalVM compiler, please open an issue on GitHub. +Attaching a Java Flight Recorder log and instructions to reproduce the issue makes investigation easier and thus the chances of a fix higher. +Even better is if you can submit a [JMH](http://openjdk.java.net/projects/code-tools/jmh/) benchmark that represents the hottest parts of your application (as identified by a profiler). +This allows us to very quickly pinpoint missing optimization opportunities or to offer suggestions on how to restructure the code to avoid or reduce performance bottlenecks. ## Troubleshooting the GraalVM Compiler -Like all software, the GraalVM compiler is not guaranteed to be bug free so it is useful to -know how to diagnose and submit useful bug reports if you encounter issues. +Like all software, the GraalVM compiler is not guaranteed to be bug free so it is useful to know how to diagnose and submit useful bug reports if you encounter issues. -If you spot a security vulnerability, please do **not** report it via GitHub Issues or the public mailing lists, -but via the process outlined at [Reporting Vulnerabilities guide](https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html). +If you spot a security vulnerability, please do **not** report it via GitHub Issues or the public mailing lists, but via the process outlined at [Reporting Vulnerabilities guide](https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html). ### Compilation Exceptions -One advantage of the compiler being written in Java is that runtime exceptions during -compilation are not fatal VM errors. Instead, each compilation has an exception -handler that takes action based on the `graal.CompilationFailureAction` -property. +One advantage of the compiler being written in Java is that runtime exceptions during compilation are not fatal VM errors. +Instead, each compilation has an exception handler that takes action based on the `graal.CompilationFailureAction` property. -The default value is `Silent`. Specifying `Diagnose` causes failing compilations to be retried -with extra diagnostics enabled. In this case, just before the VM exits, all diagnostic output -captured during retried compilations is written to a `.zip` file and its location -is printed on the console: +The default value is `Silent`. Specifying `Diagnose` causes failing compilations to be retried with extra diagnostics enabled. +In this case, just before the VM exits, all diagnostic output captured during retried compilations is written to a `.zip` file and its location is printed on the console: ```shell Graal diagnostic output saved in /Users/demo/graal-dumps/1499768882600/graal_diagnostics_64565.zip ``` @@ -92,11 +72,8 @@ are also supported: ### Code Generation Errors The other type of error you might encounter with compilers is the production of incorrect machine code. -This error can cause a VM crash, which should produce a file that starts with -`hs_err_pid` in the current working directory of the VM process. In most cases, -there is a section in the file that shows the stack at the time of the crash, -including the type of code for each frame in the stack, as in the following -example: +This error can cause a VM crash, which should produce a file that starts with `hs_err_pid` in the current working directory of the VM process. +In most cases, there is a section in the file that shows the stack at the time of the crash, including the type of code for each frame in the stack, as in the following example: ```shell Stack: [0x00007000020b1000,0x00007000021b1000], sp=0x00007000021af7a0, free space=1017k @@ -106,16 +83,14 @@ j org.graalvm.compiler.core.gen.NodeLIRBuilder.doBlock(Lorg/graalvm/compiler/no j org.graalvm.compiler.core.LIRGenerationPhase.emitBlock(Lorg/graalvm/compiler/nodes/spi/NodeLIRBuilderTool;Lorg/graalvm/compiler/lir/gen/LIRGenerationResult;Lorg/graalvm/compiler/nodes/cfg/Block;Lorg/graalvm/compiler/nodes/StructuredGraph;Lorg/graalvm/compiler/core/common/cfg/BlockMap;)V+65 ``` -This example shows that the top frame was compiled (J) by the JVMCI compiler, -which is the GraalVM compiler. The crash occurred at offset 0x141 in the machine -code produced for: +This example shows that the top frame was compiled (J) by the JVMCI compiler, which is the GraalVM compiler. +The crash occurred at offset 0x141 in the machine code produced for: ```shell org.graalvm.compiler.core.gen.NodeLIRBuilder.matchComplexExpressions(Ljava/util/List;)V ``` -The next two frames in the stack were executed in the interpreter (j). The -location of the crash is also often indicated near the top of the file with -something like this: +The next two frames in the stack were executed in the interpreter (j). +The location of the crash is also often indicated near the top of the file with something like this: ```shell # Problematic frame: # J 761 JVMCI org.graalvm.compiler.core.gen.NodeLIRBuilder.matchComplexExpressions(Ljava/util/List;)V (299 bytes) @ 0x0000000108a2fc01 [0x0000000108a2fac0+0x141] (null) @@ -123,8 +98,7 @@ something like this: In this example, there is likely an error in the code produced by the GraalVM compiler for `NodeLIRBuilder.matchComplexExpressions`. -When filing an issue on [GitHub](https://github.com/oracle/graal/issues) -for such a crash, you should first attempt to reproduce the crash with extra +When filing an issue on [GitHub](https://github.com/oracle/graal/issues) for such a crash, you should first attempt to reproduce the crash with extra diagnostics enabled for the compilation of the problematic method. In this example, you would add the following to your command line: ```shell @@ -132,21 +106,15 @@ In this example, you would add the following to your command line: ``` These options are described in more detail [here](https://github.com/oracle/graal/blob/master/compiler/docs/Debugging.md). -In brief, these options tell the compiler to capture snapshots of the compiler state at -verbosity level 2 while compiling any method named `matchComplexExpressions` in -a class with a simple name of `NodeLIRBuilder`. The complete format of the -`MethodFilter` option is described in the output of `java -XX:+JVMCIPrintProperties`. +In brief, these options tell the compiler to capture snapshots of the compiler state at verbosity level 2 while compiling any method named `matchComplexExpressions` in a class with a simple name of `NodeLIRBuilder`. +The complete format of the `MethodFilter` option is described in the output of `java -XX:+JVMCIPrintProperties`. -Quite often, the crash location does not exist directly in the problematic method -mentioned in the crash log but comes from an inlined method. +Quite often, the crash location does not exist directly in the problematic method mentioned in the crash log but comes from an inlined method. -In such a case, simply filtering for the problematic method might not capture an -erroneous compilation causing a crash. +In such a case, simply filtering for the problematic method might not capture an erroneous compilation causing a crash. -To improve the likelihood of capturing an erroneous compilation, you need to -broaden the `MethodFilter` value. To guide this, add `-Dgraal.PrintCompilation=true` -when trying to reproduce the crash so you can see what was compiled just before -the crash. +To improve the likelihood of capturing an erroneous compilation, you need to broaden the `MethodFilter` value. +To guide this, add `-Dgraal.PrintCompilation=true` when trying to reproduce the crash so you can see what was compiled just before the crash. The following shows sample output from the console: ```shell @@ -166,19 +134,15 @@ HotSpotCompilation-1221 Lorg/graalvm/compiler/hotspot/amd64/AMD64HotSpotL # Failed to write core dump. Core dumps have been disabled. To enable core dumping, try "ulimit -c unlimited" before starting Java again ``` Here we see that the crash happened in a different method than the first crash. -As such, we expand the filter argument to be `-Dgraal.MethodFilter= -NodeLIRBuilder.matchComplexExpressions,AMD64HotSpotLIRGenerator.getResult` -and run again. +As such, we expand the filter argument to be `-Dgraal.MethodFilter=NodeLIRBuilder.matchComplexExpressions,AMD64HotSpotLIRGenerator.getResult` and run again. -When the VM crashes in this way, it does not execute the shutdown code that -archives the GraalVM compiler diagnostic output or delete the directory it was written to. +When the VM crashes in this way, it does not execute the shutdown code that archives the GraalVM compiler diagnostic output or delete the directory it was written to. This must be done manually after the crash. By default, the directory is `$PWD/graal-dumps/`; for example, `./graal-dumps/1499938817387`. However, you can set the directory with `-Dgraal.DumpPath=`. -A message, such as the following, is printed to the console when this -directory is first used by the compiler: +A message, such as the following, is printed to the console when this directory is first used by the compiler: ```shell Dumping debug output in /Users/demo/graal-dumps/1499768882600 ``` diff --git a/docs/reference-manual/java/README.md b/docs/reference-manual/java/README.md index 6dac35785069..ce9337c9355f 100644 --- a/docs/reference-manual/java/README.md +++ b/docs/reference-manual/java/README.md @@ -14,7 +14,7 @@ The JVM passes bytecode to the GraalVM compiler, which compiles that to the mach GraalVM's dynamic compiler can improve the efficiency and the speed of applications written in Java, Scala, Kotlin, or other JVM languages through unique approaches to code analysis and optimization. For example, it assures performance advantages for highly abstracted programs due to its ability to remove costly object allocations. -To learn more, go to the [Compiler](/reference-manual/compiler/) page. +To learn more, go to the [Compiler](../compiler.md) page. The open source compiler's code is available on [GitHub](https://github.com/oracle/graal/tree/master/compiler). ## Compiler Operating Modes @@ -28,10 +28,10 @@ This is the default and recommended mode of operation. - **jargraal**: the GraalVM compiler goes through the same warm-up phase that the rest of the Java application does. That is, it is first interpreted before its hot methods are compiled. This mode is selected with the `-XX:-UseJVMCINativeLibrary` command-line option. This will delay the time to reach peak performance as the compiler itself needs to be compiled before it produces code quickly. -This mode allows you to [debug the GraalVM compiler with a Java debugger](Operations.md/#troubleshooting-the-graalvm-compiler). +This mode allows you to [debug the GraalVM compiler with a Java debugger](Operations.md#troubleshooting-the-graalvm-compiler). ## Interoperability -In addition to running JVM-based languages on GraalVM, you can also call any other language implemented with the [Truffle language implementation framework](../truffle-framework/README.md) directly from Java. -See the [Polyglot Programming](../polyglot-programming.md) and [Embedding Languages](../embed-languages.md) guides for more information about interoperability with other programming languages. +In addition to running JVM-based languages on GraalVM, you can also call any other language implemented with the [Truffle language implementation framework](../../../truffle/docs/README.md) directly from Java. +See the [Polyglot Programming](../polyglot-programming.md) and [Embedding Languages](../embedding/embed-languages.md) guides for more information about interoperability with other programming languages. From 24b0aacc52fe25a1852bba3ffe95825ac9dbcf77 Mon Sep 17 00:00:00 2001 From: Olga Gupalo Date: Mon, 13 Dec 2021 18:09:24 +0200 Subject: [PATCH 3/4] Use rel paths on URLs instead of permalinks --- docs/introduction.md | 38 ++--- docs/reference-manual/compiler.md | 10 +- docs/reference-manual/graalvm-updater.md | 104 ++++++------- .../reference-manual/java-on-truffle/Demos.md | 9 +- docs/reference-manual/java-on-truffle/FAQ.md | 2 +- .../java-on-truffle/HotSwapPluginAPI.md | 10 +- .../java-on-truffle/ImplementationDetails.md | 8 +- .../java-on-truffle/Interoperability.md | 2 +- .../java-on-truffle/README.md | 20 +-- docs/reference-manual/llvm/Compatibility.md | 18 +-- docs/reference-manual/llvm/Compiling.md | 42 +++--- docs/reference-manual/llvm/Debugging.md | 15 +- .../reference-manual/llvm/Interoperability.md | 22 +-- docs/reference-manual/llvm/NativeExecution.md | 18 +-- docs/reference-manual/llvm/README.md | 12 +- docs/reference-manual/native-image/Agent.md | 98 ++++++++----- .../native-image/BuildConfiguration.md | 103 ++++++------- docs/reference-manual/native-image/C-API.md | 4 +- .../native-image/ClassInitialization.md | 6 +- .../native-image/DynamicProxy.md | 3 +- .../native-image/HostedvsRuntimeOptions.md | 16 +- .../ImplementingNativeMethodsInJavaWithSVM.md | 138 +++++++----------- docs/reference-manual/native-image/JNI.md | 4 +- .../native-image/LLVMBackend.md | 9 +- .../native-image/Limitations.md | 27 ++-- .../NativeImageHeapdumpEnterprise.md | 48 +++--- docs/reference-manual/native-image/Options.md | 21 +-- docs/reference-manual/native-image/README.md | 63 ++++---- docs/reference-manual/native-image/Reports.md | 9 +- .../native-image/Resources.md | 22 +-- docs/reference-manual/polyglot-programming.md | 21 +-- docs/reference-manual/reference-manuals.md | 26 ++-- docs/reference-manual/wasm/README.md | 6 +- docs/tools/chrome-debugger.md | 4 +- docs/tools/code-coverage.md | 59 +++----- docs/tools/dap.md | 4 +- docs/tools/graalvm-insight.md | 60 ++++---- docs/tools/ideal-graph-visualizer.md | 80 +++++----- docs/tools/lsp.md | 9 +- docs/tools/profiling.md | 58 +++----- docs/tools/visualvm.md | 72 ++++----- docs/tools/vscode/graalvm/README.md | 24 +-- docs/tools/vscode/micronaut/README.md | 2 +- docs/tools/vscode/vscode.md | 8 +- 44 files changed, 577 insertions(+), 757 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index 65ddeb55c202..b8af73d11e14 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -26,7 +26,7 @@ This page provides an architectural overview of GraalVM and its runtime modes, s GraalVM adds an [advanced just-in-time (JIT) optimizing compiler](https://github.com/oracle/graal/tree/master/compiler), which is written in Java, to the HotSpot Java Virtual Machine. -In addition to running Java and JVM-based languages, GraalVM's [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) makes it possible to run JavaScript, Ruby, Python, and a number of other popular languages on the JVM. +In addition to running Java and JVM-based languages, [GraalVM's language implementation framework (Truffle)](../truffle/docs/README.md) makes it possible to run JavaScript, Ruby, Python, and a number of other popular languages on the JVM. With GraalVM Truffle, Java and other supported languages can directly interoperate with each other and pass data back and forth in the same memory space. ## Runtime Modes @@ -34,18 +34,18 @@ With GraalVM Truffle, Java and other supported languages can directly interopera GraalVM is unique as a runtime environment offering several modes of operation: JVM runtime mode, Native Image, Java on Truffle (the same Java applications can be run on either). #### JVM Runtime Mode -When running programs on the HotSpot JVM, GraalVM defaults to the [GraalVM compiler](/reference-manual/compiler/) as the top-tier JIT compiler. +When running programs on the HotSpot JVM, GraalVM defaults to the [GraalVM compiler](reference-manual/compiler.md) as the top-tier JIT compiler. At runtime, an application is loaded and executed normally on the JVM. The JVM passes bytecodes for Java or any other JVM-native language to the compiler, which compiles that to the machine code and returns it to the JVM. -Interpreters for supported languages, written on top of the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/), are themselves Java programs that run on the JVM. +Interpreters for supported languages, written on top of the [Truffle framework](../truffle/docs/README.md), are themselves Java programs that run on the JVM. #### Native Image -[Native Image](/reference-manual/native-image/) is an innovative technology that compiles Java code into a standalone binary executable or a native shared library. +[Native Image](reference-manual/native-image/README.md) is an innovative technology that compiles Java code into a standalone binary executable or a native shared library. The Java bytecode that is processed during the native image build includes all application classes, dependencies, third party dependent libraries, and any JDK classes that are required. A generated self-contained native executable is specific to each individual operating systems and machine architecture that does not require a JVM. #### Java on Truffle -[Java on Truffle](/reference-manual/java-on-truffle/) is an implementation of the Java Virtual Machine Specification, built with the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/). +[Java on Truffle](reference-manual/java-on-truffle/README.md) is an implementation of the Java Virtual Machine Specification, built with the [Truffle language implementation framework](../truffle/docs/README.md). It is a complete Java VM that includes all core components, implements the same API as the Java Runtime Environment library, and reuses all JARs and native libraries from GraalVM. Java on Trufle is an experimental technology in GraalVM, available as of version 21.0.0. @@ -55,9 +55,9 @@ GraalVM is available as **GraalVM Enterprise** and **GraalVM Community** edition GraalVM Enterprise is based on Oracle JDK while GraalVM Community is based on OpenJDK. GraalVM is available for Linux, macOS, and Windows platforms on x86 64-bit systems, and for Linux on ARM 64-bit system. -The GraalVM distribution based on Oracle JDK 16 is experimental with [several known limitations](/release-notes/known-issues/). +The GraalVM distribution based on Oracle JDK 17 is experimental with [several known limitations](https://www.graalvm.org/release-notes/known-issues/). Depending on the platform, the distributions are shipped as *.tar.gz* or *.zip* archives. -See the [Getting Started guide](/docs/getting-started/) for installation instructions. +See the [Getting Started guide](getting-started/graalvm-community/get-started-graalvm-community.md) for installation instructions. ## Distribution Components List @@ -77,24 +77,24 @@ The core components enable using GraalVM as a runtime platform for programs writ **Utilities** * JavaScript REPL with the JavaScript interpreter * `lli` tool to directly execute programs from LLVM bitcode -* [GraalVM Updater](/reference-manual/graalvm-updater/) to install additional functionalities +* [GraalVM Updater](reference-manual/graalvm-updater.md) to install additional functionalities ### Additional Components GraalVM core installation can be extended with more languages runtimes and utilities. Tools/Utilities: -* [Native Image](/reference-manual/native-image/) -- a technology to compile an application ahead-of-time into a native executable. -* [LLVM toolchain](/reference-manual/llvm/) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime. -* [Java on Truffle](/reference-manual/java-on-truffle/) -- a JVM implementation built upon the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/) to run Java via a Java bytecode interpreter. +* [Native Image](reference-manual/native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable. +* [LLVM toolchain](reference-manual/llvm/README.md) -- a set of tools and APIs for compiling native programs to bitcode that can be executed with on the GraalVM runtime. +* [Java on Truffle](reference-manual/java-on-truffle/README.md) -- a JVM implementation built upon the [Truffle framework](../truffle/docs/README.md) to run Java via a Java bytecode interpreter. Runtimes: -* [Node.js](/reference-manual/js/) -- the Node.js 14.16.1 runtime for JavaScript -* [Python](/reference-manual/python/) -- Python 3.8.5 compatible -* [Ruby](/reference-manual/ruby/) -- Ruby 2.7.3 compatible -* [R](/reference-manual/r/) -- GNU R 4.0.3 compatible -* [GraalWasm](/reference-manual/wasm/) -- WebAssembly (Wasm) +* [Node.js](reference-manual/js/README.md) -- the Node.js 14.17.6 runtime for JavaScript +* [Python](reference-manual/python/README.md) -- Python 3.8.5 compatible +* [Ruby](reference-manual/ruby/README.md) -- Ruby 2.7.3 compatible +* [R](reference-manual/r/README.md) -- GNU R 4.0.3 compatible +* [GraalWasm](reference-manual/wasm/README.md) -- WebAssembly (Wasm) ## Licensing and Support @@ -126,11 +126,11 @@ The following table lists production-ready and experimental features in GraalVM ## What to Read Next -Whether you are new to GraalVM or have little experience using it, continue to [Get Started with GraalVM](/docs/getting-started/). +Whether you are new to GraalVM or have little experience using it, continue to [Get Started with GraalVM](getting-started/graalvm-community/get-started-graalvm-community.md). Install GraalVM on your local machine, try running the examples provided in the guide, or test GraalVM with your workload. -After that we suggest you to look at more complex [Examples Applications](/examples/). +After that we suggest you to look at more complex [Examples Applications](examples/examples.md). -Developers who have GraalVM already installed or have experience using, can skip the getting started guide and proceed to the [Reference Manuals](/reference-manual/) for in-depth coverage of GraalVM technologies. +Developers who have GraalVM already installed or have experience using, can skip the getting started guide and proceed to the [Reference Manuals](reference-manual/reference-manuals.md) for in-depth coverage of GraalVM technologies. To start coding with the GraalVM Polyglot APIs, check out the [GraalVM SDK Java API Reference](http://www.graalvm.org/sdk/javadoc). diff --git a/docs/reference-manual/compiler.md b/docs/reference-manual/compiler.md index 66da06569e70..1e8f12e5033b 100644 --- a/docs/reference-manual/compiler.md +++ b/docs/reference-manual/compiler.md @@ -27,7 +27,7 @@ The GraalVM compiler assures performance advantages for highly-abstracted progra Code using more abstraction and modern Java features like Streams or Lambdas will see greater speedups. Low-level code or code that converges to things like I/O, memory allocation, or garbage collection will see less improvement. Consequently, an application running on GraalVM needs to spend less time doing memory management and garbage collection. -For more information on performance tuning, refer to [Compiler Configuration on JVM](/reference-manual/java/options/). +For more information on performance tuning, refer to [Compiler Configuration on JVM](java/Options.md). ## Graph Compilation @@ -37,7 +37,7 @@ A *graph* was selected for this role. The graph can represent similar statements of different languages in the same way, like "if" statements or loops, which makes it possible to mix languages in the same program. The GraalVM compiler can then perform language-independent optimization and generate machine code on this graph. -GraalVM also includes the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) -- a library, written in Java -- to build interpreters for programming languages, which then run on GraalVM. +GraalVM also includes the [Truffle language implementation framework](../../truffle/docs/README.md) -- a library, written in Java -- to build interpreters for programming languages, which then run on GraalVM. These languages can consequently benefit from the optimization possibilities of the GraalVM compiler. The pipeline for such compilation is: @@ -50,9 +50,9 @@ hot (i.e., called many times), it is scheduled for compilation by the compiler. ## Ahead-of-time Compilation -Besides the Truffle framework, GraalVM incorporates its optimizing compiler into an advanced ahead-of-time (AOT) compilation technology -- [Native Image](/reference-manual/native-image/) -- which translates Java and JVM-based code into a native platform executable. +Besides the Truffle framework, GraalVM incorporates its optimizing compiler into an advanced ahead-of-time (AOT) compilation technology -- [Native Image](native-image/README.md) -- which translates Java and JVM-based code into a native platform executable. These native executables start nearly instantaneously, are smaller, and consume less resources of the same Java application, making them ideal for cloud deployments and microservices. -For more information about AOT compilation, go to [Native Image](/reference-manual/native-image/). +For more information about AOT compilation, go to [Native Image](native-image/README.md). ## Compiler Operating Modes @@ -80,7 +80,7 @@ This will produce diagnostic data for every method compiled by the compiler. To refine the set of methods for which diagnostic data is produced, use the `-Dgraal.MethodFilter=.` option. For example, `-Dgraal.MethodFilter=java.lang.String.*,HashMap.get` will produce diagnostic data only for methods in the `java.lang.String` class as well as methods named `get` in a class whose non-qualified name is `HashMap`. -Instead of being written to a file, diagnostic data can also be sent over the network to the [Ideal Graph Visualizer](/tools/igv/). +Instead of being written to a file, diagnostic data can also be sent over the network to the [Ideal Graph Visualizer](../tools/ideal-graph-visualizer.md). This requires the `-Dgraal.PrintGraph=Network` option, upon which the compiler will try to send diagnostic data to _127.0.0.1:4445_. This network endpoint can be configured with the `-Dgraal.PrintGraphHost` and `-Dgraal.PrintGraphPort` options. diff --git a/docs/reference-manual/graalvm-updater.md b/docs/reference-manual/graalvm-updater.md index abf06080ab1a..c13d82d53a2b 100644 --- a/docs/reference-manual/graalvm-updater.md +++ b/docs/reference-manual/graalvm-updater.md @@ -31,16 +31,16 @@ The following GraalVM language runtimes and utilities are available for installa Tools/Utilities: -* [Native Image](/native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable -* [LLVM toolchain](/llvm/README.md) -- a set of tools and APIs for compiling native programs to bitcode that can be executed on GraalVM -* [Java on Truffle](/java-on-truffle/README.md) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Native Image](native-image/README.md) -- a technology to compile an application ahead-of-time into a native executable +* [LLVM toolchain](llvm/README.md) -- a set of tools and APIs for compiling native programs to bitcode that can be executed on GraalVM Runtimes: -* [Node.js](/reference-manual/js/) -- Node.js 14.16.1 compatible -* [Python](/python/README.md) -- Python 3.8.5-compatible -* [Ruby](/ruby/README.md) -- Ruby 2.7.3-compatible -* [R](/r/README.md) -- GNU R 4.0.3-compatible -* [Wasm](/wasm/README.md) -- WebAssembly (Wasm) +* [Java on Truffle](java-on-truffle/README.md) -- a Java Virtual Machine implementation based on a Truffle interpreter for GraalVM +* [Node.js](js/README.md) -- Node.js 14.16.1 compatible +* [Python](python/README.md) -- Python 3.8.5-compatible +* [Ruby](ruby/README.md) -- Ruby 2.7.3-compatible +* [R](r/README.md) -- GNU R 4.0.3-compatible +* [Wasm](wasm/README.md) -- WebAssembly (Wasm) GraalVM Updater verifies whether or not the version of a component is appropriate for the current GraalVM installation. Components are released for each GraalVM distribution with respective updates, and those downloaded for previous release(s) cannot be used with newer ones. @@ -63,21 +63,16 @@ gu available ```shell gu install ruby ``` -GraalVM Updater first downloads the list of components, then uses the -information in the list to download the actual component package, then installs -it. To see more verbose output during the installation, like the download -progress bar, print versions, and dependency information, use the `-v` -(`--verbose`) switch. - -If a component being installed depends on another component, GraalVM Updater will -search the catalog to find an appropriate dependency and install it as well. If -the required components cannot be found, installation will fail. - -When using custom catalog URLs, it is possible, for a convenience, to set -the environment variable `GRAALVM_CATALOG` pointing to the custom catalog's URL. -GraalVM Updater will use the URL defined by `GRAALVM_CATALOG` in preference to -the builtin ones. You may setup the environment variable in startup or profile -scripts. + +GraalVM Updater first downloads the list of components, then uses the information in the list to download the actual component package, then installs it. +To see more verbose output during the installation, like the download progress bar, print versions, and dependency information, use the `-v` (`--verbose`) switch. + +If a component being installed depends on another component, GraalVM Updater will search the catalog to find an appropriate dependency and install it as well. +If the required components cannot be found, installation will fail. + +When using custom catalog URLs, it is possible, for a convenience, to set the environment variable `GRAALVM_CATALOG` pointing to the custom catalog's URL. +GraalVM Updater will use the URL defined by `GRAALVM_CATALOG` in preference to the builtin ones. +You may setup the environment variable in startup or profile scripts. Note: If you need, for some reason to set the `GRAALVM_HOME` environment variable, it may affect `gu` operation. If it is set, it should point to the intended GraalVM installation, same as `JAVA_HOME` and `PATH`. @@ -216,7 +211,7 @@ gu rebuild-images [--verbose] polyglot|libpolyglot|js|llvm|python|ruby [custom n ## GraalVM Updater Commands Overview -Command-line help is available by running `gu` or `gu -h`. Run `gu -h` to get help specific for the particular command. For example, `gu install -h`. +Command-line help is available by running `gu` or `gu -h`. Run `gu -h` to get help specific for the particular command. For example, `gu install -h`. GraalVM Updater usage options: * `gu info [-cClLnprstuvV] `: print the information about specific component (from file, URL, or catalog) @@ -243,9 +238,8 @@ GraalVM Updater common options: * `-v, --verbose`: enable verbose output. Print versions and dependency information * `--version`: print version -Oracle GraalVM Enterprise Edition users might need to pass an -additional verification step to login to the Oracle components repository. GraalVM -Updater tool provides options for that: +Oracle GraalVM Enterprise Edition users might need to pass an additional verification step to login to the Oracle components repository. +GraalVM Updater tool provides options for that: * `--public-key / -k `: set the path to a custom GPG public key path * `--username/-U`: enter a username @@ -260,34 +254,25 @@ Runtime options: ## Configure Proxies -If GraalVM Updater needs to reach the component catalog, or download a component -package, it may need to pass through the HTTP/HTTPS proxy, if the network uses one. On -_macOS_, the proxy settings are automatically obtained from the OS. On _Linux_, -ensure that the `http_proxy` and `https_proxy` environment variables are set -appropriately before launching the `gu` tool. Refer to the distribution -and/or desktop environment documentation for the details. +If GraalVM Updater needs to reach the component catalog, or download a component package, it may need to pass through the HTTP/HTTPS proxy, if the network uses one. +On _macOS_, the proxy settings are automatically obtained from the OS. +On _Linux_, ensure that the `http_proxy` and `https_proxy` environment variables are set appropriately before launching the `gu` tool. +Refer to the distribution and/or desktop environment documentation for the details. -GraalVM Updater intentionally does not support an option to disable certificate -or hostname verification, for security reasons. A user may try to add a proxy's -certificate to the GraalVM default security trust store. A user can also -download a component manually to a folder, and then use `gu -L install /path/to/file` or `gu -C /path/to/download/dir install component` to install from a local filesystem. +GraalVM Updater intentionally does not support an option to disable certificate or hostname verification, for security reasons. +A user may try to add a proxy's certificate to the GraalVM default security trust store. +A user can also download a component manually to a folder, and then use `gu -L install /path/to/file` or `gu -C /path/to/download/dir install component` to install from a local filesystem. ### Working without Internet Access -If your machine cannot access and download the catalog and components from -the Internet, either because it is behind a proxy, or for security reasons, -GraalVM Updater can install components from a local directory, or a directory on -a network share accessible on the target machine. +If your machine cannot access and download the catalog and components from the Internet, either because it is behind a proxy, or for security reasons, +GraalVM Updater can install components from a local directory, or a directory on a network share accessible on the target machine. -You need to prepare a directory, download all components that you want to install -and their dependencies (in case they require other GraalVM components to work) into -that directory. +You need to prepare a directory, download all components that you want to install and their dependencies (in case they require other GraalVM components to work) into that directory. -Then you can use `gu -L install /path/to/file` (where the `-L` option instructs to use local files, -equivalent to `--local-file` or `--file`). Adding the `-D` option will instruct GraalVM Updater -to look for potential dependencies in the directory next to the -installable file. Additionally, `gu -C /path/to/download/dir install component` can be used, with the specified -directory contents acting as a catalog of components. +Then you can use `gu -L install /path/to/file` (where the `-L` option instructs to use local files, equivalent to `--local-file` or `--file`). +Adding the `-D` option will instruct GraalVM Updater to look for potential dependencies in the directory next to the installable file. +Additionally, `gu -C /path/to/download/dir install component` can be used, with the specified directory contents acting as a catalog of components. Note that with `gu -L` you need to specify the component's file name, while when using `gu -C `, the component name must be used: ```shell @@ -300,13 +285,10 @@ gu -C /tmp/instalables install ruby ## Replace Components and Files -A component may be only installed once. GraalVM Updater refuses to install a -component if a component with the same ID is already installed. However, the -installed component can be replaced. GraalVM Updater first uninstalls the -component and then installs a new package. +A component may be only installed once. GraalVM Updater refuses to install a component if a component with the same ID is already installed. +However, the installed component can be replaced. GraalVM Updater first uninstalls the component and then installs a new package. -To replace a component, use the `-r` -option, and the `-L` (`--local-file` or `--file`) option to treat parameters as local filename of a packaged component: +To replace a component, use the `-r` option, and the `-L` (`--local-file` or `--file`) option to treat parameters as local filename of a packaged component: ```shell gu install -L -r component.jar gu install -r ruby @@ -314,18 +296,16 @@ gu install -r ruby The process is the same as if `gu remove` is run first and `gu install` next. -GraalVM Updater also refuses to overwrite existing files if the -to-be-installed and existing versions differ. There are cases when refreshing -file contents may be needed, such as if they were modified or damaged. In this case, use the `-o` option: +GraalVM Updater also refuses to overwrite existing files if the to-be-installed and existing versions differ. +There are cases when refreshing file contents may be needed, such as if they were modified or damaged. +In this case, use the `-o` option: ```shell gu install -L -o component.jar gu install -o ruby ``` -GraalVM Updater will then instruct the user to replace the contained files of a -component. By default, it will not alter anything. Alternatively, use the `-f` -(`--force`) option, which disables most of the checks, and allows the user to -install non-matching versions. +GraalVM Updater will then instruct the user to replace the contained files of a component. +By default, it will not alter anything. Alternatively, use the `-f` (`--force`) option, which disables most of the checks, and allows the user to install non-matching versions. ### Troubleshooting diff --git a/docs/reference-manual/java-on-truffle/Demos.md b/docs/reference-manual/java-on-truffle/Demos.md index 16f73280241d..d3194f58c4f1 100644 --- a/docs/reference-manual/java-on-truffle/Demos.md +++ b/docs/reference-manual/java-on-truffle/Demos.md @@ -131,7 +131,7 @@ GraalVM Native Image technology allows compiling applications ahead-of-time (AOT The main trade off for using Native Image is that the analysis and compilation of your program happens under the closed world assumption, meaning the static analysis needs to process all bytecode which will ever be executed in the application. This makes using some language features like dynamic class loading or reflection tricky. -Java on Truffle is a JVM implementation of a JVM bytecode interpreter, built on the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/). +Java on Truffle is a JVM implementation of a JVM bytecode interpreter, built on the [Truffle framework](../../../truffle/docs/README.md). It is essentially a Java application, as are the Truffle framework itself and the GraalVM JIT compiler. All three of them can be compiled ahead-of-time with `native-image`. Using Java on Truffle for some parts of your application makes it possible to isolate the required dynamic behaviour and still use the native image on the rest of your code. @@ -144,10 +144,9 @@ It is a REPL capable of evaluating Java code and consists of two parts: This design naturally fits the point we are trying to illustrate. We can build a native executable of the JShell's UI part, and make it include Java on Truffle to run the code dynamically specified at run time. Prerequisites: -* [GraalVM 21.0](/downloads/) -* [Native Image](/reference-manual/native-image/#install-native-image) -* [Java on Truffle](/reference-manual/java-on-truffle/#install-java-on-truffle) - +* [GraalVM 21.0](https://www.graalvm.org/downloads/) +* [Native Image](../native-image/README.md#install-native-image) +* [Java on Truffle](README.md#install-java-on-truffle) 1. Clone the [project](https://github.com/graalvm/graalvm-demos) with the demo applications and navigate to the `espresso-jshell` directory: diff --git a/docs/reference-manual/java-on-truffle/FAQ.md b/docs/reference-manual/java-on-truffle/FAQ.md index b54113ff9670..b130e63066e2 100644 --- a/docs/reference-manual/java-on-truffle/FAQ.md +++ b/docs/reference-manual/java-on-truffle/FAQ.md @@ -14,7 +14,7 @@ That means it can only run a Java program once it has been compiled to Java byte In the GraalVM family, this is similar to WebAssembly or the LLVM interpreter: while both can run C programs, they have to be complied by a C compiler first. ### Does Java running on Truffle run on HotSpot too? -Like other languages implemented with the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/), it can run both as a native image or on top of HotSpot. +Like other languages implemented with the [Truffle framework](../../../truffle/docs/README.md), it can run both as a native image or on top of HotSpot. Running on top of HotSpot is currently only possible on Linux. We plan to extend this capability to macOS and Windows platforms also. diff --git a/docs/reference-manual/java-on-truffle/HotSwapPluginAPI.md b/docs/reference-manual/java-on-truffle/HotSwapPluginAPI.md index 55891a5abf89..b2b711290d77 100644 --- a/docs/reference-manual/java-on-truffle/HotSwapPluginAPI.md +++ b/docs/reference-manual/java-on-truffle/HotSwapPluginAPI.md @@ -7,8 +7,8 @@ permalink: /reference-manual/java-on-truffle/hotswap-plugin/ # Truffle on Java HotSwap Plugin API -With Java on Truffle you can benefit from enhanced HotSwap [capabilites](/reference-manual/java-on-truffle/demos/#enhanced-hotswap-capabilities-with-java-on-truffle) that allow the code to evolve naturally during development without the need for restarting a running application. -​ +With Java on Truffle you can benefit from enhanced HotSwap [capabilites](Demos.md#enhanced-hotswap-capabilities-with-java-on-truffle) that allow the code to evolve naturally during development without the need for restarting a running application. + While code reloading (HotSwap) is a powerful tool, it is not sufficient to reflect all kinds of changes, e.g., changes to annotations, framework-specific changes such as implemented services or beans. For these things the code often needs to be executed to reload configurations or contexts before the changes are fully reflected in the running instance. This is where the Truffle on Java HotSwap Plugin API comes in handy. @@ -18,7 +18,7 @@ The main design principle is that you can register various HotSwap listeners tha Examples include the ability to re-run a static initializer, a generic post HotSwap callback and hooks when implementations for a certain service provider changes. ​ **Note**: The HotSwap Plugin API is under development and more fine-grained registration of HotSwap listeners are likely to be added upon requests from the community. -You are welcomed to send enhancement requests to help shape the API through our community support [channels](/community/). +You are welcomed to send enhancement requests to help shape the API through our community support [channels](https://www.graalvm.org/community/). Review the HotSwap Plugin API by going through a running example that will enable more powerful reloading support on [Micronaut](https://micronaut.io/). ​ @@ -138,8 +138,8 @@ Here is a sample application created from the tutorial ["Creating your first Mic Example's sources can be downloaded as a ready-made Gradle project from [here](https://guides.micronaut.io/latest/micronaut-creating-first-graal-app-gradle-java.zip). Download, unzip and open the project in your IDE. -Before you proceed, make sure that you have Java on Truffle [installed](/reference-manual/java-on-truffle/#install-java-on-truffle) and set the GraalVM as the project SDK. -​ +Before you proceed, make sure that you have Java on Truffle [installed](README.md#install-java-on-truffle) and set the GraalVM as the project SDK. + 1. In your IDE navigate to the root `build.gradle` within the sample project. Add: ```groovy diff --git a/docs/reference-manual/java-on-truffle/ImplementationDetails.md b/docs/reference-manual/java-on-truffle/ImplementationDetails.md index 02b49e1b5ae7..866eb7486e3b 100644 --- a/docs/reference-manual/java-on-truffle/ImplementationDetails.md +++ b/docs/reference-manual/java-on-truffle/ImplementationDetails.md @@ -21,7 +21,7 @@ Java on Truffle is a minified Java VM that implements all core components of a V * Java Debug Wire Protocol (JDWP) Java on Truffle reuses all JARs and native libraries from GraalVM. -All native libraries and methods are loaded/accessed/called via [Truffle Native Function Interface (JNI)](https://www.graalvm.org/graalvm-as-a-platform/language-implementation-framework/NFI/). +All native libraries and methods are loaded/accessed/called via [Truffle Native Function Interface (JNI)](../../../truffle/docs/NFI.md). JNI handles are implemented in Java on Truffle, e.g., all Truffle NFI methods only receive and return primitives. Some methods are substituted for performance, e.g., `Math.sqrt`, `System.arraycopy`, avoiding the expensive transition to native. @@ -33,8 +33,8 @@ This mode is not used when running in a native image since there will be no conf * Java on Truffle does not implement the [JVM Tool Interface (JVMTI)](https://docs.oracle.com/en/java/javase/11/docs/specs/jvmti.html). As a result, it does not support the `-agentlib`, or `-agentpath` VM options. * Java on Truffle does not implement the `java.lang.instrument` interface. As a result it does not support the `-javaagent` VM option. -* Java on Truffle currently uses the standard native libraries from the Java core library. This requires allowing a polyglot `Context` native access. Because of the way these libraries are loaded (via [Truffle NFI](https://www.graalvm.org/graalvm-as-a-platform/language-implementation-framework/NFI/)), running on top of HotSpot only works on Linux (with `glibc`). Running as part of a native image works on Linux, Windows, and macOS but it currently limited to one context. +* Java on Truffle currently uses the standard native libraries from the Java core library. This requires allowing a polyglot `Context` native access. Because of the way these libraries are loaded (via [Truffle NFI](../../../truffle/docs/NFI.md)), running on top of HotSpot only works on Linux (with `glibc`). Running as part of a native image works on Linux, Windows, and macOS but it currently limited to one context. * Support for [Java Management Extensions (JMX)](https://docs.oracle.com/javase/tutorial/jmx/index.html) is partial and some methods might return partial data. -* The [Debugger Protocol Implementation (JDWP)](https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdwp-spec.html) lacks some capabilities compared to HotSpot. It will correctly report the supported [capabilities](https://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_Capabilities). In particular actions that require to enumerate all Java objects are not supported. However it does support a few hot reloading cases that HotSpot does not. See [Enhanced HotSwap Capabilities with Java on Truffle](/reference-manual/java-on-truffle/demos/#enhanced-hotswap-capabilities-with-java-on-truffle). +* The [Debugger Protocol Implementation (JDWP)](https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdwp-spec.html) lacks some capabilities compared to HotSpot. It will correctly report the supported [capabilities](https://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_Capabilities). In particular actions that require to enumerate all Java objects are not supported. However it does support a few hot reloading cases that HotSpot does not. See [Enhanced HotSwap Capabilities with Java on Truffle](Demos.md#enhanced-hotswap-capabilities-with-java-on-truffle). * When the `java.MultiThreaded` option is set to "false", [reference processing](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/ref/package-summary.html) will not happen. Depending on the application, this could create resource leaks. Note that this option is set to "false" automatically if Java on Truffle runs in a context where a single-threaded language is enabled (e.g., JavaScript). -* Java on Truffle does not support the [Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) yet. However, it provides a guest Java Polyglot API, described in `polyglot.jar`. For more information, see [Interoperability with Truffle Languages](/reference-manual/java-on-truffle/interoperability/). +* Java on Truffle does not support the [Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) yet. However, it provides a guest Java Polyglot API, described in `polyglot.jar`. For more information, see [Interoperability with Truffle Languages](Interoperability.md). diff --git a/docs/reference-manual/java-on-truffle/Interoperability.md b/docs/reference-manual/java-on-truffle/Interoperability.md index 4c4e24b27587..7551851d064e 100644 --- a/docs/reference-manual/java-on-truffle/Interoperability.md +++ b/docs/reference-manual/java-on-truffle/Interoperability.md @@ -7,7 +7,7 @@ permalink: /reference-manual/java-on-truffle/interoperability/ # Interoperability with Truffle Languages -Java on Truffle allows you to interface other "Truffle" languages (languages which interpreters are implemented with the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/)) to create polyglot programs -- programs written in more than one language. +Java on Truffle allows you to interface other "Truffle" languages (languages which interpreters are implemented with the [Truffle framework](../../../truffle/docs/README.md)) to create polyglot programs -- programs written in more than one language. This guide describes how to load code written in foreign languages, how to export and import objects between languages, how to use Java on Truffle objects from a foreign language, how to use foreign objects from Java on Truffle, and how to embed in host Java. diff --git a/docs/reference-manual/java-on-truffle/README.md b/docs/reference-manual/java-on-truffle/README.md index 6dfe6681fbc4..6576102facb1 100644 --- a/docs/reference-manual/java-on-truffle/README.md +++ b/docs/reference-manual/java-on-truffle/README.md @@ -7,14 +7,14 @@ permalink: /reference-manual/java-on-truffle/ # Java on Truffle -Using GraalVM, you can run Java applications normally [on the JVM](/reference-manual/java/), in [Native Image](/reference-manual/native-image/), and now on Truffle. +Using GraalVM, you can run Java applications normally [on the JVM](../java/README.md), in [Native Image](../native-image/README.md), and now on Truffle. Java on Truffle is an implementation of the Java Virtual Machine Specification, [Java SE 8](https://docs.oracle.com/javase/specs/jvms/se8/html/index.html) and [Java SE 11](https://docs.oracle.com/javase/specs/jvms/se11/html/index.html), built upon GraalVM as a Truffle interpreter. It is a minified Java VM that includes all core components of a VM, implements the same API as the Java Runtime Environment library (libjvm.so), and reuses all JARs and native libraries from GraalVM. -See the [Implementation Details](/reference-manual/java-on-truffle/implementation/) for more information. +See the [Implementation Details](ImplementationDetails.md) for more information. The project name behind this implementation is "Espresso". Its open source version is available on [GitHub](https://github.com/oracle/graal/tree/master/espresso). -The Java on Truffle execution mode runs Java via a Java bytecode interpreter, implemented with the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/) – an open-source library for writing interpreters for programming languages. +The Java on Truffle execution mode runs Java via a Java bytecode interpreter, implemented with the [Truffle framework](../../../truffle/docs/README.md) – an open-source library for writing interpreters for programming languages. Now Java can be executed by the same principle as other languages in the GraalVM ecosystem (JavaScript, Ruby, Python, R), directly interoperate with those languages, and pass data back and forth in the same memory space. Besides complete language interoperability, with Java on Truffle you can: @@ -28,8 +28,8 @@ It is available as of version 21.0.0. ## Install Java on Truffle -To run Java on Truffle, you need to have [GraalVM installed](/docs/getting-started/#install-graalvm). -The Java on Truffle runtime is not available by default, but can be easily added to GraalVM using the [GraalVM Updater tool](/reference-manual/graalvm-updater/). +To run Java on Truffle, you need to have [GraalVM installed](../../getting-started/graalvm-community/get-started-graalvm-community.md). +The Java on Truffle runtime is not available by default, but can be easily added to GraalVM using the [GraalVM Updater tool](../graalvm-updater.md). For GraalVM Community Edition users, run the following command to install Java on Truffle from the GitHub catalog: ```shell @@ -81,7 +81,7 @@ You can still influence the performance by passing the following options to `jav * `--engine.MultiTier=true` to enable multi-tier compilation; * `--engine.Inlining=false` in combination with `--java.InlineFieldAccessors=true` to make the compilation faster, in exchange for slower performance. -The `--vm.XX:` syntax ensures the option is passed to the underlying [native image VM](https://www.graalvm.org/reference-manual/native-image/HostedvsRuntimeOptions). +The `--vm.XX:` syntax ensures the option is passed to the underlying [native image VM](../native-image/HostedvsRuntimeOptions.md). When using the `-XX:` syntax, the VM first checks if there is such an option in the Java on Truffle runtime. If there is none, it will try to apply this option to the underlying native image VM. This might be important for options such as `MaxDirectMemorySize` which can be set independently at both levels: `-XX:MaxDirectMemorySize=256M` controls how much native memory can be reserved by the Java program running on Truffle (the guest VM), while `--vm.XX:MaxDirectMemorySize=256M` controls how much native memory can be reserved by native image (the host VM). @@ -167,11 +167,11 @@ It should show GraalVM as project's JRE and VM options should include `-truffle ## What to Read Next Java on Truffle enables a seamless Java interoperability with other languages in the GraalVM ecosystem. -Check the [Interoperability with Truffle Languages guide](/reference-manual/java-on-truffle/interoperability/) to learn how to load code written in foreign languages, export and import objects between languages, how to use Java-on-Truffle objects from a foreign language and vice versa to create powerful polyglot programs. +Check the [Interoperability with Truffle Languages guide](Interoperability.md) to learn how to load code written in foreign languages, export and import objects between languages, how to use Java-on-Truffle objects from a foreign language and vice versa to create powerful polyglot programs. -To learn about the implementation approach, project's current status, and known limitations proceed to [Implementation Details](/reference-manual/java-on-truffle/implementation/). +To learn about the implementation approach, project's current status, and known limitations proceed to [Implementation Details](ImplementationDetails.md). You can already run some large applications like the Eclipse IDE, Scala or other languages REPLs, etc. in the Java on Truffle execution mode. -We recommend having a look at the collection of [Demo Applications](/reference-manual/java-on-truffle/demos/). +We recommend having a look at the collection of [Demo Applications](Demos.md). -If you have a question, check the available [FAQs](/reference-manual/java-on-truffle/faq/), or reach us directly over the **#espresso** channel in [GraalVM Slack](https://www.graalvm.org/slack-invitation/). +If you have a question, check the available [FAQs](FAQ.md), or reach us directly over the **#espresso** channel in [GraalVM Slack](https://www.graalvm.org/slack-invitation/). diff --git a/docs/reference-manual/llvm/Compatibility.md b/docs/reference-manual/llvm/Compatibility.md index 7f285f5a1331..c2925c1ea2a3 100644 --- a/docs/reference-manual/llvm/Compatibility.md +++ b/docs/reference-manual/llvm/Compatibility.md @@ -11,21 +11,15 @@ It is recommended to use the LLVM toolchain shipped with GraalVM. ## Optimizations Flags -In contrast to the static compilation model of LLVM languages, in GraalVM the -machine code is not directly produced from the LLVM bitcode. There is an -additional dynamic compilation step by the GraalVM compiler. +In contrast to the static compilation model of LLVM languages, in GraalVM the machine code is not directly produced from the LLVM bitcode. +There is an additional dynamic compilation step by the GraalVM compiler. -First, the LLVM frontend (e.g., `clang`) performs optimizations on -the bitcode level, and then the GraalVM compiler does its own optimizations on top of that -during dynamic compilation. Some optimizations are better when done -ahead-of-time on bitcode, while other optimizations are better left for the -dynamic compilation of the GraalVM compiler, when profiling information is available. +First, the LLVM frontend (e.g., `clang`) performs optimizations on the bitcode level, and then the GraalVM compiler does its own optimizations on top of that during dynamic compilation. +Some optimizations are better when done ahead-of-time on bitcode, while other optimizations are better left for the dynamic compilation of the GraalVM compiler, when profiling information is available. -The LLVM toolchain that is shipped with GraalVM automatically selects the -recommended flags by default. +The LLVM toolchain that is shipped with GraalVM automatically selects the recommended flags by default. -Generally, all optimization levels should work, but for a better result, it is -recommended to compile the bitcode with the optimization level `-O1`. +Generally, all optimization levels should work, but for a better result, it is recommended to compile the bitcode with the optimization level `-O1`. For cross-language interoperability, the `-mem2reg` optimization is required. There are two ways to get that: either compile with at least `-O1`, or use the `opt` tool to apply the `-mem2reg` optimization manually. diff --git a/docs/reference-manual/llvm/Compiling.md b/docs/reference-manual/llvm/Compiling.md index 4c7d74b507b1..aed0ad20800c 100644 --- a/docs/reference-manual/llvm/Compiling.md +++ b/docs/reference-manual/llvm/Compiling.md @@ -11,8 +11,7 @@ As the first step, you have to compile a program to LLVM bitcode using some LLVM ## File Format -While the GraalVM LLVM runtime can execute [plain bitcode files](https://llvm.org/docs/BitCodeFormat.html), -the preferred format is a _native executable_ with _embedded bitcode_. +While the GraalVM LLVM runtime can execute [plain bitcode files](https://llvm.org/docs/BitCodeFormat.html), the preferred format is a _native executable_ with _embedded bitcode_. The executable file formats differ on Linux and macOS. Linux by default uses ELF files. The bitcode is stored in a section called `.llvmbc`. @@ -31,13 +30,13 @@ To simplify compiling C/C++ to executables with embedded bitcode, GraalVM comes The toolchain contains compilers such as `clang` for C or `clang++` for C++, but also other tools that are needed for building native projects such as a linker (`ld`), or an archiver (`ar`) for creating static libraries. -The LLVM toolchain can be added to GraalVM on demand with the [GraalVM Updater](https://www.graalvm.org/reference-manual/graalvm-updater) tool: +The LLVM toolchain can be added to GraalVM on demand with the [GraalVM Updater](../graalvm-updater.md) tool: ```shell $GRAALVM_HOME/bin/gu install llvm-toolchain ``` The above command will install the LLVM toolchain from the GitHub catalog for GraalVM Community users. -For GraalVM Enterprise users, the [manual installation](https://www.graalvm.org/reference-manual/graalvm-updater/#manual-installation) is required. +For GraalVM Enterprise users, the [manual installation](../graalvm-updater.md#manual-installation) is required. To get the location of the toolchain, use the `--print-toolchain-path` argument of `lli`: ```shell @@ -71,8 +70,8 @@ $GRAALVM_HOME/bin/lli hello ## External Library Dependencies -If the bitcode file depends on external libraries, GraalVM will automatically -pick up the dependencies from the binary headers. For example: +If the bitcode file depends on external libraries, GraalVM will automatically pick up the dependencies from the binary headers. +For example: ```c #include #include @@ -95,9 +94,9 @@ lli hello-curses ## Running C++ -For running C++ code, the GraalVM LLVM runtime requires the -[`libc++`](https://libcxx.llvm.org) standard library from the LLVM project. The -LLVM toolchain shipped with GraalVM automatically links against `libc++`. For example, save this code as a _hello-c++.cpp_ file: +For running C++ code, the GraalVM LLVM runtime requires the [`libc++`](https://libcxx.llvm.org) standard library from the LLVM project. +The LLVM toolchain shipped with GraalVM automatically links against `libc++`. +For example, save this code as a _hello-c++.cpp_ file: ```c++ #include @@ -115,9 +114,8 @@ Hello, C++ World! ## Running Rust -The LLVM toolchain, bundled with GraalVM, does not come with the Rust -compiler. To install Rust, run the following in your command prompt, then follow the -onscreen instructions: +The LLVM toolchain, bundled with GraalVM, does not come with the Rust compiler. +To install Rust, run the following in your command prompt, then follow the onscreen instructions: ```shell curl https://sh.rustup.rs -sSf | sh ``` @@ -134,32 +132,26 @@ This can be then compiled to bitcode with the `--emit=llvm-bc` flag: rustc --emit=llvm-bc hello-rust.rs ``` -To run the Rust program, we have to tell GraalVM where to find the Rust -standard libraries: +To run the Rust program, we have to tell GraalVM where to find the Rust standard libraries: ```shell lli --lib $(rustc --print sysroot)/lib/libstd-* hello-rust.bc Hello Rust! ``` -Since the Rust compiler is not using the LLVM toolchain shipped with GraalVM, depending on the -local Rust installation, an error similar to one of the following might happen: +Since the Rust compiler is not using the LLVM toolchain shipped with GraalVM, depending on the local Rust installation, an error similar to one of the following might happen: ``` Mismatching target triple (expected x86_64-unknown-linux-gnu, got x86_64-pc-linux-gnu) Mismatching target triple (expected x86_64-apple-macosx10.11.0, got x86_64-apple-darwin) ``` -This indicates that the Rust compiler used a different target triple than the LLVM toolchain -shipped with GraalVM. In this particular case, the differences are just different naming -conventions across Linux distributions or MacOS versions, there is no real difference. +This indicates that the Rust compiler used a different target triple than the LLVM toolchain shipped with GraalVM. +In this particular case, the differences are just different naming conventions across Linux distributions or MacOS versions, there is no real difference. In that case, the error can be safely ignored: ```shell lli --experimental-options --llvm.verifyBitcode=false --lib $(rustc --print sysroot)/lib/libstd-* hello-rust.bc ``` -This option should only be used after manually verifying that the target triples are -really compatible, i.e., the architecture, operating system, and C library all match. -For example, `x86_64-unknown-linux-musl` and `x86_64-unknown-linux-gnu` are really different, -the bitcode is compiled for a different C library. The `--llvm.verifyBitcode=false` option -disables all checks, GraalVM will then try to run the bitcode regardless, which might randomly -fail in unexpected ways. +This option should only be used after manually verifying that the target triples are really compatible, i.e., the architecture, operating system, and C library all match. +For example, `x86_64-unknown-linux-musl` and `x86_64-unknown-linux-gnu` are really different, the bitcode is compiled for a different C library. +The `--llvm.verifyBitcode=false` option disables all checks, GraalVM will then try to run the bitcode regardless, which might randomly fail in unexpected ways. diff --git a/docs/reference-manual/llvm/Debugging.md b/docs/reference-manual/llvm/Debugging.md index 6cd9556f5273..e1ee07053df8 100644 --- a/docs/reference-manual/llvm/Debugging.md +++ b/docs/reference-manual/llvm/Debugging.md @@ -12,9 +12,9 @@ This includes support for single-stepping, breakpoints, and inspection of local To use this feature, make sure to compile your program with debug information enabled by specifying the `-g` argument when compiling with `clang` (the LLVM toolchain shipped with GraalVM will automatically enable debug information). This gives you the ability to step through the program's source code and set breakpoints in it. -With GraalVM 20.0 and older, the option `--llvm.enableLVI=true` is needed for being able to inspect variables during debugging. + To start debugging, run `lli` with the `--inspect` option: ```shell @@ -35,14 +35,13 @@ To instead parse functions eagerly, and be able to set breakpoints also in funct Program-defined breakpoints using the `__builtin_debugtrap` function enables you to mark locations in the program at which you explicitly want GraalVM to halt the program and switch to the debugger. The debugger automatically halts at each call to this function as if a breakpoint were set on the call. You can use this feature to quickly reach the code you are actually trying to debug without having to first find and set a breakpoint on it after launching your application. -You can also instruct Chrome Inspector not to suspend your program at the first source-level statement being executed. When doing so, GraalVM will instead execute your program until it reaches a call to `__builtin_debugtrap()` before invoking the debugger. +You can also instruct Chrome Inspector not to suspend your program at the first source-level statement being executed. +When doing so, GraalVM will instead execute your program until it reaches a call to `__builtin_debugtrap()` before invoking the debugger. To enable this behavior you need to pass the arguments `lli --inspect.Suspend=false --inspect.WaitAttached=true`. ## Locating Source Files -Debug information in LLVM bitcode files contains absolute search paths to identify the -location of source code. If the source files did not move, it should be found automatically. +Debug information in LLVM bitcode files contains absolute search paths to identify the location of source code. +If the source files did not move, it should be found automatically. -If the source files moved, or were compiled on a different machine, a search path can be -specified using the `--inspect.SourcePath=` option (multiple paths can be separated -by `:`). +If the source files moved, or were compiled on a different machine, a search path can be specified using the `--inspect.SourcePath=` option (multiple paths can be separated by `:`). diff --git a/docs/reference-manual/llvm/Interoperability.md b/docs/reference-manual/llvm/Interoperability.md index 7910a0e0b877..620256010620 100644 --- a/docs/reference-manual/llvm/Interoperability.md +++ b/docs/reference-manual/llvm/Interoperability.md @@ -9,13 +9,10 @@ permalink: /reference-manual/llvm/Interoperability/ GraalVM supports several other programming languages including JavaScript, Python, Ruby, and R. While GraalVM's implementation of `lli` is designed to run LLVM bitcode, it also provides the API for programming language interoperability that lets you execute code from any other GraalVM-supported language. -Dynamic languages like JavaScript usually access object members by name. Since -normally names are not preserved in LLVM bitcode, it must be compiled with debug -information enabled (the LLVM toolchain shipped with GraalVM will automatically enable -debugging information). +Dynamic languages like JavaScript usually access object members by name. +Since normally names are not preserved in LLVM bitcode, it must be compiled with debug information enabled (the LLVM toolchain shipped with GraalVM will automatically enable debugging information). -The following example demonstrates how you can use the API for interoperability -with other programming languages. +The following example demonstrates how you can use the API for interoperability with other programming languages. Define a C struct for points and implement allocation functions in a file named _cpart.c_: @@ -52,9 +49,8 @@ void printPoint(struct Point *p) { } ``` -Make sure `LLVM_TOOLCHAIN` resolves to the GraalVM LLVM toolchain (`lli --print-toolchain-path`), -and then compile _cpart.c_ (the graalvm-llvm library defines the polyglot -API functions used in the example): +Make sure `LLVM_TOOLCHAIN` resolves to the GraalVM LLVM toolchain (`lli --print-toolchain-path`), and then compile _cpart.c_ (the graalvm-llvm library defines the Polyglot API functions used in the example): + ```shell $LLVM_TOOLCHAIN/clang -shared cpart.c -lgraalvm-llvm -o cpart.so ``` @@ -104,9 +100,8 @@ Point<17.000000,42.000000> ## Polyglot C API -There are also lower level API functions for directly accessing polyglot values -from C. See the [Polyglot Programming](https://graalvm.org/reference-manual/polyglot-programming/) reference -and the comments in `polyglot.h` for more details. +There are also lower level API functions for directly accessing polyglot values from C. +See the [Polyglot Programming](../polyglot-programming.md) reference and the comments in `polyglot.h` for more details. For example, this program allocates and accesses a Java array from C: ```c @@ -163,5 +158,4 @@ java Polyglot 24 ``` -See the [Embedding Languages](https://graalvm.org/reference-manual/embed-languages/) reference for -more information. +See the [Embedding Languages](../embedding/embed-languages.md) reference for more information. diff --git a/docs/reference-manual/llvm/NativeExecution.md b/docs/reference-manual/llvm/NativeExecution.md index 6171d928ffc6..6892db89e2f7 100644 --- a/docs/reference-manual/llvm/NativeExecution.md +++ b/docs/reference-manual/llvm/NativeExecution.md @@ -12,24 +12,16 @@ The difference lies in safety guarantees and cross-language interoperability. Note: Managed execution mode for LLVM bitcode is possible with GraalVM Enterprise only. -In the default configuration, cross-language interoperability requires bitcode -to be compiled with the debug information enabled (`-g`), and the `-mem2reg` -optimization performed on LLVM bitcode (compiled with at least `-O1`, or -explicitly using the `opt` tool). These requirements can be overcome in a -managed environment of GraalVM Enterprise that allows native code to participate in the -polyglot programs, passing and receiving the data from any other supported -language. In terms of security, the execution of native code in a managed -environment passes with additional safety features: catching illegal pointer -accesses, accessing arrays outside of the bounds, etc. +In the default configuration, cross-language interoperability requires bitcode to be compiled with the debug information enabled (`-g`), and the `-mem2reg` optimization performed on LLVM bitcode (compiled with at least `-O1`, or explicitly using the `opt` tool). +These requirements can be overcome in a managed environment of GraalVM Enterprise that allows native code to participate in the polyglot programs, passing and receiving the data from any other supported language. +In terms of security, the execution of native code in a managed environment passes with additional safety features: catching illegal pointer accesses, accessing arrays outside of the bounds, etc. There are certain limitations and differences to the native execution depending on the GraalVM edition. Consider them respectively. ### Limitations and Differences to Native Execution on Top of GraalVM Community -The LLVM interpreter in GraalVM Community Edition environment allows executing LLVM bitcode within a -multilingual context. Even though it aspires to be a generic LLVM runtime, there -are certain fundamental and/or implementational limitations that users need to -be aware of. +The LLVM interpreter in GraalVM Community Edition environment allows executing LLVM bitcode within a multilingual context. +Even though it aspires to be a generic LLVM runtime, there are certain fundamental and/or implementational limitations that users need to be aware of. The following restrictions and differences to native execution (i.e., bitcode compiled down to native code) exist when LLVM bitcode is executed with the LLVM interpreter on top of GraalVM Community: diff --git a/docs/reference-manual/llvm/README.md b/docs/reference-manual/llvm/README.md index dfcd66c93ff0..5adc7c3c2ca9 100644 --- a/docs/reference-manual/llvm/README.md +++ b/docs/reference-manual/llvm/README.md @@ -14,15 +14,15 @@ This allows seamless interoperability with the dynamic languages supported by Gr ## Running LLVM Bitcode on GraalVM -To run LLVM-based languages on GraalVM, the binaries need to be compiled with embedded -bitcode. The [Compiling](Compiling.md) guide provides information on -how to compile a program to LLVM bitcode and what file format is expected. +To run LLVM-based languages on GraalVM, the binaries need to be compiled with embedded bitcode. +The [Compiling](Compiling.md) guide provides information on how to compile a program to LLVM bitcode and what file format is expected. The syntax to execute programs in LLVM bitcode format on GraalVM is: ```shell lli [LLI options] [GraalVM options] [polyglot options] [program args] ``` -Here, `` is [a compiled program with embedded LLVM bitcode](Compiling.md). See [LLI Command Options](Options.md) or use `lli --help` for options explanations. +Here, `` is [a compiled program with embedded LLVM bitcode](Compiling.md). +See [LLI Command Options](Options.md) or use `lli --help` for options explanations. -Note: LLVM bitcode is platform-dependent. The program must be compiled to -bitcode for an appropriate platform. +Note: LLVM bitcode is platform-dependent. +The program must be compiled to bitcode for an appropriate platform. diff --git a/docs/reference-manual/native-image/Agent.md b/docs/reference-manual/native-image/Agent.md index 1505c516379d..979f0832487d 100644 --- a/docs/reference-manual/native-image/Agent.md +++ b/docs/reference-manual/native-image/Agent.md @@ -72,11 +72,9 @@ public class ReflectionExample { } ``` -This is a simple Java program where non-constant strings for accessing program -elements by name must come as external inputs. The main method invokes a method -of a particular class (`Class.forName`) whose names are passed as command line -arguments. Providing any other class or method name on the command line leads to -an exception. +This is a simple Java program where non-constant strings for accessing program elements by name must come as external inputs. +The main method invokes a method of a particular class (`Class.forName`) whose names are passed as command line arguments. +Providing any other class or method name on the command line leads to an exception. Having compiled the example, invoke each method: ```shell @@ -94,10 +92,7 @@ $JAVA_HOME/bin/native-image ReflectionExample ... ./reflectionexample ``` -The `reflectionexample` binary is just a launcher for the JVM. To -build a native image with reflective lookup operations, apply the tracing -agent to write a configuration file to be later fed into the native image -build together. +The `reflectionexample` binary is just a launcher for the JVM. To build a native image with reflective lookup operations, apply the tracing agent to write a configuration file to be later fed into the native image build together. 1. Create a directory `META-INF/native-image` in the working directory: ```shell @@ -108,17 +103,16 @@ mkdir -p META-INF/native-image ```shell $JAVA_HOME/bin/java -agentlib:native-image-agent=config-output-dir=META-INF/native-image ReflectionExample StringReverser reverse "hello" ``` -This command creates a _reflection-config.json_ file which makes the `StringReverser` class and the `reverse()` method accessible via reflection. The _jni-config.json_, _proxy-config.json_ , and _resource-config.json_ configuration files are written in that directory too. +This command creates a _reflection-config.json_ file which makes the `StringReverser` class and the `reverse()` method accessible via reflection. +The _jni-config.json_, _proxy-config.json_ , and _resource-config.json_ configuration files are written in that directory too. 3. Build a native image: ```shell $JAVA_HOME/bin/native-image --no-fallback ReflectionExample ``` -The native image builder automatically picks up configuration files in the -_META-INF/native-image_ directory or subdirectories. However, it is recommended -to have _META-INF/native-image_ location on the class path, either via a JAR -file or via the `-cp` flag. It will help to avoid confusion for IDE users where a -directory structure is defined by the tool. +The native image builder automatically picks up configuration files in the _META-INF/native-image_ directory or subdirectories. +However, it is recommended to have _META-INF/native-image_ location on the class path, either via a JAR file or via the `-cp` flag. +It will help to avoid confusion for IDE users where a directory structure is defined by the tool. 4. Test the methods, but remember that you have not run the tracing agent twice to create a configuration that supports both: ```shell @@ -131,20 +125,15 @@ Exception in thread "main" java.lang.ClassNotFoundException: StringCapitalizer at ReflectionExample.main(ReflectionExample.java:21) ``` -Neither the tracing agent nor native images generator can automatically check -if the provided configuration files are complete. The agent only observes and -records which values are accessed through reflection so that the same accesses -are possible in a native image. You can either manually edit the -_reflection-config.json_ file, or re-run the tracing agent to transform the -existing configuration file, or extend it by using `config-merge-dir` option: +Neither the tracing agent nor native images generator can automatically check if the provided configuration files are complete. +The agent only observes and records which values are accessed through reflection so that the same accesses are possible in a native image. +You can either manually edit the _reflection-config.json_ file, or re-run the tracing agent to transform the existing configuration file, or extend it by using `config-merge-dir` option: ```shell $JAVA_HOME/bin/java -agentlib:native-image-agent=config-merge-dir=META-INF/native-image ReflectionExample StringCapitalizer capitalize "hello" ``` -Note, the different `config-merge-dir` option instructs the agent to extend the -existing configuration files instead of overwriting them. After re-building the -native image, the `StringCapitalizer` class and the `capitalize` method will be -accessible too. +Note, the different `config-merge-dir` option instructs the agent to extend the existing configuration files instead of overwriting them. +After re-building the native image, the `StringCapitalizer` class and the `capitalize` method will be accessible too. ![](/img/reflect_config_file_merged.png) @@ -152,9 +141,13 @@ accessible too. ### Caller-based Filters -By default, the agent filters dynamic accesses which Native Image supports without configuration. The filter mechanism works by identifying the Java method performing the access, also referred to as _caller_ method, and matching its declaring class against a sequence of filter rules. The built-in filter rules exclude dynamic accesses which originate in the JVM, or in parts of a Java class library directly supported by Native Image (such as `java.nio`) from the generated configuration files. Which item (class, method, field, resource, etc.) is being accessed is not relevant for filtering. +By default, the agent filters dynamic accesses which Native Image supports without configuration. +The filter mechanism works by identifying the Java method performing the access, also referred to as _caller_ method, and matching its declaring class against a sequence of filter rules. +The built-in filter rules exclude dynamic accesses which originate in the JVM, or in parts of a Java class library directly supported by Native Image (such as `java.nio`) from the generated configuration files. +Which item (class, method, field, resource, etc.) is being accessed is not relevant for filtering. -In addition to the built-in filter, custom filter files with additional rules can be specified using the `caller-filter-file` option. For example: `-agentlib:caller-filter-file=/path/to/filter-file,config-output-dir=...` +In addition to the built-in filter, custom filter files with additional rules can be specified using the `caller-filter-file` option. +For example: `-agentlib:caller-filter-file=/path/to/filter-file,config-output-dir=...` Filter files have the following structure: ```json @@ -166,53 +159,80 @@ Filter files have the following structure: } ``` -The `rules` section contains a sequence of rules. Each rule specifies either `includeClasses`, which means that lookups originating in matching classes will be included in the resulting configuration, or `excludeClasses`, which excludes lookups originating in matching classes from the configuration. Each rule defines a pattern for the set of matching classes, which can end in `.*` or `.**`: a `.*` ending matches all classes in a package and that package only, while a `.**` ending matches all classes in the package as well as in all subpackages at any depth. Without `.*` or `.**`, the rule applies only to a single class with the qualified name that matches the pattern. All rules are processed in the sequence in which they are specified, so later rules can partially or entirely override earlier ones. When multiple filter files are provided (by specifying multiple `caller-filter-file` options), their rules are chained together in the order in which the files are specified. The rules of the built-in caller filter are always processed first, so they can be overridden in custom filter files. +TThe `rules` section contains a sequence of rules. +Each rule specifies either `includeClasses`, which means that lookups originating in matching classes will be included in the resulting configuration, or `excludeClasses`, which excludes lookups originating in matching classes from the configuration. +Each rule defines a pattern for the set of matching classes, which can end in `.*` or `.**`: a `.*` ending matches all classes in a package and that package only, while a `.**` ending matches all classes in the package as well as in all subpackages at any depth. Without `.*` or `.**`, the rule applies only to a single class with the qualified name that matches the pattern. +All rules are processed in the sequence in which they are specified, so later rules can partially or entirely override earlier ones. +When multiple filter files are provided (by specifying multiple `caller-filter-file` options), their rules are chained together in the order in which the files are specified. +The rules of the built-in caller filter are always processed first, so they can be overridden in custom filter files. -In the example above, the first rule excludes lookups originating in all classes from package `com.oracle.svm` and from all of its subpackages (and their subpackages, etc.) from the generated configuration. In the next rule however, lookups from those classes that are directly in package `com.oracle.svm.tutorial` are included again. Finally, lookups from the `HostedHelper` class is excluded again. Each of these rules partially overrides the previous ones. For example, if the rules were in the reverse order, the exclusion of `com.oracle.svm.**` would be the last rule and would override all other rules. +In the example above, the first rule excludes lookups originating in all classes from package `com.oracle.svm` and from all of its subpackages (and their subpackages, etc.) from the generated configuration. +In the next rule however, lookups from those classes that are directly in package `com.oracle.svm.tutorial` are included again. +Finally, lookups from the `HostedHelper` class is excluded again. Each of these rules partially overrides the previous ones. +For example, if the rules were in the reverse order, the exclusion of `com.oracle.svm.**` would be the last rule and would override all other rules. -For testing purposes, the built-in filter for Java class library lookups can be disabled by adding the `no-builtin-caller-filter` option, but the resulting configuration files are generally unsuitable for a native image build. Similarly, the built-in filter for Java VM-internal accesses based on heuristics can be disabled with `no-builtin-heuristic-filter` and will also generally lead to less usable configuration files. For example: `-agentlib:native-image-agent=no-builtin-caller-filter,no-builtin-heuristic-filter,config-output-dir=...` +For testing purposes, the built-in filter for Java class library lookups can be disabled by adding the `no-builtin-caller-filter` option, but the resulting configuration files are generally unsuitable for a native image build. +Similarly, the built-in filter for Java VM-internal accesses based on heuristics can be disabled with `no-builtin-heuristic-filter` and will also generally lead to less usable configuration files. +For example: `-agentlib:native-image-agent=no-builtin-caller-filter,no-builtin-heuristic-filter,config-output-dir=...` ### Access Filters -Unlike the caller-based filters described above, which filter dynamic accesses based on where they originate from, _access filters_ apply to the _target_ of the access. Therefore, access filters enable directly excluding packages and classes (and their members) from the generated configuration. +Unlike the caller-based filters described above, which filter dynamic accesses based on where they originate from, _access filters_ apply to the _target_ of the access. +Therefore, access filters enable directly excluding packages and classes (and their members) from the generated configuration. -By default, all accessed classes (which also pass the caller-based filters and the built-in filters) are included in the generated configuration. Using the `access-filter-file` option, a custom filter file that follows the file structure described above can be added. The option can be specified more than once to add multiple filter files and can be combined with the other filter options. For example: `-agentlib:access-filter-file=/path/to/access-filter-file,caller-filter-file=/path/to/caller-filter-file,config-output-dir=...` +By default, all accessed classes (which also pass the caller-based filters and the built-in filters) are included in the generated configuration. +Using the `access-filter-file` option, a custom filter file that follows the file structure described above can be added. +The option can be specified more than once to add multiple filter files and can be combined with the other filter options. +For example: `-agentlib:access-filter-file=/path/to/access-filter-file,caller-filter-file=/path/to/caller-filter-file,config-output-dir=...` ### Specifying Configuration Files as Native Image Arguments -A directory containing configuration files that is not part of the class path can be specified to `native-image` via `-H:ConfigurationFileDirectories=/path/to/config-dir/`. This directory must directly contain all four files: `jni-config.json`, `reflect-config.json`, `proxy-config.json` and `resource-config.json`. A directory with the same four configuration files that is on the class path, but not in `META-INF/native-image/`, can be provided via `-H:ConfigurationResourceRoots=path/to/resources/`. Both `-H:ConfigurationFileDirectories` and `-H:ConfigurationResourceRoots` can also take a comma-separated list of directories. +A directory containing configuration files that is not part of the class path can be specified to `native-image` via `-H:ConfigurationFileDirectories=/path/to/config-dir/`. +This directory must directly contain all four files: `jni-config.json`, `reflect-config.json`, `proxy-config.json` and `resource-config.json`. +A directory with the same four configuration files that is on the class path, but not in `META-INF/native-image/`, can be provided via `-H:ConfigurationResourceRoots=path/to/resources/`. +Both `-H:ConfigurationFileDirectories` and `-H:ConfigurationResourceRoots` can also take a comma-separated list of directories. ### Injecting the Agent via the Process Environment -Altering the `java` command line to inject the agent can prove to be difficult if the Java process is launched by an application or script file, or if Java is even embedded in an existing process. In that case, it is also possible to inject the agent via the `JAVA_TOOL_OPTIONS` environment variable. This environment variable can be picked up by multiple Java processes which run at the same time, in which case each agent must write to a separate output directory with `config-output-dir`. (The next section describes how to merge sets of configuration files.) In order to use separate paths with a single global `JAVA_TOOL_OPTIONS` variable, the agent's output path options support placeholders: +Altering the `java` command line to inject the agent can prove to be difficult if the Java process is launched by an application or script file, or if Java is even embedded in an existing process. +In that case, it is also possible to inject the agent via the `JAVA_TOOL_OPTIONS` environment variable. +This environment variable can be picked up by multiple Java processes which run at the same time, in which case each agent must write to a separate output directory with `config-output-dir`. +(The next section describes how to merge sets of configuration files.) +In order to use separate paths with a single global `JAVA_TOOL_OPTIONS` variable, the agent's output path options support placeholders: ```shell export JAVA_TOOL_OPTIONS="-agentlib:native-image-agent=config-output-dir=/path/to/config-output-dir-{pid}-{datetime}/" ``` -The `{pid}` placeholder is replaced with the process identifier, while `{datetime}` is replaced with the system date and time in UTC, formatted according to ISO 8601. For the above example, the resulting path could be: `/path/to/config-output-dir-31415-20181231T235950Z/`. +The `{pid}` placeholder is replaced with the process identifier, while `{datetime}` is replaced with the system date and time in UTC, formatted according to ISO 8601. +For the above example, the resulting path could be: `/path/to/config-output-dir-31415-20181231T235950Z/`. ### Trace Files -In the examples above, `native-image-agent` has been used to both keep track of the dynamic accesses in a Java VM and then to generate a set of configuration files from them. However, for a better understanding of the execution, the agent can also write a _trace file_ in JSON format that contains each individual access: +In the examples above, `native-image-agent` has been used to both keep track of the dynamic accesses in a Java VM and then to generate a set of configuration files from them. +However, for a better understanding of the execution, the agent can also write a _trace file_ in JSON format that contains each individual access: ```shell $JAVA_HOME/bin/java -agentlib:native-image-agent=trace-output=/path/to/trace-file.json ... ``` -The `native-image-configure` tool can transform trace files to configuration files that can be used in native image builds. The following command reads and processes `trace-file.json` and generates a set of configuration files in directory `/path/to/config-dir/`: +The `native-image-configure` tool can transform trace files to configuration files that can be used in native image builds. +The following command reads and processes `trace-file.json` and generates a set of configuration files in directory `/path/to/config-dir/`: ```shell native-image-configure generate --trace-input=/path/to/trace-file.json --output-dir=/path/to/config-dir/ ``` ### Interoperability -Although the agent is distributed with GraalVM, it uses the JVM Tool Interface (JVMTI) and can potentially be used with other JVMs that support JVMTI. In this case, it is necessary to provide the absolute path of the agent: +Although the agent is distributed with GraalVM, it uses the JVM Tool Interface (JVMTI) and can potentially be used with other JVMs that support JVMTI. +In this case, it is necessary to provide the absolute path of the agent: ```shell /path/to/some/java -agentpath:/path/to/graalvm/jre/lib/amd64/libnative-image-agent.so= ... ``` ### Native Image Configure Tool -When using the agent in multiple processes at the same time as described in the previous section, `config-output-dir` is a safe option, but results in multiple sets of configuration files. The `native-image-configure-launcher` tool can be used to merge these configuration files. This tool must first be built with: +When using the agent in multiple processes at the same time as described in the previous section, `config-output-dir` is a safe option, but results in multiple sets of configuration files. The `native-image-configure-launcher` tool can be used to merge these configuration files. +This tool must first be built with: + ```shell native-image --macro:native-image-configure-launcher ``` diff --git a/docs/reference-manual/native-image/BuildConfiguration.md b/docs/reference-manual/native-image/BuildConfiguration.md index d7718abb2707..60303172d45b 100644 --- a/docs/reference-manual/native-image/BuildConfiguration.md +++ b/docs/reference-manual/native-image/BuildConfiguration.md @@ -18,22 +18,17 @@ Native Image supports a wide range of options to configure a native image build ## Embedding a Configuration File -A recommended way to provide configuration is to embed a -**native-image.properties** file into a project JAR file. The Native Image builder -will automatically pick up all configuration options provided anywhere below the -resource location `META-INF/native-image/` and use it to construct -`native-image` command line arguments. - -To avoid a situation when constituent parts of a project are built -with overlapping configurations, it is recommended to use "subdirectories" within -`META-INF/native-image`. That way a JAR file built from multiple maven projects -cannot suffer from overlapping `native-image` configurations. For example: +A recommended way to provide configuration is to embed a **native-image.properties** file into a project JAR file. +The Native Image builder will automatically pick up all configuration options provided anywhere below the resource location `META-INF/native-image/` and use it to construct `native-image` command line arguments. + +To avoid a situation when constituent parts of a project are built with overlapping configurations, it is recommended to use "subdirectories" within `META-INF/native-image`. +That way a JAR file built from multiple maven projects cannot suffer from overlapping `native-image` configurations. +For example: * _foo.jar_ has its configurations in `META-INF/native-image/foo_groupID/foo_artifactID` * _bar.jar_ has its configurations in `META-INF/native-image/bar_groupID/bar_artifactID` -The JAR file that contains `foo` and `bar` will then contain both configurations -without conflicting with one another. Therefore the recommended layout for -storing native image configuration data in JAR files is the following: +The JAR file that contains `foo` and `bar` will then contain both configurations without conflicting with one another. +Therefore the recommended layout for storing native image configuration data in JAR files is the following: ``` META-INF/ └── native-image @@ -42,12 +37,9 @@ META-INF/ └── native-image.properties ``` -Note that the use of `${.}` in a _native-image.properties_ file expands to the -resource location that contains that exact configuration file. This can be -useful if the _native-image.properties_ file wants to refer to resources within -its "subfolder", for example, `-H:SubstitutionResources=${.}/substitutions.json`. -Always make sure to use the option variants that take resources, i.e., use -`-H:ResourceConfigurationResources` instead of `-H:ResourceConfigurationFiles`. +Note that the use of `${.}` in a _native-image.properties_ file expands to the resource location that contains that exact configuration file. +This can be useful if the _native-image.properties_ file wants to refer to resources within its "subfolder", for example, `-H:SubstitutionResources=${.}/substitutions.json`. +Always make sure to use the option variants that take resources, i.e., use `-H:ResourceConfigurationResources` instead of `-H:ResourceConfigurationFiles`. Other options that are known to work in this context are: * `-H:DynamicProxyConfigurationResources` * `-H:JNIConfigurationResources` @@ -56,16 +48,14 @@ Other options that are known to work in this context are: * `-H:SubstitutionResources` * `-H:SerializationConfigurationResources` -By having such a composable _native-image.properties_ file, building an image -does not require any additional arguments specified on command line. It is -sufficient to just run the following command: +By having such a composable _native-image.properties_ file, building an image does not require any additional arguments specified on command line. +It is sufficient to just run the following command: ```shell $JAVA_HOME/bin/native-image -jar target/.jar ``` -To debug which configuration data gets applied for the image building, use `native-image --verbose`. This will show from where `native-image` picks up the -configurations to construct the final composite configuration command line -options for the native image builder. +To debug which configuration data gets applied for the image building, use `native-image --verbose`. +This will show from where `native-image` picks up the configurations to construct the final composite configuration command line options for the native image builder. ```shell native-image --verbose -jar build/basic-app-0.1-all.jar Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/common/native-image.properties @@ -89,44 +79,38 @@ supported. **Args** -Use this property if your project requires custom `native-image` command line options to build correctly. For example, the `native-image-configure-examples/configure-at-runtime-example` has `Args = --initialize-at-build-time=com.fasterxml.jackson.annotation.JsonProperty$Access` in its `native-image.properties` file to ensure the class `com.fasterxml.jackson.annotation.JsonProperty$Access` gets initialized at image build time. +Use this property if your project requires custom `native-image` command line options to build correctly. +For example, the `native-image-configure-examples/configure-at-runtime-example` has `Args = --initialize-at-build-time=com.fasterxml.jackson.annotation.JsonProperty$Access` in its `native-image.properties` file to ensure the class `com.fasterxml.jackson.annotation.JsonProperty$Access` gets initialized at image build time. **JavaArgs** -Sometimes it can be necessary to provide custom options to the JVM that runs the -native image builder. The `JavaArgs` property can be used in this case. +Sometimes it can be necessary to provide custom options to the JVM that runs the native image builder. +The `JavaArgs` property can be used in this case. **ImageName** -This property can be used to specify a user-defined name for the image. If -`ImageName` is not used, a name gets automatically chosen: +This property can be used to specify a user-defined name for the image. +If `ImageName` is not used, a name gets automatically chosen: * `native-image -jar ` has a default image name `` * `native-image -cp ... fully.qualified.MainClass` has a default image name `fully.qualified.mainclass` -Note that using `ImageName` does not prevent the user to override the name later via command line. For example, if `foo.bar` contains `ImageName=foo_app`: +Note that using `ImageName` does not prevent the user to override the name later via command line. +For example, if `foo.bar` contains `ImageName=foo_app`: * `native-image -jar foo.bar` generates the image `foo_app` but * `native-image -jar foo.bar application` generates the image `application` ### Order of Arguments Evaluation -The arguments passed to `native-image` are evaluated left-to-right. This also -extends to arguments that get passed indirectly via `META-INF/native-image` -based native image configuration. Suppose you have a JAR file that contains -_native-image.properties_ with `Args = -H:Optimize=0`. Then by using the -`-H:Optimize=2` option after `-cp ` you can override the setting that -comes from the JAR file. +The arguments passed to `native-image` are evaluated left-to-right. +This also extends to arguments that get passed indirectly via `META-INF/native-image` based native image configuration. +Suppose you have a JAR file that contains _native-image.properties_ with `Args = -H:Optimize=0`. +Then by using the `-H:Optimize=2` option after `-cp ` you can override the setting that comes from the JAR file. ### Specifying Default Options for Native Image -If there is a need to pass some options for every image build unconditionally, for -example, to always generate an image in verbose mode (`--verbose`), you can -make use of the `NATIVE_IMAGE_CONFIG_FILE` environment variable. -If it is set to a Java properties file, the Native Image builder will use the -default setting defined in there on each invocation. Write a -configuration file and export -`NATIVE_IMAGE_CONFIG_FILE=$HOME/.native-image/default.properties` in -`~/.bash_profile`. Every time `native-image` gets used, it will implicitly use -the arguments specified as `NativeImageArgs`, plus the arguments specified on the -command line. Here is an example of a configuration file, saved as -`~/.native-image/default.properties`: +If there is a need to pass some options for every image build unconditionally, for example, to always generate an image in verbose mode (`--verbose`), you can make use of the `NATIVE_IMAGE_CONFIG_FILE` environment variable. +If it is set to a Java properties file, the Native Image builder will use the default setting defined in there on each invocation. +Write a configuration file and export `NATIVE_IMAGE_CONFIG_FILE=$HOME/.native-image/default.properties` in `~/.bash_profile`. +Every time `native-image` gets used, it will implicitly use the arguments specified as `NativeImageArgs`, plus the arguments specified on the command line. +Here is an example of a configuration file, saved as `~/.native-image/default.properties`: ``` NativeImageArgs = --configurations-path /home/user/custom-image-configs \ @@ -146,9 +130,9 @@ export NATIVE_IMAGE_USER_HOME= $HOME/.local/share/native-image The native image build runs on the Java HotSpot VM and uses the memory management of the underlying platform. The usual Java HotSpot command-line options for garbage collection apply to the native image builder. -During the native image build, the representation of a whole program is created to -figure out which classes and methods will be used at run time. It is a -computationally intensive process. The default values for memory usage at image build time are: +During the native image build, the representation of a whole program is created to figure out which classes and methods will be used at run time. +It is a computationally intensive process. +The default values for memory usage at image build time are: ``` -Xss10M \ -Xms1G \ @@ -164,21 +148,16 @@ Check other related options to the native image builder from the `native-image - ## Runtime vs Build-Time Initialization -Building your application into a native image allows you to decide which parts -of your application should be run at image build time and which parts have to -run at image run time. +Building your application into a native image allows you to decide which parts of your application should be run at image build time and which parts have to run at image run time. -All class-initialization code (static initializers and static -field initialization) of the application you build an image for is executed -at image run time by default. Sometimes it is beneficial to allow class -initialization code to get executed at image build time for faster startup (e.g., -if some static fields get initialized to run-time independent data). This can be -controlled with the following `native-image` options: +All class-initialization code (static initializers and static field initialization) of the application you build an image for is executed at image run time by default. +Sometimes it is beneficial to allow class initialization code to get executed at image build time for faster startup (e.g., if some static fields get initialized to run-time independent data). +This can be controlled with the following `native-image` options: * `--initialize-at-build-time=` * `--initialize-at-run-time=` -In addition to that, arbitrary computations are allowed at build time that can be put into `ImageSingletons` that are -accessible at image run time. For more information please have a look at [Native Image configuration examples](https://github.com/graalvm/graalvm-demos/tree/master/native-image-configure-examples). +In addition to that, arbitrary computations are allowed at build time that can be put into `ImageSingletons` that are accessible at image run time. +For more information please have a look at [Native Image configuration examples](https://github.com/graalvm/graalvm-demos/tree/master/native-image-configure-examples). For more information, continue reading to the [Class Initialization in Native Image](ClassInitialization.md) guide. diff --git a/docs/reference-manual/native-image/C-API.md b/docs/reference-manual/native-image/C-API.md index d662844d550e..a0611d270dfb 100644 --- a/docs/reference-manual/native-image/C-API.md +++ b/docs/reference-manual/native-image/C-API.md @@ -79,6 +79,4 @@ int graal_detach_thread(graal_isolatethread_t* thread); */ int graal_tear_down_isolate(graal_isolatethread_t* thread); ``` -In addition to the C level API, there is also a way to initialize an isolate -from Java and thus use Java and Native Image to -[implement native methods in Java](ImplementingNativeMethodsInJavaWithSVM.md). +In addition to the C level API, there is also a way to initialize an isolate from Java and thus use Java and Native Image to [implement native methods in Java](ImplementingNativeMethodsInJavaWithSVM.md). diff --git a/docs/reference-manual/native-image/ClassInitialization.md b/docs/reference-manual/native-image/ClassInitialization.md index 5b457b014fca..cab5aa3d9f69 100644 --- a/docs/reference-manual/native-image/ClassInitialization.md +++ b/docs/reference-manual/native-image/ClassInitialization.md @@ -19,7 +19,8 @@ Access to the static fields that were initialized at build time is transparent t Specifying class initialization policies can be complicated due to the following constraints that come from class initialization semantics: * When a class is initialized, all super classes and super interfaces with default methods must also be initialized. -Interfaces without default methods, however, are not initialized. To describe this, a short-term "relevant supertype" is used furhter, and a relevant subtype for subtypes of classes and interfaces with default methods. +Interfaces without default methods, however, are not initialized. +To describe this, a short-term "relevant supertype" is used furhter, and a relevant subtype for subtypes of classes and interfaces with default methods. * Relevant supertypes of types initialized at build time must also be initialized at build time. * Relevant subtypes of types initialized at run time must also be initialized at run time. * No instances classes that are initialized at run time must be present in the image. @@ -31,7 +32,8 @@ To enjoy the complete out-of-the-box experience of Native Image and still get th * [Explicitly Specifying Class Initialization](#explicitly-specifying-class-initialization) To track which classes were initialized and why, one can use the flag `-H:+PrintClassInitialization`. -This flag greatly helps to configure the image build to work as intended. The goal is to have as many classes as possible initialized at build time, yet keep the correct semantics of the program. +This flag greatly helps to configure the image build to work as intended. +The goal is to have as many classes as possible initialized at build time, yet keep the correct semantics of the program. ## Build-Time Initialization of Native Image Runtime diff --git a/docs/reference-manual/native-image/DynamicProxy.md b/docs/reference-manual/native-image/DynamicProxy.md index c56dadc05175..1c81eb53a69d 100644 --- a/docs/reference-manual/native-image/DynamicProxy.md +++ b/docs/reference-manual/native-image/DynamicProxy.md @@ -16,7 +16,8 @@ See also the [guide on assisted configuration of Java resources and other dynami ## Automatic Detection -Native Image employs a simple static analysis that detects calls to `java.lang.reflect.Proxy.newProxyInstance(ClassLoader, Class[], InvocationHandler)` and `java.lang.reflect.Proxy.getProxyClass(ClassLoader, Class[])`, then tries to determine the list of interfaces that define dynamic proxies automatically. Given the list of interfaces, Native Image generates proxy classes at image build time and adds them to the native image heap. +Native Image employs a simple static analysis that detects calls to `java.lang.reflect.Proxy.newProxyInstance(ClassLoader, Class[], InvocationHandler)` and `java.lang.reflect.Proxy.getProxyClass(ClassLoader, Class[])`, then tries to determine the list of interfaces that define dynamic proxies automatically. +Given the list of interfaces, Native Image generates proxy classes at image build time and adds them to the native image heap. In addition to generating the dynamic proxy class, the constructor of the generated class that takes a `java.lang.reflect.InvocationHandler` argument, i.e., the one reflectively invoked by `java.lang.reflect.Proxy.newProxyInstance(ClassLoader, Class[], InvocationHandler)`, is registered for reflection so that dynamic proxy instances can be allocated at run time. The analysis is limited to situations where the list of interfaces comes from a constant array or an array that is allocated in the same method. diff --git a/docs/reference-manual/native-image/HostedvsRuntimeOptions.md b/docs/reference-manual/native-image/HostedvsRuntimeOptions.md index 1c15425aa568..ff7cc594ed1e 100644 --- a/docs/reference-manual/native-image/HostedvsRuntimeOptions.md +++ b/docs/reference-manual/native-image/HostedvsRuntimeOptions.md @@ -6,8 +6,7 @@ permalink: /reference-manual/native-image/HostedvsRuntimeOptions/ --- # Native Image Hosted and Runtime Options -Along with all the options listed in the [Options](Options.md) -guide, Native Image also distinguishes hosted and runtime options. +Along with all the options listed in the [Options](Options.md) guide, Native Image also distinguishes hosted and runtime options. * Hosted options: configure a native image build, i.e., influence what is put into the image and how the image is built. These are set using the prefix `-H:` on the command line. @@ -19,15 +18,10 @@ For developer documentation on how to define and use options, read the documenta ## List of Useful Options ### Graph Dumping -Native Image re-used the GraalVM options for graph dumping, logging, counters, -and everything else in the GraalVM debug environment. These GraalVM options can -be used both as hosted options (if you want to dump graphs of the native image -builder), and as runtime options (if you want to dump graphs during dynamic -compilation at runtime). - -The GraalVM compiler options that work as expected include `Dump`, `DumpOnError`, `Log`, -`MethodFilter`, and the options to specify file names and ports for the dump -handlers. +Native Image re-used the GraalVM options for graph dumping, logging, counters, and everything else in the GraalVM debug environment. +These GraalVM options can be used both as hosted options (if you want to dump graphs of the native image builder), and as runtime options (if you want to dump graphs during dynamic compilation at runtime). + +The GraalVM compiler options that work as expected include `Dump`, `DumpOnError`, `Log`, `MethodFilter`, and the options to specify file names and ports for the dump handlers. For example: * To dump the compiler graphs of the native image builder: `-H:Dump= -H:MethodFilter=ClassName.MethodName`. diff --git a/docs/reference-manual/native-image/ImplementingNativeMethodsInJavaWithSVM.md b/docs/reference-manual/native-image/ImplementingNativeMethodsInJavaWithSVM.md index d5bf3ac44288..89f20feb3201 100644 --- a/docs/reference-manual/native-image/ImplementingNativeMethodsInJavaWithSVM.md +++ b/docs/reference-manual/native-image/ImplementingNativeMethodsInJavaWithSVM.md @@ -6,20 +6,15 @@ permalink: /reference-manual/native-image/ImplementingNativeMethodsInJavaWithSVM --- # Implementing Native Methods in Java with Native Image -Native Image can be used to implement low-level system operations in Java and -make them available via JNI to Java code executing on a standard JVM. As -a result one can use the same language to write the application logic -as well as the system calls. +Native Image can be used to implement low-level system operations in Java and make them available via JNI to Java code executing on a standard JVM. +As a result one can use the same language to write the application logic as well as the system calls. -Note that this document describes the opposite of what is commonly done via JNI: -usually low-level system operations are implemented in C and invoked from Java -using JNI. If you are interested in how Native Image supports the common use case, -continue reading to the [Native Image JNI support](JNI.md) guide instead. +Note that this document describes the opposite of what is commonly done via JNI: usually low-level system operations are implemented in C and invoked from Java using JNI. +If you are interested in how Native Image supports the common use case, continue reading to the [Native Image JNI support](JNI.md) guide instead. ## Create a Shared Library -First of all one has to use the `native-image` builder to generate a shared library -with some JNI-compatible [entry points](README.md#build-a-shared-library). +First of all one has to use the `native-image` builder to generate a shared library with some JNI-compatible [entry points](README.md#build-a-shared-library). Start with the Java code: ```java package org.pkg.implnative; @@ -34,20 +29,15 @@ public final class NativeImpl { } } ``` -After being processed by the `native-image` builder, the code -[exposes a C function](C-API.md) `Java_org_pkg_apinative_Native_add` -(the name follows conventions of JNI that will be handy later) and -a Native Image signature typical for JNI methods. The first parameter -is a reference to the `JNIEnv*` value. The second parameter is a reference -to the `jclass` value for the class declaring the method. The third parameter is a -portable (e.g., `long`) identifier of the [Native Image isolatethread](C-API.md). -The rest of the parameters are the actual parameters of the Java `Native.add` -method described in the next section. Compile the code with the `--shared` option: +After being processed by the `native-image` builder, the code [exposes a C function](C-API.md) `Java_org_pkg_apinative_Native_add` (the name follows conventions of JNI that will be handy later) and a Native Image signature typical for JNI methods. +The first parameter is a reference to the `JNIEnv*` value. +The second parameter is a reference to the `jclass` value for the class declaring the method. +The third parameter is a portable (e.g., `long`) identifier of the [Native Image isolatethread](C-API.md). +The rest of the parameters are the actual parameters of the Java `Native.add` method described in the next section. Compile the code with the `--shared` option: ```shell $GRAALVM/bin/native-image --shared -H:Name=libnativeimpl -cp nativeimpl ``` -The `libnativeimpl.so` is generated. We are ready to use it from standard -Java code. +The `libnativeimpl.so` is generated. We are ready to use it from standard Java code. ## Bind a Java Native Method @@ -59,16 +49,14 @@ public final class Native { private static native int add(long isolateThreadId, int a, int b); } ``` -The package name of the class, as well as the name of the method, has to correspond -(after the [JNI mangling](https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html)) -to the name of the `@CEntryPoint` introduced previously. The first argument is -a portable (e.g., `long`) identifier of the Native Image isolate thread. The rest of the arguments -match the parameters of the entry point. +The package name of the class, as well as the name of the method, has to correspond (after the [JNI mangling](https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html)) to the name of the `@CEntryPoint` introduced previously. +The first argument is a portable (e.g., `long`) identifier of the Native Image isolate thread. +The rest of the arguments match the parameters of the entry point. ## Loading the Native Library -The next step is to bind the JDK with the generated `.so` library. For example, -make sure the implementation of the native `Native.add` method is loaded. +The next step is to bind the JDK with the generated `.so` library. +For example, make sure the implementation of the native `Native.add` method is loaded. Simple `load` or `loadLibrary` calls will do: ```java public static void main(String[] args) { @@ -76,27 +64,23 @@ public static void main(String[] args) { // ... } ``` -This is assuming your `LD_LIBRARY_PATH` environment variable is specified, -or the `java.library.path` Java property is properly set. +This is assuming your `LD_LIBRARY_PATH` environment variable is specified, or the `java.library.path` Java property is properly set. ## Initializing a Native Image Isolate -Before making calls to the `Native.add` method, we need to create a Native Image -isolate. Native Image provides a special built-in to allow that: -`CEntryPoint.Builtin.CREATE_ISOLATE`. Define another method along your other -existing `@CEntryPoint` methods. Let it return `IsolateThread` and take no parameters: +Before making calls to the `Native.add` method, we need to create a Native Image isolate. +Native Image provides a special built-in to allow that: `CEntryPoint.Builtin.CREATE_ISOLATE`. +Define another method along your other existing `@CEntryPoint` methods. +Let it return `IsolateThread` and take no parameters: ```java public final class NativeImpl { @CEntryPoint(name = "Java_org_pkg_apinative_Native_createIsolate", builtin=CEntryPoint.Builtin.CREATE_ISOLATE) public static native IsolateThread createIsolate(); } ``` -Native Image then generates default native implementation of the -method into the final `.so` library. -The method initializes the Native Image runtime and -returns a portable identification, e.g., `long`, to hold -an instance of a [Native Image isolatethread](C-API.md). The isolate thread can then be used for -multiple invocations of the native part of your code: +Native Image then generates default native implementation of the method into the final `.so` library. +The method initializes the Native Image runtime and returns a portable identification, e.g., `long`, to hold an instance of a [Native Image isolatethread](C-API.md). +The isolate thread can then be used for multiple invocations of the native part of your code: ```java package org.pkg.apinative; @@ -115,19 +99,16 @@ public final class Native { private static native long createIsolate(); } ``` -The standard JVM is started. It initializes a Native Image isolate, -attaches the current thread to the isolate, and the universal answer `42` is -then computed three times inside of the isolate. +The standard JVM is started. It initializes a Native Image isolate, attaches the current thread to the isolate, and the universal answer `42` is then computed three times inside of the isolate. ## Calling JVM from Native Java -There is a detailed [tutorial on the C interface](https://github.com/oracle/graal/blob/master/substratevm/src/com.oracle.svm.tutorial/src/com/oracle/svm/tutorial/CInterfaceTutorial.java) of Native Image. The following example shows how to make a callback to JVM. +There is a detailed [tutorial on the C interface](https://github.com/oracle/graal/blob/master/substratevm/src/com.oracle.svm.tutorial/src/com/oracle/svm/tutorial/CInterfaceTutorial.java) of Native Image. +The following example shows how to make a callback to JVM. -In the classical setup, when C needs to call into JVM, it uses a [jni.h](JNI.md) -header file. The file defines essential JVM structures (like `JNIEnv`) as well as -functions one can invoke to inspect classes, access fields, and call methods -in the JVM. In order to call these functions from the `NativeImpl` class in the above -example, you need to define appropriate Java API wrappers of the `jni.h` concepts: +In the classical setup, when C needs to call into JVM, it uses a [jni.h](JNI.md) header file. +The file defines essential JVM structures (like `JNIEnv`) as well as functions one can invoke to inspect classes, access fields, and call methods in the JVM. +In order to call these functions from the `NativeImpl` class in the above example, you need to define appropriate Java API wrappers of the `jni.h` concepts: ```java @CContext(JNIHeaderDirectives.class) @@ -172,20 +153,14 @@ interface JMethodID extends PointerBase { } ``` -Leaving aside the meaning of `JNIHeaderDirectives` for now, the rest -of the interfaces are type-safe representations of the C pointers found in the -`jni.h` file. `JClass`, `JMethodID`, and `JObject` are all pointers. Thanks to -the above definitions, you now have Java interfaces to represent -instances of these objects in your native Java code in a type-safe way. - -The core part of any [JNI](JNI.md) API is the set of functions one can call -when talking to the JVM. There are dozens of them, but in the `JNINativeInterface` -definition, you just define wrappers for those few that are needed in the example. -Again, give them proper types, so in your native Java code you can use -`GetMethodId.find(...)`, `CallStaticVoidMethod.call(...)`, etc. In addition, -there is another important part missing in the puzzle - the `jvalue` union type -wrapping all the possible Java primitive and object types. Here are definitions -of its getters and setters: +Leaving aside the meaning of `JNIHeaderDirectives` for now, the rest of the interfaces are type-safe representations of the C pointers found in the `jni.h` file. `JClass`, `JMethodID`, and `JObject` are all pointers. +Thanks to the above definitions, you now have Java interfaces to represent instances of these objects in your native Java code in a type-safe way. + +The core part of any [JNI](JNI.md) API is the set of functions one can call when talking to the JVM. +There are dozens of them, but in the `JNINativeInterface` definition, you just define wrappers for those few that are needed in the example. +Again, give them proper types, so in your native Java code you can use `GetMethodId.find(...)`, `CallStaticVoidMethod.call(...)`, etc. +In addition, there is another important part missing in the puzzle - the `jvalue` union type wrapping all the possible Java primitive and object types. +Here are definitions of its getters and setters: ```java @CContext(JNIHeaderDirectives.class) @@ -215,13 +190,9 @@ interface JValue extends PointerBase { JValue addressOf(int index); } ``` -The `addressOf` method is a special Native Image construct used to perform -C pointer arithmetics. Given a pointer, one can treat it as the initial element of -an array, then, for example, use `addressOf(1)` to access the subsequent element. -With this you have all the API needed to make a callback - redefine -the previously introduced `NativeImpl.add` method to accept properly typed -pointers, and then use these pointers to invoke a JVM method before computing -the sum of `a + b`: +The `addressOf` method is a special Native Image construct used to perform C pointer arithmetics. +Given a pointer, one can treat it as the initial element of an array, then, for example, use `addressOf(1)` to access the subsequent element. +With this you have all the API needed to make a callback - redefine the previously introduced `NativeImpl.add` method to accept properly typed pointers, and then use these pointers to invoke a JVM method before computing the sum of `a + b`: ```java @CEntryPoint(name = "Java_org_pkg_apinative_Native_add") @@ -250,13 +221,9 @@ static int add(JNIEnvironment env, JClass clazz, @CEntryPoint.IsolateThreadConte } ``` -The above example seeks a static method `hello` and invokes it with eight -`JValue` parameters in an array reserved by `StackValue.get` -on the stack. Individual parameters are accessed by use of -the `addressOf` operator and filled with appropriate primitive values -before the call happens. The method `hello` is defined in the class `Native` -and prints values of all parameters to verify they are properly -propagated from the `NativeImpl.add` caller: +The above example seeks a static method `hello` and invokes it with eight `JValue` parameters in an array reserved by `StackValue.get` on the stack. +Individual parameters are accessed by use of the `addressOf` operator and filled with appropriate primitive values before the call happens. +The method `hello` is defined in the class `Native` and prints values of all parameters to verify they are properly propagated from the `NativeImpl.add` caller: ``` public class Native { @@ -268,11 +235,9 @@ public class Native { ``` There is just one final piece to explain: the `JNIHeaderDirectives`. -The Native Image C interface needs to understand the layout of the C structures. It -needs to know at which offset of `JNINativeInterface` structure it can find -the pointer to the `GetMethodId` function. To do so, it needs `jni.h` and additional -files during compilation. One can specify them by `@CContext` annotation and -implementation of its `Directives`: +The Native Image C interface needs to understand the layout of the C structures. +It needs to know at which offset of `JNINativeInterface` structure it can find the pointer to the `GetMethodId` function. +To do so, it needs `jni.h` and additional files during compilation. One can specify them by `@CContext` annotation and implementation of its `Directives`: ```java final class JNIHeaderDirectives implements CContext.Directives { @@ -300,10 +265,7 @@ final class JNIHeaderDirectives implements CContext.Directives { } ``` -The good thing is that `jni.h` is inside of every JDK, so one can use the -`java.home` property to locate the necessary header files. The actual logic -can, of course, be made more robust and OS-independent. +The good thing is that `jni.h` is inside of every JDK, so one can use the `java.home` property to locate the necessary header files. +The actual logic can, of course, be made more robust and OS-independent. -Implementing any JVM native method in Java and/or making callbacks to the JVM -with Native Image should now be as easy as expanding upon the given example -and invoking `native-image`. +Implementing any JVM native method in Java and/or making callbacks to the JVM with Native Image should now be as easy as expanding upon the given example and invoking `native-image`. diff --git a/docs/reference-manual/native-image/JNI.md b/docs/reference-manual/native-image/JNI.md index b658101f7818..55429bb20d66 100644 --- a/docs/reference-manual/native-image/JNI.md +++ b/docs/reference-manual/native-image/JNI.md @@ -53,7 +53,9 @@ class JNIRegistrationFeature implements Feature { } } ``` -To activate the custom feature `--features=` needs to be passed to native-image. [Native Image Build Configuration](BuildConfiguration.md) explains how this can be automated with a `native-image.properties` file in `META-INF/native-image`. + +To activate the custom feature `--features=` needs to be passed to native-image. +[Native Image Build Configuration](BuildConfiguration.md) explains how this can be automated with a `native-image.properties` file in `META-INF/native-image`. ## Object Handles JNI does not permit direct access to Java objects. diff --git a/docs/reference-manual/native-image/LLVMBackend.md b/docs/reference-manual/native-image/LLVMBackend.md index e25dd6aacaa0..15e22d898bf8 100644 --- a/docs/reference-manual/native-image/LLVMBackend.md +++ b/docs/reference-manual/native-image/LLVMBackend.md @@ -6,7 +6,8 @@ permalink: /reference-manual/native-image/LLVMBackend/ --- # LLVM Backend for Native Image -Native Image includes an alternative backend which uses the [LLVM intermediate representation](https://llvm.org/docs/LangRef.html) and the [LLVM compiler](http://llvm.org/docs/CommandGuide/llc.html) to produce native executables. To use it, add the `-H:CompilerBackend=llvm` option to the Native Image invocation. +Native Image includes an alternative backend which uses the [LLVM intermediate representation](https://llvm.org/docs/LangRef.html) and the [LLVM compiler](http://llvm.org/docs/CommandGuide/llc.html) to produce native executables. +To use it, add the `-H:CompilerBackend=llvm` option to the Native Image invocation. The LLVM backend requires GraalVM's LLVM toolchain to be installed (with `gu install llvm-toolchain`). @@ -29,13 +30,15 @@ The LLVM backend requires GraalVM's LLVM toolchain to be installed (with `gu ins ## How to Add a Target Architecture to GraalVM Using LLVM Backend -An interesting use case for the LLVM backend is to target a new architecture without having to implement a complete new backend for Native Image. The following are the necessary steps to achieve this at the moment. +An interesting use case for the LLVM backend is to target a new architecture without having to implement a complete new backend for Native Image. +The following are the necessary steps to achieve this at the moment. ### Target-Specific LLVM Settings There are a few instances where the GraalVM code has to go deeper than the target-independent nature of LLVM. These are most notably inline assembly snippets to implement direct register accesses and direct register jumps (for trampolines), as well as precisions about the structure of the stack frames of the code emitted by LLVM. -All in all, this represents less than a dozen simple values to be set for each new target. It is our goal that in the future this will be the only addition needed to support a new target. +All in all, this represents less than a dozen simple values to be set for each new target. +It is our goal that in the future this will be the only addition needed to support a new target. _([Complete set of values for AArch64](https://github.com/oracle/graal/commit/80cceec6f6299181d94e844eb22dffbef3ecc9e4))_ diff --git a/docs/reference-manual/native-image/Limitations.md b/docs/reference-manual/native-image/Limitations.md index 23974f379729..4f13c6c80924 100644 --- a/docs/reference-manual/native-image/Limitations.md +++ b/docs/reference-manual/native-image/Limitations.md @@ -19,7 +19,8 @@ If an application is not optimizable, then a so-called fallback image is generat ## Class Metadata Features (Require Configuration) -The following features generally require the configuration at image build time in order to use the closed-world optimization. This configuration ensures that the minimum amount of space necessary is used in the native image binary. +The following features generally require the configuration at image build time in order to use the closed-world optimization. +This configuration ensures that the minimum amount of space necessary is used in the native image binary. If one of the following features is used without providing a configuration at image build time, a fallback image is generated. ### Dynamic Class Loading @@ -47,7 +48,8 @@ For more details, read the [Dynamic Proxies support](DynamicProxy.md) guide. ### JNI (Java Native Interface) Native code may access Java objects, classes, methods and fields by name, in a similar way to using the reflection API in Java code. -For the same reasons, any Java artifacts accessed by name via JNI must be specified during a native image generation in a [configuration file](BuildConfiguration.md). For more details, read the [JNI Implementation](JNI.md) guide. +For the same reasons, any Java artifacts accessed by name via JNI must be specified during a native image generation in a [configuration file](BuildConfiguration.md). +For more details, read the [JNI Implementation](JNI.md) guide. As an alternative, and in addition to JNI, Native Image provides its own native interface that is much simpler than JNI and with lower overhead. It allows calls between Java and C, and access of C data structures from Java code. @@ -56,8 +58,8 @@ For more details, read the [JavaDoc of the package `org.graalvm.nativeimage.c` a ### Serialization Java serialization requires class metadata information in order to function and must be specified during a native image generation in a [configuration file](BuildConfiguration.md). -However, Java serialization has been a persistent source of security vulnerabilities. The Java architects have announced that the existing serialization mechanism will be replaced -with a new mechanism avoiding these problems in the near future. +However, Java serialization has been a persistent source of security vulnerabilities. +The Java architects have announced that the existing serialization mechanism will be replaced with a new mechanism avoiding these problems in the near future. ## Features Incompatible with Closed-World Optimization @@ -80,16 +82,12 @@ Native Image implements some Java features in a different way than the Java HotS ### Signal Handlers -Registering a signal handler requires to start a new thread that handles the -signal and invokes the shutdown hooks. By default, no signal handlers are -registered when building a native image, unless they are registered explicitly by the user. -For example, it is not recommended to register the default signal -handlers when building a shared library, but it is desirable to include -signal handlers when building native images for containerized environments, like -Docker containers. +Registering a signal handler requires to start a new thread that handles the signal and invokes the shutdown hooks. +By default, no signal handlers are registered when building a native image, unless they are registered explicitly by the user. +For example, it is not recommended to register the default signal handlers when building a shared library, but it is desirable to include signal handlers when building native images for containerized environments, like Docker containers. -To register the default signal handlers, pass the `--install-exit-handlers` option to the -`native-image` builder. This option gives you the same signal handlers as a JVM does. +To register the default signal handlers, pass the `--install-exit-handlers` option to the `native-image` builder. +This option gives you the same signal handlers as a JVM does. ### Class Initializers By default, classes are initialized at image run time. @@ -99,8 +97,7 @@ Class initialization behaviour can be adjusted using the options `--initialize- See `native-image --help` for details. Classes of the JDK class libraries are handled for you and do not need special consideration from the user. -Native Image users should be aware that class initialization at image build time -may break specific assumptions in existing code. +Native Image users should be aware that class initialization at image build time may break specific assumptions in existing code. For example, files loaded in a class initializer may not be in the same place at image build time as at image run time. Also, certain objects such as a file descriptors or running threads must not be stored into a native image binary. If such objects are reachable at image build time, image generation fails with an error. diff --git a/docs/reference-manual/native-image/NativeImageHeapdumpEnterprise.md b/docs/reference-manual/native-image/NativeImageHeapdumpEnterprise.md index 3cf3f0c9c362..9c89b0cb884f 100644 --- a/docs/reference-manual/native-image/NativeImageHeapdumpEnterprise.md +++ b/docs/reference-manual/native-image/NativeImageHeapdumpEnterprise.md @@ -8,24 +8,20 @@ permalink: /reference-manual/native-image/NativeImageHeapdump/ With GraalVM Enterprise Edition you can generate heap dumps of the Native Image processes to monitor the execution. -Native Image does not implement JVMTI agent and it is not possible to trigger -heap dump creation using tools like _VisualVM_ or _jmap_. You can build a native image for your application in a way so that it can handle certain signals and then get a heap -dump when the application receives the `USR1` signal (other supported signals are `QUIT/BREAK` for stackdumps and `USR2` to dump runtime compilation info). You only need to build your image with GraalVM Enterprise Native Image and use the `-H:+AllowVMInspection` option. +Native Image does not implement JVMTI agent and it is not possible to trigger heap dump creation using tools like _VisualVM_ or _jmap_. +You can build a native image for your application in a way so that it can handle certain signals and then get a heap dump when the application receives the `USR1` signal (other supported signals are `QUIT/BREAK` for stackdumps and `USR2` to dump runtime compilation info). +You only need to build your image with GraalVM Enterprise Native Image and use the `-H:+AllowVMInspection` option. -Another possibility is to -write a special method which will generate a heap dump at certain points in the -lifetime of your application. For example, when certain conditions are met while -executing a native image, your application code can trigger heap dump creation. -A dedicated [`org.graalvm.nativeimage.VMRuntime#dumpHeap`](https://github.com/oracle/graal/blob/master/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/VMInspection.java) API exists for this -purpose. Both possibilities are covered in this guide. +Another possibility is to write a special method which will generate a heap dump at certain points in the lifetime of your application. For example, when certain conditions are met while executing a native image, your application code can trigger heap dump creation. +A dedicated [`org.graalvm.nativeimage.VMRuntime#dumpHeap`](https://github.com/oracle/graal/blob/master/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/VMInspection.java) API exists for this purpose. +Both possibilities are covered in this guide. Note: This feature is available with **GraalVM Enterprise** only. ## Handle SIGUSR1 Signal -The following Java example is a simple multi-threaded application which runs for -60 seconds. There is enough time to get its PID and send the SIGUSR1 signal -which will generate a heap dump into the application's working directory. Save -the following code as _SVMHeapDump.java_ file on your disk: +The following Java example is a simple multi-threaded application which runs for 60 seconds. +There is enough time to get its PID and send the SIGUSR1 signal which will generate a heap dump into the application's working directory. +Save the following code as _SVMHeapDump.java_ file on your disk: ```java import java.text.DateFormat; import java.util.Date; @@ -81,9 +77,8 @@ $JAVA_HOME/bin/javac SVMHeapDump.java ``` If you run it on `java`, you will see that it runs for 60 seconds then finishes. -Build a native executable and provide the `-H:+AllowVMInspection` option for the -builder. This way the native executable will accept SIGUSR1 signal to produce a -heap dump. +Build a native executable and provide the `-H:+AllowVMInspection` option for the builder. +This way the native executable will accept SIGUSR1 signal to produce a heap dump. ```shell $JAVA_HOME/bin/native-image SVMHeapDump -H:+AllowVMInspection @@ -105,9 +100,8 @@ $JAVA_HOME/bin/native-image SVMHeapDump -H:+AllowVMInspection [svmheapdump:41691] [total]: 47,805.47 ms, 2.62 GB ``` -The `native-image` builder analyzes existing `SVMHeapDump.class` and creates from -it an executable file. When the command completes, `svmheapdump` is created in -the current directory. +The `native-image` builder analyzes existing `SVMHeapDump.class` and creates from it an executable file. +When the command completes, `svmheapdump` is created in the current directory. ##### Run the application and check the heap dump Run the application: @@ -121,10 +115,7 @@ Starting thread! May 15, 2020, 4:28:14 PM: Thread started, it will run for 60 seconds ``` -Open the 2nd terminal to get the process ID of the running `svmheapdump` -application using a command like `ps -C svmheapdump -o pid=` for Linux OS and -`pgrep svmheapdump` for macOS. Copy the printed process ID, e.g. 100, and use it -to send the signal to the running application: +Open the 2nd terminal to get the process ID of the running `svmheapdump` application using a command like `ps -C svmheapdump -o pid=` for Linux OS and `pgrep svmheapdump` for macOS. Copy the printed process ID, e.g. 100, and use it to send the signal to the running application: ```shell kill -SIGUSR1 100 ``` @@ -132,8 +123,7 @@ The heap dump will be available at the working directory while the application c ## Generate a Heap Dump from within a Java Application -The following Java example shows how a heap dump can be generated from within -a running Java application using `VMRuntime.dumpHeap()` after some condition is met. +The following Java example shows how a heap dump can be generated from within a running Java application using `VMRuntime.dumpHeap()` after some condition is met. The condition to generate a heap dump is provided as an option on the command line. Save the code snippet below as _SVMHeapDumpAPI.java_. @@ -186,8 +176,7 @@ public class SVMHeapDumpAPI { } } ``` -The application creates some data to have something to dump, checks the command line -to see if heap dump has to be created, and then in method `createHeapDump()` creates +The application creates some data to have something to dump, checks the command line to see if heap dump has to be created, and then in method `createHeapDump()` creates the actual heap dump, performing checks for file's existence. #### Building a Native Image @@ -219,8 +208,7 @@ $JAVA_HOME/bin/native-image SVMHeapDumpAPI When the command completes, the `svmheapdumpapi` executable is created in the current directory. ##### Run the application and check the heap dump -Now you can run your native image application and generate a heap dump from it -with the output similar to one below: +Now you can run your native image application and generate a heap dump from it with the output similar to one below: ```shell ./svmheapdumpapi --heapdump Sep 15, 2020, 4:06:36 PM: Hello GraalVM native image developer. @@ -228,4 +216,4 @@ Your command line options are: --heapdump Heap dump created /var/folders/hw/s9d78jts67gdc8cfyq5fjcdm0000gp/T/SVMHeapDump-6437252222863577987.hprof, size: 8051959 ``` -The resulting heap dump can be then opened with the [VisualVM](/tools/visualvm/) tool like any other Java heap dump. +The resulting heap dump can be then opened with the [VisualVM](../../tools/visualvm.md) tool like any other Java heap dump. diff --git a/docs/reference-manual/native-image/Options.md b/docs/reference-manual/native-image/Options.md index 63c20d8b84c8..8b619ec567bf 100644 --- a/docs/reference-manual/native-image/Options.md +++ b/docs/reference-manual/native-image/Options.md @@ -6,29 +6,22 @@ permalink: /reference-manual/native-image/Options/ --- # Native Image Options -The `native-image` builder needs to provide the classpath for all classes -using the familiar option from the `java` launcher: `-cp` is followed by a list -of directories or JAR files, separated by `:`. The name of the class containing -the `main` method is the last argument, or you can use `-jar` and provide a JAR -file that specifies the main method in its manifest. +The `native-image` builder needs to provide the classpath for all classes using the familiar option from the `java` launcher: `-cp` is followed by a list of directories or JAR files, separated by `:`. +The name of the class containing the `main` method is the last argument, or you can use `-jar` and provide a JAR file that specifies the main method in its manifest. The syntax of the `native-image` command is: -- `native-image [options] class [imagename] [options]` to build an executable file for a class in the -current working directory. Invoking it executes the native-compiled code of that -class. +- `native-image [options] class [imagename] [options]` to build an executable file for a class in the current working directory. Invoking it executes the native-compiled code of that class. - `native-image [options] -jar jarfile [imagename] [options]` to build an image for a JAR file. The options passed to `native-image` are evaluated left-to-right. For more information, see [Native Image Build Configuration](BuildConfiguration.md#order-of-arguments-evaluation). -The options fall into four categories: -image generation options, macro options, non-standard options, and server options. +The options fall into four categories: image generation options, macro options, non-standard options, and server options. Non-standard and server options are subject to change through a deprecation cycle. -Command-line help is available. Run `native-image --help` to get -the commands overview, and `native-image --help-extra` to print help on non-standard, -macro, and server options. +Command-line help is available. +Run `native-image --help` to get the commands overview, and `native-image --help-extra` to print help on non-standard, macro, and server options. ### Options to Native Image Builder @@ -94,7 +87,7 @@ instantiation is traced for. * `--tool:lsp`: add the Language Server Protocol support to later attach compatible debuggers to GraalVM in IDEs like VS Code * `--tool:profiler`: add profiling support to a GraalVM supported language -The `--language:python`, `--language:ruby` and `--language:R` polyglot macro options become available once the corresponding languages are added to the base GraalVM installation (see the [GraalVM Updater](https://www.graalvm.org/reference-manual/graalvm-updater/) guide). +The `--language:python`, `--language:ruby` and `--language:R` polyglot macro options become available once the corresponding languages are added to the base GraalVM installation (see the [GraalVM Updater](../graalvm-updater.md) guide). ### Non-standard Options * `--expert-options`: list image build options for experts diff --git a/docs/reference-manual/native-image/README.md b/docs/reference-manual/native-image/README.md index f54ac4b42196..6002c1cd82ae 100644 --- a/docs/reference-manual/native-image/README.md +++ b/docs/reference-manual/native-image/README.md @@ -18,11 +18,9 @@ Then it ahead-of-time compiles that reachable code and data to a native executab This entire process is called **building an image** (or the **image build time**) to clearly distinguish it from the compilation of Java source code to bytecode. Native Image supports JVM-based languages, e.g., Java, Scala, Clojure, Kotlin. -The resulting image can, optionally, execute dynamic languages like -JavaScript, Ruby, R or Python. Polyglot embeddings can also be compiled -ahead-of-time. To inform `native-image` of a guest language used by an -application, specify `--language:` for each guest language (e.g., -`--language:js`). +The resulting image can, optionally, execute dynamic languages like JavaScript, Ruby, R or Python. +Polyglot embeddings can also be compiled ahead-of-time. +To inform `native-image` of a guest language used by an application, specify `--language:` for each guest language (e.g., `--language:js`). * [Install Native Image](#install-native-image) * [Prerequisites](#prerequisites) @@ -42,7 +40,7 @@ For more information, check the [Oracle Technology Network License Agreement for ## Install Native Image -Native Image can be added to GraalVM with the [GraalVM Updater](https://www.graalvm.org/reference-manual/graalvm-updater/) tool. +Native Image can be added to GraalVM with the [GraalVM Updater](../graalvm-updater.md) tool. Run this command to install Native Image: ```shell @@ -52,13 +50,11 @@ After this additional step, the `native-image` executable will become available the `GRAALVM_HOME/bin` directory. The above command will install Native Image from the GitHub catalog for GraalVM Community users. -For GraalVM Enterprise users, the [manual installation](https://www.graalvm.org/reference-manual/graalvm-updater/#manual-installation) is required. +For GraalVM Enterprise users, the [manual installation](../graalvm-updater.md#manual-installation) is required. ## Prerequisites -For compilation `native-image` depends on the local toolchain. Install - `glibc-devel`, `zlib-devel` (header files for the C library and `zlib`) -and `gcc`, using a package manager available on your OS. Some Linux distributions may additionally require `libstdc++-static`. +For compilation `native-image` depends on the local toolchain. Install `glibc-devel`, `zlib-devel` (header files for the C library and `zlib`) and `gcc`, using a package manager available on your OS. Some Linux distributions may additionally require `libstdc++-static`. On Oracle Linux use `yum` package manager: ```shell @@ -105,12 +101,9 @@ To build a native image of a JAR file, use: native-image [options] -jar jarfile [imagename] [options] ``` -The `native-image` command needs to provide the class path for all classes using -the familiar option from the java launcher: `-cp` followed by a list of +The `native-image` command needs to provide the class path for all classes using the familiar option from the java launcher: `-cp` followed by a list of directories or JAR files, separated by `:` on Linux and macOS platforms, or `;` on Windows. -The name of the class containing the -main method is the last argument, or you can use `-jar` and provide a JAR -file that specifies the main method in its manifest. +The name of the class containing the main method is the last argument, or you can use `-jar` and provide a JAR file that specifies the main method in its manifest. As an example, take this small Java program that reverses a String using recursion: ```java @@ -134,20 +127,18 @@ Compile it and build a native image from the Java class: javac Example.java native-image Example ``` -The native image builder ahead-of-time compiles the `Example` class into a -standalone executable, `example`, in the current working directory. Run the executable: +The native image builder ahead-of-time compiles the `Example` class into a standalone executable, `example`, in the current working directory. +Run the executable: ```shell ./example ``` -Another option to the native image builder that might be helpful is -`--install-exit-handlers`. It is not recommended to register the default signal -handlers when building a shared library. However, it is desirable to include -signal handlers when building a native image for containerized environments, like -Docker containers. The `--install-exit-handlers` option gives you the same -signal handlers that a JVM does. +Another option to the native image builder that might be helpful is `--install-exit-handlers`. +It is not recommended to register the default signal handlers when building a shared library. +However, it is desirable to include signal handlers when building a native image for containerized environments, like Docker containers. +The `--install-exit-handlers` option gives you the same signal handlers that a JVM does. -For more complex examples, visit the [native image generation](https://www.graalvm.org/examples/native-image-examples/) or [compiling a Java and Kotlin app ahead-of-time](https://www.graalvm.org/examples/java-kotlin-aot/) pages. +For more complex examples, visit the [native image generation](../../examples/native-image-examples.md) or [compiling a Java and Kotlin app ahead-of-time](../../examples/java-kotlin-aot.md) pages. ## Build a Shared Library @@ -165,7 +156,9 @@ Note: if you build a shared library where you do not specify a main class, you m As mentioned in the previous section, you need to have at least one entry point method for a native image to be useful. For shared libraries, Native Image provides the `@CEntryPoint` annotation to specify entry point methods that should be exported and callable from C. -Entry point methods must be static and may only have non-object parameters and return types – this includes Java primitives, but also Word types (including pointers). One of the parameters of an entry point method has to be of type `IsolateThread` or `Isolate`. This parameter provides the current thread's execution context for the call. +Entry point methods must be static and may only have non-object parameters and return types – this includes Java primitives, but also Word types (including pointers). +One of the parameters of an entry point method has to be of type `IsolateThread` or `Isolate`. +This parameter provides the current thread's execution context for the call. For example: @@ -176,7 +169,8 @@ For example: ``` When building a shared library, an additional C header file is generated. -This header file contains declarations for the [C API](C-API.md), which allows creating isolates and attaching threads from C code, as well as declarations for each entry point in the source code. The generated C declaration for the above example is: +This header file contains declarations for the [C API](C-API.md), which allows creating isolates and attaching threads from C code, as well as declarations for each entry point in the source code. +The generated C declaration for the above example is: ```c int add(graal_isolatethread_t* thread, int a, int b); ``` @@ -192,9 +186,9 @@ native-image -cp hello EmptyHello ... ``` -If you do not know what GraalVM distribution is set to the `PATH` environment -variable, how to determine if a native image was compiled with Community or -Enterprise Edition? Run this command: +If you do not know what GraalVM distribution is set to the `PATH` environment variable, how to determine if a native image was compiled with Community or +Enterprise Edition? +Run this command: ```shell strings emptyhello | grep com.oracle.svm.core.VM ``` @@ -229,10 +223,7 @@ com.oracle.svm.core.VM=GraalVM Java 11 EE ## Ahead-of-time Compilation Limitations -There is a small portion of Java features are not susceptible to ahead-of-time -compilation, and will therefore miss out on the performance advantages. To be -able to build a highly optimized native executable, GraalVM runs an aggressive static -analysis that requires a closed-world assumption, which means that all classes -and all bytecodes that are reachable at run time must be known at build time. -Therefore, it is not possible to load new data that have not been available -during ahead-of-time compilation. Continue reading to [GraalVM Native Image Compatibility and Optimization](Limitations.md). +There is a small portion of Java features are not susceptible to ahead-of-time compilation, and will therefore miss out on the performance advantages. +To be able to build a highly optimized native executable, GraalVM runs an aggressive static analysis that requires a closed-world assumption, which means that all classes and all bytecodes that are reachable at run time must be known at build time. +Therefore, it is not possible to load new data that have not been available during ahead-of-time compilation. +Continue reading to [GraalVM Native Image Compatibility and Optimization](Limitations.md). diff --git a/docs/reference-manual/native-image/Reports.md b/docs/reference-manual/native-image/Reports.md index d0aee5feae2b..1b518cdabfdc 100644 --- a/docs/reference-manual/native-image/Reports.md +++ b/docs/reference-manual/native-image/Reports.md @@ -6,12 +6,9 @@ permalink: /reference-manual/native-image/Reports/ --- # Points-to Analysis Reports -The points-to analysis produces two kinds of reports: analysis call tree and -image object tree. This information is produced by an intermediate step in the -image building process and represents the static analysis view of the call graph -and heap object graph. These graphs are further transformed in the image -building process before they are AOT compiled into the image and written into -the image heap, respectively. +The points-to analysis produces two kinds of reports: analysis call tree and image object tree. +This information is produced by an intermediate step in the image building process and represents the static analysis view of the call graph and heap object graph. +These graphs are further transformed in the image building process before they are AOT compiled into the image and written into the image heap, respectively. #### Call tree The call tree is a a breadth-first tree reduction of the call graph as seen by the points-to analysis. diff --git a/docs/reference-manual/native-image/Resources.md b/docs/reference-manual/native-image/Resources.md index 3c12fe49671f..f54205314b90 100644 --- a/docs/reference-manual/native-image/Resources.md +++ b/docs/reference-manual/native-image/Resources.md @@ -26,7 +26,8 @@ To make calls such as `Class.getResource()` or `Class.getResourceAsStream()` (or } ``` -The configuration file's path must be provided to `native-image` with `-H:ResourceConfigurationFiles=/path/to/resource-config.json`. Alternatively, individual resource paths can also be specified directly to `native-image`: +The configuration file's path must be provided to `native-image` with `-H:ResourceConfigurationFiles=/path/to/resource-config.json`. +Alternatively, individual resource paths can also be specified directly to `native-image`: ```shell native-image -H:IncludeResources= -H:ExcludeResources= ... ``` @@ -60,9 +61,8 @@ See also the [guide on assisted configuration of Java resources and other dynami ## Locales -It is also possible to specify which locales should be included in the image and what should be the default one. For -example, to switch the default locale to German and also include French and English, one can use the following hosted -options. +It is also possible to specify which locales should be included in the image and what should be the default one. +For example, to switch the default locale to German and also include French and English, one can use the following hosted options. ```shell native-image -H:DefaultLocale=de -H:IncludeLocales=fr,en ``` @@ -74,7 +74,8 @@ binary. Java localization support (`java.util.ResourceBundle`) enables Java code to load L10N resources and show the right user messages suitable for actual runtime settings like time locale and format, etc. -Native Image needs ahead-of-time knowledge of the resource bundles your application needs so that it can load and store the appropriate bundles for usage in the generated binary. The bundles can be specified in the resource configuration file (see above), in the `bundles` section: +Native Image needs ahead-of-time knowledge of the resource bundles your application needs so that it can load and store the appropriate bundles for usage in the generated binary. +The bundles can be specified in the resource configuration file (see above), in the `bundles` section: ```json { @@ -91,13 +92,12 @@ Alternatively, bundles can be specified directly as options to `native-image` as ```shell native-image -H:IncludeResourceBundles=your.pgk.Bundle,another.pkg.Resource,etc.Bundle ... ``` -By default, the requested bundles are included for all requested locales. In order to optimize this, it is possible to -use ``IncludeResourceBundles`` with locale specific substring, for -example ``-H:+IncludeResourceBundles=com.company.bundles.MyBundle_fr-FR`` will include the bundle only in French. +By default, the requested bundles are included for all requested locales. +In order to optimize this, it is possible to use ``IncludeResourceBundles`` with locale specific substring, for example ``-H:+IncludeResourceBundles=com.company.bundles.MyBundle_fr-FR`` will include the bundle only in French. ### JVM Mode of Localization -Resource Bundle lookup is a complex and dynamic mechanism which utilizes a lot of the infrastructure of JVM. As a result of that, it causes image size increase -for smaller applications such as Hello World. Therefore, an optimized mode is set by default in which this lookup is simplified utilizing the fact the all -bundles are known ahead of time. +Resource Bundle lookup is a complex and dynamic mechanism which utilizes a lot of the infrastructure of JVM. +As a result of that, it causes image size increase for smaller applications such as Hello World. +Therefore, an optimized mode is set by default in which this lookup is simplified utilizing the fact the all bundles are known ahead of time. In case you would like to use the original JVM lookup, use the `-H:-LocalizationOptimizedMode` option. diff --git a/docs/reference-manual/polyglot-programming.md b/docs/reference-manual/polyglot-programming.md index fb8074f062cc..9f023a92a17d 100644 --- a/docs/reference-manual/polyglot-programming.md +++ b/docs/reference-manual/polyglot-programming.md @@ -14,21 +14,17 @@ permalink: /reference-manual/polyglot-programming/ * [Passing Options Programmatically](#passing-options-programmatically) * [Passing Options Using JVM Arguments](#passing-options-using-jvm-arguments) -GraalVM allows users to write polyglot applications that seamlessly -pass values from one language to another by means of the [Truffle language implementation framework](/graalvm-as-a-platform/language-implementation-framework/) (henceforth "Truffle"). +GraalVM allows users to write polyglot applications that seamlessly pass values from one language to another by means of the [Truffle language implementation framework](../../truffle/docs/README.md) (henceforth "Truffle"). Truffle is a Java library for building programming languages implementations as interpreters for self-modifying Abstract Syntax Trees. When writing a language interpreter with Truffle, it will automatically use the GraalVM compiler as a just-in-time compiler for the language. By having access to this framework, a Ruby application, for example, can run on the same JVM as a Java application. Also, a host JVM-based language and a guest language can directly interoperate with each other and pass data back and forth in the same memory space. -In order to provide foreign polyglot values in the languages implemented with Truffle, the so-called _polyglot interoperability protocol_ has been developed. This -interoperability protocol consists of a set of standardized messages that every -language implements and uses for foreign polyglot values. The protocol allows -GraalVM to support interoperability between any combination of languages without -requiring them to know of each other. For more details, proceed to the -[High-Performance Cross-Language Interoperability in a Multi-Language Runtime](http://dx.doi.org/10.1145/2816707.2816714) paper. - +In order to provide foreign polyglot values in the languages implemented with Truffle, the so-called _polyglot interoperability protocol_ has been developed. +This interoperability protocol consists of a set of standardized messages that every language implements and uses for foreign polyglot values. +The protocol allows GraalVM to support interoperability between any combination of languages without requiring them to know of each other. +For more details, proceed to the [High-Performance Cross-Language Interoperability in a Multi-Language Runtime](http://dx.doi.org/10.1145/2816707.2816714) paper. Throughout this section you learn how to combine multiple languages using GraalVM Polyglot APIs. ## Running Polyglot Applications @@ -41,12 +37,11 @@ Ensure you set up GraalVM before you begin. The below examples work: * on a JVM, by passing `--polyglot --jvm`. * on native launchers with `--polyglot` (e.g., `js --polyglot`). - It might be required to [rebuild images](/reference-manual/graalvm-updater/#rebuild-images) to access languages installed with `gu`. + It might be required to [rebuild images](graalvm-updater.md#rebuild-images) to access languages installed with `gu`. * with native executables (e.g., `native-image --language:js`). For native launchers and native executables using Java as a Target Language -and accessing classes other than Java arrays, it is required to recompile the image and provide -a [reflection configuration file](/reference-manual/native-image/Reflection/). +and accessing classes other than Java arrays, it is required to recompile the image and provide a [reflection configuration file](native-image/Reflection.md). Note: To start an application with LLVM as a Target Language, make sure to precompile the _polyglot.c_ file provided below. @@ -201,7 +196,7 @@ polyglot --jvm polyglot.js polyglot.R polyglot.rb ``` We have also included a basic experimental shell for multiple languages called the _Polyglot Shell_. -It is useful to quickly test the interactivity of languages implemented with the [Truffle framework](/graalvm-as-a-platform/language-implementation-framework/). +It is useful to quickly test the interactivity of languages implemented with the [Truffle framework](../../truffle/docs/README.md). This is how you can start it: ```shell diff --git a/docs/reference-manual/reference-manuals.md b/docs/reference-manual/reference-manuals.md index 969593093a0d..3c1e33cd879d 100644 --- a/docs/reference-manual/reference-manuals.md +++ b/docs/reference-manual/reference-manuals.md @@ -14,25 +14,25 @@ environment for their workloads. ## Technologies -[Native Image](/reference-manual/native-image/) - learn in detail about Native Image: GraalVM's innovative technology that can ahead-of-time compile Java code to a self-contained native executable. +[Native Image](native-image/README.md) - learn in detail about Native Image: GraalVM's innovative technology that can ahead-of-time compile Java code to a self-contained native executable. -[Compiler](/reference-manual/compiler/) - learn about the uniqueness of the GraalVM compiler and its advantages. +[Compiler](compiler.md) - learn about the uniqueness of the GraalVM compiler and its advantages. -[Updater](/reference-manual/graalvm-updater/) - learn how to add more capabilities and upgrade the core GraalVM installation. +[Updater](graalvm-updater.md) - learn how to add more capabilities and upgrade the core GraalVM installation. -[Polyglot Programming](/reference-manual/polyglot-programming/) - learn how to write polyglot applications and allow languages to directly interoperate with each other in the same memory space. +[Polyglot Programming](polyglot-programming.md) - learn how to write polyglot applications and allow languages to directly interoperate with each other in the same memory space. -[Embedding Languages](/reference-manual/embed-languages/) - learn how to embed polyglot applications in Java host applications or native images. +[Embedding Languages](embedding/embed-languages.md) - learn how to embed polyglot applications in Java host applications or native images. ## Specific Languages If you are mostly interested in the GraalVM support for a specific language, here you can find the most extensive documentation: -* [Java](/reference-manual/java/) -* [Java on Truffle](/reference-manual/java-on-truffle/) -* [JavaScript and Node.js](/reference-manual/js/) -* [LLVM Languages](/reference-manual/llvm/) -* [Python](/reference-manual/python/) -* [R](/reference-manual/r/) -* [Ruby](/reference-manual/ruby/) -* [WebAssembly](/reference-manual/wasm/) +* [Java](java/README.md) +* [Java on Truffle](java-on-truffle/README.md) +* [JavaScript and Node.js](js/README.md) +* [LLVM Languages](llvm/README.md) +* [Python](python/README.md) +* [R](r/README.md) +* [Ruby](ruby/README.md) +* [WebAssembly](wasm/README.md) diff --git a/docs/reference-manual/wasm/README.md b/docs/reference-manual/wasm/README.md index 4c47f89a120d..66b106f68f37 100644 --- a/docs/reference-manual/wasm/README.md +++ b/docs/reference-manual/wasm/README.md @@ -13,12 +13,12 @@ The support for WebAssembly is in the early stages of its development. ## Installing Wasm -The support is not available by default, but you can add it to GraalVM using the [GraalVM Updater](/reference-manual/graalvm-updater/) tool: +The support is not available by default, but you can add it to GraalVM using the [GraalVM Updater](../graalvm-updater.md) tool: ```shell gu install wasm ``` The above command will install a community version of a component from the GitHub catalog. -For GraalVM Enterprise users, the [manual component installation](/reference-manual/graalvm-updater/#component-installation) is required. +For GraalVM Enterprise users, the [manual component installation](../graalvm-updater.md#component-installation) is required. Then `wasm` launcher, which can run compiled WebAssembly binary code, becomes available. @@ -75,4 +75,4 @@ Value mainFunction = context.getBindings("wasm").getMember("main").getMember("_s mainFunction.execute(); ``` -For more polyglot examples, visit the [Polyglot Programming](/reference-manual/polyglot-programming/) page. +For more polyglot examples, visit the [Polyglot Programming](../polyglot-programming.md) page. diff --git a/docs/tools/chrome-debugger.md b/docs/tools/chrome-debugger.md index 5d87871181d2..506e0ac7592d 100644 --- a/docs/tools/chrome-debugger.md +++ b/docs/tools/chrome-debugger.md @@ -8,9 +8,11 @@ redirect_from: /docs/tools/chrome-debugger/ # Chrome Debugger -GraalVM supports debugging of guest language applications and provides a built-in implementation of the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). This allows you to attach compatible debuggers such as [Chrome Developer Tools](https://developers.google.com/web/tools/chrome-devtools/) to GraalVM. +GraalVM supports debugging of guest language applications and provides a built-in implementation of the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). +This allows you to attach compatible debuggers such as [Chrome Developer Tools](https://developers.google.com/web/tools/chrome-devtools/) to GraalVM. To debug guest language applications, pass the `--inspect` option to the command line launcher, as in the following example with a Node.js _HelloWorld_ program: + ```javascript var http = require('http'); diff --git a/docs/tools/code-coverage.md b/docs/tools/code-coverage.md index 5367925cbe33..81d6ae8910ed 100644 --- a/docs/tools/code-coverage.md +++ b/docs/tools/code-coverage.md @@ -7,22 +7,15 @@ permalink: /tools/code-coverage/ # Code Coverage Command Line Tool -As of version 19.3.0, GraalVM provides a **code coverage command line tool** -that lets users record and analyze the source code coverage of a particular execution -of code. +GraalVM provides a **code coverage command line tool** that lets users record and analyze the source code coverage of a particular execution of code. -Code coverage, as a percentage of source code lines, functions, or statements -covered, is an important metric for understanding a particular source code +Code coverage, as a percentage of source code lines, functions, or statements covered, is an important metric for understanding a particular source code execution, and is commonly associated with test quality (test coverage). -Providing a visual coverage overview for individual lines of code shows the -developer which code paths are covered and which are not, giving insight into -the character of the execution which can, for example, inform further testing -efforts. +Providing a visual coverage overview for individual lines of code shows the developer which code paths are covered and which are not, giving insight into the character of the execution which can, for example, inform further testing efforts. -The example application below will be used to demonstrate GraalVM's code -coverage capabilities. This application defines a -`getPrime` function that calculates the n-th prime using a basic prime number -calculator based on the [Sieve of Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) algorithm. It also has a somewhat naive cache of the first 20 prime numbers. +The example application below will be used to demonstrate GraalVM's code coverage capabilities. +This application defines a `getPrime` function that calculates the n-th prime using a basic prime number calculator based on the [Sieve of Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) algorithm. +It also has a somewhat naive cache of the first 20 prime numbers. 1. Copy the following code into a new file named `primes.js`: @@ -96,11 +89,10 @@ Shows what percent of each element was covered during execution /path/to/primes.js | 20.69% | 26.67% | 22.22% -------------------------------------------------------- ``` -The tracer prints a coverage histogram for each source file. You can see that -statement coverage is roughly 20%, line coverage is roughly 26%, and root coverage (the -term "root" covers functions, methods, etc.) is 22.22%. This tells your that our -simple tests are not particularly good at exercising the source code. Next you -will figure out which parts of the code are not covered. +The tracer prints a coverage histogram for each source file. +You can see that statement coverage is roughly 20%, line coverage is roughly 26%, and root coverage (the term "root" covers functions, methods, etc.) is 22.22%. +This tells your that our simple tests are not particularly good at exercising the source code. +Next you will figure out which parts of the code are not covered. 4. Run `js primes.js --coverage --coverage.Output=detailed`. Prepare for a somewhat verbose output. Specifying the output as `detailed` will print all the source code lines with a @@ -175,16 +167,15 @@ p if (n > cache.length) { return calculatePrime(n); } -------------------------------------------------------- ``` -As the legend at the beginning of the output explains, lines that are covered by -the execution are preceded with a `+`. Lines not covered by the execution are -preceded with a `-`. Lines that are covered partially are preceded with `p` (e.g., when an `if` -statement is covered but only one branch is taken, consider the other bench +As the legend at the beginning of the output explains, lines that are covered by the execution are preceded with a `+`. +Lines not covered by the execution are preceded with a `-`. +Lines that are covered partially are preceded with `p` (e.g., when an `if` statement is covered but only one branch is taken, consider the other bench to be incidentally covered). -Looking at the output you can see that the `calculatePrime` function and all its -calls are never executed. Looking again at the assertions and the `getPrime` -function, it becomes clear that our tests always hit the cache. Thus most of the -code is never executed. You can improve on that. +Looking at the output you can see that the `calculatePrime` function and all its calls are never executed. +Looking again at the assertions and the `getPrime` function, it becomes clear that our tests always hit the cache. +Thus most of the code is never executed. +You can improve on that. 5. Add `console.assert(getPrime(30) == 113);` to the end of the `primes.js` file and run `js primes.js --coverage`. Since the new assertion added calls @@ -205,11 +196,9 @@ Code coverage histogram. ## Integrating with Other Tools -The code coverage tool provides ways to integrate with other tools. Running -with `--coverage.Output=lcov` produces output in the commonly used -[lcov](https://linux.die.net/man/1/lcov) format which is used by multiple tools -(e.g., `genhtml`) to display coverage data. Take a look at the next example that -shows how to visualise coverage of a Node.js app with Visual Studio Code. +The code coverage tool provides ways to integrate with other tools. +Running with `--coverage.Output=lcov` produces output in the commonly used [lcov](https://linux.die.net/man/1/lcov) format which is used by multiple tools (e.g., `genhtml`) to display coverage data. +Take a look at the next example that shows how to visualise coverage of a Node.js app with Visual Studio Code. 1. Copy the following code into a new file named `nodeapp.js`: @@ -244,9 +233,7 @@ node --coverage --coverage.Output=lcov \ nodeapp.js ``` -Note that the Code Coverage Highlighter plugin looks for the `lcov.info` file in -the `coverage` directory by default, so direct the output of the code -coverage tool there. +Note that the Code Coverage Highlighter plugin looks for the `lcov.info` file in the `coverage` directory by default, so direct the output of the code coverage tool there. 5. Visit [localhost:3000/](http://localhost:3000/) in your browser, then visit [localhost:3000/shutdown](http://localhost:3000/shutdown) to close the app. @@ -255,6 +242,4 @@ and `coverage` directory and you should be greeted with an image similar to the ![](img/vscode-coverage.png) -If you wish to integrate the data gathered by the GraalVM code coverage tool -with your own visualisation, the `--coverage.Output=json` option results in -the output being a JSON file with the raw data gathered by the tracker. +If you wish to integrate the data gathered by the GraalVM code coverage tool with your own visualisation, the `--coverage.Output=json` option results in the output being a JSON file with the raw data gathered by the tracker. diff --git a/docs/tools/dap.md b/docs/tools/dap.md index c890f7b60aea..42256a1ec8fe 100644 --- a/docs/tools/dap.md +++ b/docs/tools/dap.md @@ -77,10 +77,10 @@ code . 8. Start debugging (F5). The other approach is to use VS Code with the GraalVM extension installed. -Follow the steps described in -[Node.js and JavaScript Debugging](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.graalvm#javascript-and-node.js-debugging), and launch the application being debugged directly from VS Code. +Follow the steps described in [Node.js and JavaScript Debugging](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.graalvm#javascript-and-node.js-debugging), and launch the application being debugged directly from VS Code. When debugging a guest language application from VS Code, a user can choose a protocol to use by setting the protocol attribute in the corresponding debug configuration to either `chromeDevTools` or `debugAdapter`. To connect to the open DAP port in this scenario, the content of the _launch.json_ should be: + ```json { "version": "0.2.0", diff --git a/docs/tools/graalvm-insight.md b/docs/tools/graalvm-insight.md index daafa72079c7..8bdf45600b1b 100644 --- a/docs/tools/graalvm-insight.md +++ b/docs/tools/graalvm-insight.md @@ -7,22 +7,20 @@ permalink: /tools/graalvm-insight/ # GraalVM Insight -GraalVM Insight is a multipurpose, flexible tool for writing reliable -microservices solutions that traces program runtime behavior and gathers insights. +* [Start Using GraalVM Insight](#start-using-graalvm-insight) +* [Polyglot Tracing](#polyglot-tracing) +* [Inspecting Values](#inspecting-values) -The dynamic nature of the tool helps users to selectively apply tracing pointcuts on -already running applications with no loss of performance. Insight -also provides detailed access to runtime behavior of a program, allowing users to -inspect values and types at invocation or allocation sites. GraalVM Insight further permits users to -modify computed values, interrupt execution, and quickly experiment with -behavioral changes without modifying the application code. +GraalVM Insight is a multipurpose, flexible tool for writing reliable microservices solutions that traces program runtime behavior and gathers insights. + +The dynamic nature of the tool helps users to selectively apply tracing pointcuts on already running applications with no loss of performance. +GraalVM Insight also provides detailed access to runtime behavior of a program, allowing users to inspect values and types at invocation or allocation sites. +The tool further permits users to modify computed values, interrupt execution, and quickly experiment with behavioral changes without modifying the application code. This page provides information on GraalVM Insight as of the 20.1 version. To learn about Insight on versions 20.0 and 19.3, proceed [here](https://github.com/oracle/graal/blob/release/graal-vm/20.0/tools/docs/T-Trace.md). -Note: The GraalVM Insight tool is offered as a technology preview and requires the user to -pass the `--experimental-options` option in order to enable the `--insight` -instrument. +Note: The GraalVM Insight tool is offered as a technology preview and requires the user to pass the `--experimental-options` option in order to enable the `--insight` instrument. ## Start Using GraalVM Insight @@ -48,14 +46,11 @@ Loading 505 characters from [eval]-wrapper Loading 29 characters from [eval] The result: 42 ``` -The _source-tracing.js_ script used the provided `insight` object to -attach a source listener to the runtime. Whenever the script was loaded, the -listener got notified of it and could take an action -- printing the length and -name of the processed script. +The _source-tracing.js_ script used the provided `insight` object to attach a source listener to the runtime. +Whenever the script was loaded, the listener got notified of it and could take an action -- printing the length and name of the processed script. The Insight information can be collected to a print statement or a histogram. -The following _function-histogram-tracing.js_ script counts all method invocations -and dumps the most frequent ones when the execution of a program is over: +The following _function-histogram-tracing.js_ script counts all method invocations and dumps the most frequent ones when the execution of a program is over: ```javascript var map = new Map(); @@ -90,10 +85,9 @@ insight.on('enter', function(ev) { insight.on('close', dumpHistogram); ``` -The `map` is a global variable shared inside of the Insight script that allows the -code to share data between the `insight.on('enter')` function and the `dumpHistogram` -function. The latter is executed when the node process execution is over -(registered via `insight.on('close', dumpHistogram`). Invoke it as: +The `map` is a global variable shared inside of the Insight script that allows the code to share data between the `insight.on('enter')` function and the `dumpHistogram` function. +The latter is executed when the node process execution is over (registered via `insight.on('close', dumpHistogram`). Invoke it as: + ```shell $JAVA_HOME/bin/node --experimental-options --insight=function-histogram-tracing.js --js.print -e "print('The result: ' + 6 * 7)" The result: 42 @@ -120,9 +114,7 @@ The result: 42 ## Polyglot Tracing -The previous examples were written in JavaScript, but due to GraalVM's polyglot -nature, you can take the same instrument and use it in a program written in, -e.g., the Ruby language. +The previous examples were written in JavaScript, but due to GraalVM's polyglot nature, you can take the same instrument and use it in a program written in, e.g., the Ruby language. 1. Create the _source-trace.js_ file: ```javascript @@ -146,7 +138,7 @@ Hello from GraalVM Ruby! It is necessary to start the Ruby launcher with the `--polyglot` parameter, as the _source-tracing.js_ script remains written in JavaScript. A user can instrument any language on top of GraalVM, but also the Insight scripts can be -written in any of the GraalVM supported languages (implemented with the [Truffle language implementation framework](../graalvm-as-a-platform/truffle-framework/README.md)). +written in any of the GraalVM supported languages (implemented with the [Truffle language implementation framework](../../truffle/docs/README.md)). 1. Create the _source-tracing.rb_ Ruby file: ```ruby @@ -178,10 +170,9 @@ With Ruby: 42 ## Inspecting Values -GraalVM Insight not only allows one to trace where the program execution is happening, -it also offers access to values of local variables and function arguments during -program execution. You can, for example, write an instrument that shows the value of -argument `n` in the function `fib`: +GraalVM Insight not only allows one to trace where the program execution is happening, it also offers access to values of local variables and function arguments during program execution. +You can, for example, write an instrument that shows the value of argument `n` in the function `fib`: + ```javascript insight.on('enter', function(ctx, frame) { print('fib for ' + frame.n); @@ -191,9 +182,9 @@ insight.on('enter', function(ctx, frame) { }); ``` -This instrument uses the second function argument, `frame`, to get access to values of -local variables inside every instrumented function. The above script -also uses `rootNameFilter` to apply its hook only to the function named `fib`: +This instrument uses the second function argument, `frame`, to get access to values of local variables inside every instrumented function. +The above script also uses `rootNameFilter` to apply its hook only to the function named `fib`: + ```javascript function fib(n) { if (n < 1) return 0; @@ -203,9 +194,8 @@ function fib(n) { print("Two is the result " + fib(3)); ``` -When the instrument is stored in a `fib-trace.js` file and the actual code is in -`fib.js`, invoking the following command yields detailed information about the -program execution and parameters passed between function invocations: +When the instrument is stored in a `fib-trace.js` file and the actual code is in `fib.js`, invoking the following command yields detailed information about the program execution and parameters passed between function invocations: + ```shell $JAVA_HOME/bin/node --experimental-options --insight=fib-trace.js --js.print fib.js fib for 3 diff --git a/docs/tools/ideal-graph-visualizer.md b/docs/tools/ideal-graph-visualizer.md index 8c2ab3321b41..ac85fd3b9bf1 100644 --- a/docs/tools/ideal-graph-visualizer.md +++ b/docs/tools/ideal-graph-visualizer.md @@ -7,13 +7,17 @@ permalink: /tools/igv/ # Ideal Graph Visualizer -Ideal Graph Visualizer (IGV) is a developer tool allowing users to analyze compilation -graphs and investigate performance issues. The tool is essential for any -language implementers building on top of **Oracle GraalVM Enterprise Edition**. It is -available as a separate download on [Oracle Technology Network](https://www.oracle.com/technetwork/oracle-labs/program-languages/downloads/index.html) and requires accepting the Oracle Technology Network Developer License. +* [Browsing Graphs](#browsing-graphs) +* [Viewing Source Code](#viewing-source-code) +* [Dumping Graphs](#dumping-graphs) + +Ideal Graph Visualizer (IGV) is a developer tool allowing users to analyze compilation graphs and investigate performance issues. +The tool is essential for any language implementers building on top of **Oracle GraalVM Enterprise Edition**. +It is available as a separate download on [Oracle Technology Network](https://www.oracle.com/downloads/graalvm-downloads.html) and requires accepting the Oracle Technology Network Developer License. IGV is developed to view and inspect intermediate representation graphs -- a language-independent intermediate representation (IR) between the source -language and the machine code, generated by the compiler. See [Dumping Graphs](/tools/igv/#dumping-graphs) below. +language and the machine code, generated by the compiler. +See [Dumping Graphs](#dumping-graphs) below. 1. Unzip the downloaded package and enter `bin` directory: ```shell @@ -46,7 +50,8 @@ and connect the `Test.rb` script to the running IGV: gu list ruby --jvm --polyglot --vm.Dgraal.Dump=:1 --vm.Dgraal.PrintGraph=Network Test.rb ``` -This causes GraalVM Enterprise to dump compiler graphs in the IGV format over the network to an IGV process listening on `127.0.0.1:4445`. Once the connection is made, you are able to see the graphs in the Outline window. +This causes GraalVM Enterprise to dump compiler graphs in the IGV format over the network to an IGV process listening on `127.0.0.1:4445`. +Once the connection is made, you are able to see the graphs in the Outline window. Find, e.g., the `java.lang.String.char(int)` folder and open its After Parsing graph by double-clicking. If the node has `sourceNodePosition` property, then the Processing window will attempt to display its location and the entire stacktrace. @@ -58,57 +63,48 @@ Select a node in the graph and press the Go to Source button in the Stack View w ![](img/IGV_add_source.png) -Graphs navigation is also available from the Context menu, enabled by focusing -and right-clicking a specific graph node. The Extract Nodes option will re-render -a graph and display only the selected nodes and their neighbors. +Graphs navigation is also available from the Context menu, enabled by focusing and right-clicking a specific graph node. +The Extract Nodes option will re-render a graph and display only the selected nodes and their neighbors. ![](img/IGV_context_menu.png) -If the graph is larger than the screen, manipulate with the Satellite view button -in the main toolbar to move the viewport rectangle. +If the graph is larger than the screen, manipulate with the Satellite view button in the main toolbar to move the viewport rectangle. ![](img/IGV_satellite_view.png) -For user preference, the graph color scheme is adjustable by editing -the Coloring filter, enabled by default in the left sidebar. +For user preference, the graph color scheme is adjustable by editing the Coloring filter, enabled by default in the left sidebar. ## Viewing Source Code -Source code views can be opened in manual and assisted modes. Once you select a node -in the graph view, the Processing view will open. If the IGV knows where the source code -for the current frame is, the green Go to Source arrow is enabled. If the IGV does not -know where the source is, the line is greyed out and a Looking Glass button appears. +Source code views can be opened in manual and assisted modes. +Once you select a node in the graph view, the Processing view will open. +If the IGV knows where the source code for the current frame is, the green Go to Source arrow is enabled. +If the IGV does not know where the source is, the line is greyed out and a Looking Glass button appears. ![](img/IGV_add_source.png) Press it and select Locate in Java project to locate the correct project in the dialog. The IGV hides projects which do not contain the required source file. The Source Collections serves to display the stand alone roots added by "Add root of sources" general action. -If the source is located using the preferred method (i.e., from a Java project), -its project can be later managed on the Project tab. That one is initially hidden, -but you can display the list of opened projects using Window -> Projects. +If the source is located using the preferred method (i.e., from a Java project), its project can be later managed on the Project tab. +That one is initially hidden, but you can display the list of opened projects using Window -> Projects. ## Dumping Graphs -The IGV tool is developed to allow GraalVM Enterprise language implementers -to optimize their languages assembled with the [Language Implentation Framework](/graalvm-as-a-platform/language-implementation-framework/). As a development -tool it should not be installed to production environments. - -To dump the GraalVM compiler graphs from an embedded Java application to the IGV, -you need to add options to GraalVM-based processes. Depending on the language/VM -used, you may need to prefix the options by `--vm`. See the particular -language's documentation for the details. The main option to add is -`-Dgraal.Dump=:1`. This will dump graphs in an IGV readable format to the local -file system. To send the dumps directly to the IGV over the network, add -`-Dgraal.PrintGraph=Network` when starting a GraalVM instance. Optionally a -port can be specified. Then dumps are sent to the IGV from the running GraalVM on -localhost. If the IGV does not listen on localhost, Options -> Ideal Graph Settings| -Accept Data From Network can be checked. If there is not an IGV instance -listening on `127.0.0.1` or it cannot be connected to, the dumps will be -redirected to the local file system. The file system location is `graal_dumps/` -under the current working directory of the process and can be changed with the -`-Dgraal.DumpPath` option. - -In case an older GraalVM Enterprise is used, you may need to explicitly request that dumps -include the `nodeSourcePosition` property. This is done by adding the -`-XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints` options. +The IGV tool is developed to allow GraalVM Enterprise language implementers to optimize their languages assembled with the [Language Implentation Framework](../../truffle/docs/README.md). +As a development tool it should not be installed to production environments. + +To dump the GraalVM compiler graphs from an embedded Java application to the IGV, you need to add options to GraalVM-based processes. +Depending on the language/VM used, you may need to prefix the options by `--vm`. +See the particular language's documentation for the details. +The main option to add is `-Dgraal.Dump=:1`. +This will dump graphs in an IGV readable format to the local file system. +To send the dumps directly to the IGV over the network, add `-Dgraal.PrintGraph=Network` when starting a GraalVM instance. +Optionally a port can be specified. +Then dumps are sent to the IGV from the running GraalVM on localhost. +If the IGV does not listen on localhost, Options -> Ideal Graph Settings|Accept Data From Network can be checked. +If there is not an IGV instance listening on `127.0.0.1` or it cannot be connected to, the dumps will be redirected to the local file system. +The file system location is `graal_dumps/` under the current working directory of the process and can be changed with the `-Dgraal.DumpPath` option. + +In case an older GraalVM Enterprise is used, you may need to explicitly request that dumps include the `nodeSourcePosition` property. +This is done by adding the `-XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints` options. diff --git a/docs/tools/lsp.md b/docs/tools/lsp.md index f831f89238ad..134bd71eeaad 100644 --- a/docs/tools/lsp.md +++ b/docs/tools/lsp.md @@ -7,13 +7,13 @@ permalink: /tools/lsp/ # Language Server Protocol -GraalVM supports [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for guest languages. It provides features like code-completion, find usages and alike for the client tools -- IDEs like Visual Studio Code. +GraalVM supports [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for guest languages. +It provides features like code-completion, find usages and alike for the client tools -- IDEs like Visual Studio Code. To start the GraalVM Language Server, pass the `--lsp` option to the command line launcher as in the following example with a Node.js application. -Note: The GraalVM Language Server is offered as a technology preview and requires the -user to pass the `--experimental-options` option for its activation. +Note: The GraalVM Language Server is offered as a technology preview and requires the user to pass the `--experimental-options` option for its activation. ```shell node --experimental-options --lsp app.js @@ -23,7 +23,8 @@ Example app listening on port 3000! ![](img/vscode_cc_1.png) _GraalVM Enterprise-provided code completion for R script, part of the Node.js Polyglot application_ -The GraalVM Language Server itself does not provide the static data usually gathered by parsing the application sources (as these data are sometimes fuzzy in the cases of dynamic languages). Instead, the Language Server was designed to provide the accurate dynamic data gathered from the application runtime. +The GraalVM Language Server itself does not provide the static data usually gathered by parsing the application sources (as these data are sometimes fuzzy in the cases of dynamic languages). +Instead, the Language Server was designed to provide the accurate dynamic data gathered from the application runtime. However, the Language Server could delegate to the existing language servers written specially for the particular languages (using the `--lsp.Delegates` launcher option) and merge the static data returned from these servers with its own dynamic data to a single result. diff --git a/docs/tools/profiling.md b/docs/tools/profiling.md index f5cc19a9e5f3..074829129442 100644 --- a/docs/tools/profiling.md +++ b/docs/tools/profiling.md @@ -7,17 +7,13 @@ permalink: /tools/profiling/ # Profiling Command Line Tools -GraalVM **profiling command line tools** help you optimize your code -through analysis of CPU and memory usage. +GraalVM **profiling command line tools** help you optimize your code through analysis of CPU and memory usage. -Most applications spend 80% of their runtime in 20% of the code. For this -reason, to optimize the code, it is essential to know where the application -spends its time. In this section, we use an example application to demonstrate -the three main profiling capabilities that GraalVM offers: CPU Tracer, CPU -Sampler, and Memory Tracer. +Most applications spend 80% of their runtime in 20% of the code. +For this reason, to optimize the code, it is essential to know where the application spends its time. +In this section, we use an example application to demonstrate the three main profiling capabilities that GraalVM offers: CPU Tracer, CPU Sampler, and Memory Tracer. -This example application uses a basic prime -number calculator based on the [Sieve of Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) +This example application uses a basic prime number calculator based on the [Sieve of Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) algorithm. 1. Copy the following code into a new file named `primes.js`: @@ -90,7 +86,7 @@ algorithm. Total Time: Time spent somewhere on the stack. ---------------------------------------------------------------------------------------------------- Thread[main,5,main] - Name | Total Time || Self Time || Location + Name | Total Time || Self Time || Location ---------------------------------------------------------------------------------------------------- accept | 7330ms 88.8% || 7330ms 88.8% || primes.js~13-22:191-419 :program | 8250ms 100.0% || 420ms 5.1% || primes.js~1-46:0-982 @@ -101,19 +97,18 @@ algorithm. ---------------------------------------------------------------------------------------------------- ``` By default the sampler prints an execution time histogram for each JavaScript function. - You can produce a flame graph in SVG format by doing + You can produce a flame graph in SVG format by doing ```shell js primes.js --cpusampler --cpusampler.Output=flamegraph --cpusampler.OutputFile=primes.svg ``` which should produce something like this - + ![](img/profiler_flamegraph.png) - + You can zoom into the graph by clicking on elements. - By default, CPU sampling takes a sample every 10 milliseconds. From the - result, we can see that roughly 89% of the time is spent - in the `DivisibleByFilter.accept` function. + By default, CPU sampling takes a sample every 10 milliseconds. + From the result, we can see that roughly 89% of the time is spent in the `DivisibleByFilter.accept` function. ```javascript accept(n) { @@ -129,8 +124,7 @@ algorithm. ``` Now use the CPU Tracer to collect execution counts of each statement: -4. Run `js primes.js --cputracer --cputracer.TraceStatements --cputracer.FilterRootName=*accept` -to collect execution counts for all statements in methods ending with `accept`: +4. Run `js primes.js --cputracer --cputracer.TraceStatements --cputracer.FilterRootName=*accept` to collect execution counts for all statements in methods ending with `accept`: ```shell js primes.js --cputracer --cputracer.TraceStatements --cputracer.FilterRootName=*accept Computed 5000 prime numbers. The last 5 are 48563,48571,48589,48593,48611. @@ -154,14 +148,10 @@ to collect execution counts for all statements in methods ending with `accept`: ----------------------------------------------------------------------------------------- ``` - The output shows execution counters for each statement, instead of timing - information. Tracing histograms often provides insights into the behavior - of the algorithm that needs optimization. + The output shows execution counters for each statement, instead of timing information. + Tracing histograms often provides insights into the behavior of the algorithm that needs optimization. -5. Run `js primes.js --experimental-options --memtracer` to display source code locations and -counts of reported allocations. Note that the Memory Tracer tool for capturing allocations is currently an -experimental feature in GraalVM. As such, `--memtracer` must -be preceded by the `--experimental-options` command line option. +5. Run `js primes.js --experimental-options --memtracer` to display source code locations and counts of reported allocations. Note that the Memory Tracer tool for capturing allocations is currently an experimental feature in GraalVM. As such, `--memtracer` must be preceded by the `--experimental-options` command line option. ```shell js primes.js --experimental-options --memtracer Computed 5000 prime numbers. The last 5 are 48563,48571,48589,48593,48611. @@ -179,21 +169,15 @@ be preceded by the `--experimental-options` command line option. ``` - This output shows the number of allocations which were recorded per function. - For each prime number that was computed, the program allocates one object in - `next` and one in `constructor` of `DivisibleByFilter`. Allocations are recorded - independently of whether they could get eliminated by the compiler. + This output shows the number of allocations which were recorded per function. For each prime number that was computed, the program allocates one object in `next` and one in `constructor` of `DivisibleByFilter`. + Allocations are recorded independently of whether they could get eliminated by the compiler. - The GraalVM compiler is particularly powerful in optimizing allocations and can push - allocations into infrequent branches to increase execution performance. The - GraalVM team plans to add information about memory optimizations to the - memory tracer in the future. + The GraalVM compiler is particularly powerful in optimizing allocations and can push allocations into infrequent branches to increase execution performance. + The GraalVM team plans to add information about memory optimizations to the memory tracer in the future. ## Tools Options -Use the `--help:tools` option in all guest language launchers to display -reference information for CPU Sampler, CPU Tracer, and Memory Tracer. - -The current set of available options is as follows: +Use the `--help:tools` option in all guest language launchers to display reference information for CPU Sampler, CPU Tracer, and Memory Tracer. +The current set of available options is as follows. ### CPU Sampler Options diff --git a/docs/tools/visualvm.md b/docs/tools/visualvm.md index fd9a18b21e7c..cb34b024619e 100644 --- a/docs/tools/visualvm.md +++ b/docs/tools/visualvm.md @@ -21,66 +21,59 @@ currently available: To start VisualVM, execute `jvisualvm`. Immediately after startup, the tool shows all locally running Java processes in the Applications area, including the VisualVM process, itself. ### Capture a Heap Dump -To capture a heap dump of, for example, a Ruby application for later analysis, -start your application and let it run for a few seconds to warm up. Then -right-click its process in VisualVM and invoke the Heap Dump action. A -new heap viewer for the Ruby process opens. - -__Note:__ [Native Image](../reference-manual/native-image/README.md) does not implement the JVMTI agent, so triggering heap dump creation from the Applications area is impossible. Apply the `-H:+AllowVMInspection` flag with the `native-image` tool for native image processes. This way your application will handle signals and capture a heap dump when it receives the SIGUSR1 signal. The guest language REPL process must be started also with the `--jvm` flag to monitor it using VisualVM. This functionality is available with [GraalVM Enterprise Edition](https://www.oracle.com/downloads/graalvm-downloads.html). It is not available in GraalVM Community Edition. See the [Generating Native Heap Dumps](../reference-manual/native-image/NativeImageHeapdumpEnterprise.md) page for details on capturing heap dumps from a native image process. +To capture a heap dump of, for example, a Ruby application for later analysis, start your application and let it run for a few seconds to warm up. +Then right-click its process in VisualVM and invoke the Heap Dump action. +A new heap viewer for the Ruby process opens. + +__Note:__ [Native Image](../reference-manual/native-image/README.md) does not implement the JVMTI agent, so triggering heap dump creation from the Applications area is impossible. +Apply the `-H:+AllowVMInspection` flag with the `native-image` tool for native image processes. +This way your application will handle signals and capture a heap dump when it receives the SIGUSR1 signal. +The guest language REPL process must be started also with the `--jvm` flag to monitor it using VisualVM. +This functionality is available with [GraalVM Enterprise Edition](https://www.oracle.com/downloads/graalvm-downloads.html). +It is not available in GraalVM Community Edition. +See the [Generating Native Heap Dumps](../reference-manual/native-image/NativeImageHeapdumpEnterprise.md) page for details on capturing heap dumps from a native image process. ### Analyzing Objects -Initially the Summary view for the Java heap is displayed. To analyze the Ruby -heap, click the leftmost (Summary) dropdown in the Heap Viewer toolbar, choose -the Ruby Heap scope and select the Objects view. Now the heap viewer displays -all Ruby heap objects, aggregated by their type. +Initially the Summary view for the Java heap is displayed. +To analyze the Ruby heap, click the leftmost (Summary) dropdown in the Heap Viewer toolbar, choose the Ruby Heap scope and select the Objects view. +Now the heap viewer displays all Ruby heap objects, aggregated by their type. Expand the Proc node in the Results view to see a list of objects of this type. -Each object displays its logical value as provided by the underlying -implementation. Expand the objects to access their variables and references, -where available. +Each object displays its logical value as provided by the underlying implementation. +Expand the objects to access their variables and references, where available. ![](img/HeapViewer_objects.png) -Now enable the Preview, Variables, and References details by clicking the buttons -in the toolbar, and select the individual _ProcType_ objects. Where available, the -Preview view shows the corresponding source fragment, the Variables view shows -variables of the object, and the References view shows objects referring to the -selected object. +Now enable the Preview, Variables, and References details by clicking the buttons in the toolbar, and select the individual _ProcType_ objects. +Where available, the Preview view shows the corresponding source fragment, the Variables view shows variables of the object, and the References view shows objects referring to the selected object. -Last, use the Presets dropdown in the Heap Viewer toolbar to switch the view -from All Objects to Dominators or GC Roots. To display the heap dominators, -retained sizes must be computed first, which can take a few minutes for the -_server.rb_ example. Select the Objects aggregation in the toolbar to view the -individual dominators or GC roots. +Last, use the Presets dropdown in the Heap Viewer toolbar to switch the view from All Objects to Dominators or GC Roots. +To display the heap dominators, retained sizes must be computed first, which can take a few minutes for the _server.rb_ example. +Select the Objects aggregation in the toolbar to view the individual dominators or GC roots. ![](img/HeapViewer_objects_dominators.png) ### Analyzing Threads -Click the leftmost dropdown in the Heap Viewer toolbar and select the Threads -view for the Ruby heap. The heap viewer now displays the Ruby thread stack -trace, including local objects. The stack trace can alternatively be displayed -textually by clicking the HTML toolbar button. +Click the leftmost dropdown in the Heap Viewer toolbar and select the Threads view for the Ruby heap. +The heap viewer now displays the Ruby thread stack trace, including local objects. The stack trace can alternatively be displayed textually by clicking the HTML toolbar button. ![](img/HeapViewer_thread.png) ### Reading JFR Snapshots -The VisualVM tool bundled with GraalVM 19.2.x and later has the ability to read JFR snapshots -- snapshots taken with JDK Flight Recorder (previously Java Flight Recorder). JFR is a tool for collecting -diagnostic and profiling data about a running Java application. It is integrated -into the Java Virtual Machine (JVM) and causes almost no performance overhead, -so it can be used even in heavily loaded production environments. +The VisualVM tool bundled with GraalVM 19.2.x and later has the ability to read JFR snapshots -- snapshots taken with JDK Flight Recorder (previously Java Flight Recorder). +JFR is a tool for collecting diagnostic and profiling data about a running Java application. +It is integrated into the Java Virtual Machine (JVM) and causes almost no performance overhead, so it can be used even in heavily loaded production environments. To install the JFR support, released as a plugin: 1. Run `/bin/jvisualvm` to start VisualVM; 2. Navigate to Tools > Plugins > Available Plugins to list all available plugins, then install the _VisualVM-JFR_ and _VisualVM-JFR-Generic_ modules. -The JFR snapshots can be opened using either the File > Load action, or by -double-clicking the JFR Snapshots node and adding the snapshot into the JFR -repository, permanently. Please follow the documentation for your Java version to -create JFR snapshots. +The JFR snapshots can be opened using either the File > Load action, or by double-clicking the JFR Snapshots node and adding the snapshot into the JFR +repository, permanently. +Please follow the documentation for your Java version to create JFR snapshots. -The JFR viewer reads all JFR snapshots created from Java 7 onward, and presents the data in typical -VisualVM views familiar to the tool users. +The JFR viewer reads all JFR snapshots created from Java 7 onward, and presents the data in typical VisualVM views familiar to the tool users. ![](img/visualvm_jfr.png) @@ -109,7 +102,4 @@ usage, etc. * Recording tab - lists the recording settings and basic snapshot telemetry like number of events, total recording time, etc. -Note: the support of JDK Flight Recorder is currently experimental. Some advanced features like -analyzing JVM internals, showing event stack traces, or support for creating JFR -snapshots from live processes are not available in this preview version and will -be addressed incrementally in the following releases. +Note: The support of JDK Flight Recorder is currently experimental. Some advanced features like analyzing JVM internals, showing event stack traces, or support for creating JFR snapshots from live processes are not available in this preview version and will be addressed incrementally in the following releases. diff --git a/docs/tools/vscode/graalvm/README.md b/docs/tools/vscode/graalvm/README.md index 2f0ba532c380..7e547ea330c0 100644 --- a/docs/tools/vscode/graalvm/README.md +++ b/docs/tools/vscode/graalvm/README.md @@ -192,7 +192,7 @@ Open the _launch.json_ file and click the Add Configuration... button in the bot 5. Generate load to the running process to invoke more code and generate the best configuration. Once all possible execution paths have been executed, terminate the process. At this point the Native Image agent dumps the collected configuration to the selected output directory. -Once the configuration for Native Image has been generated, follow the documentation on how to [generate a native image for a project](https://www.graalvm.org/reference-manual/native-image/#build-a-native-image) from the command line, or how to [build native images right from VS Code](../micronaut/README.md#generate-native-images-of-micronaut-projects). +Once the configuration for Native Image has been generated, follow the documentation on how to [generate a native image for a project](https://www.graalvm.org/reference-manual/native-image#build-a-native-image) from the command line, or how to [build native images right from VS Code](../micronaut/README.md#generate-native-images-of-micronaut-projects). ## Native Image Debugger @@ -216,7 +216,7 @@ This brings the visual Java tooling to VS Code. ![VisualVM and VS Code Integration](images/vscode_visualvm.png) -To get started, you need to get the latest stable GraalVM release using the **Download & Install GraalVM** action from the **Gr** activity view, as described in the [Installation and Setup](README.md#installation-and-setup) section. +To get started, you need to get the latest stable GraalVM release using the **Download & Install GraalVM** action from the **Gr** activity view, as described in the [Installation and Setup](#installation-and-setup) section. Make sure the GraalVM is set as **active**. Once a GraalVM installation is set as active, the Command Palette contains the following commands related to VisualVM: @@ -461,7 +461,7 @@ For example, to connect to the Chrome Dev Tools protocol port, the content of th Alternatively, to pass the `--polyglot` option to any of the existing application launchers, add the `runtimeArgs` attribute containing the `--polyglot` value to their respective debug configurations. -> Note: In some cases (polyglot application calls Java or R, or native launcher accesses languages installed with `gu` without [rebuilding images](https://www.graalvm.org/reference-manual/graalvm-updater/#component-uninstallation)), also passing the `--jvm` option is necessary. +> Note: In some cases (polyglot application calls Java or R, or native launcher accesses languages installed with `gu` without [rebuilding images](https://www.graalvm.org/reference-manual/graalvm-updater#component-uninstallation)), also passing the `--jvm` option is necessary. ![Image Debug Configuration for Python](images/polyglot-debug-config.png) @@ -502,14 +502,14 @@ GraalVM supports smart editing features of development tools used to create gues This allows you to attach compatible development tools such as VS Code to GraalVM and to get features like auto complete, go to declaration, or documentation on hover. Currently, [GraalVM's Language Server Protocol](https://www.graalvm.org/tools/lsp/) implementation supports the following services: -* [Text Document Synchronization](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_synchronization) -* [Hover Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover) -* [Completion Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion) -* [Signature Help Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp) -* [Document Highlight Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_documentHighlight) -* [Code Action Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction) -* [Code Lens Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeLens) -* [Execute Command Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand) +* [Text Document Synchronization](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_synchronization) +* [Hover Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_hover) +* [Completion Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_completion) +* [Signature Help Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_signatureHelp) +* [Document Highlight Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_documentHighlight) +* [Code Action Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_codeAction) +* [Code Lens Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#textDocument_codeLens) +* [Execute Command Provider](https://microsoft.github.io/language-server-protocol/specifications/specification-current#workspace_executeCommand) > Note: The Language Server Protocol is offered as a technology preview and requires to pass the `--experimental-options` option for its activation. @@ -552,7 +552,7 @@ Once the `solargraph` gem is installed, the Ruby Language Server is automaticall ### Additional Editor Features -Since the easy writing of [polyglot](https://www.graalvm.org/docs/reference-manual/polyglot) applications is one of the defining features of GraalVM, the code completion invoked inside JavaScript sources provides items for `Polyglot.eval(...)`, `Polyglot.evalFile(...)`, and `Java.type(...)` calls. +Since the easy writing of [polyglot applications](https://www.graalvm.org/reference-manual/polyglot-programming/) is one of the defining features of GraalVM, the code completion invoked inside JavaScript sources provides items for `Polyglot.eval(...)`, `Polyglot.evalFile(...)`, and `Java.type(...)` calls. ![Image Code Completion](images/code-completion-js.png) diff --git a/docs/tools/vscode/micronaut/README.md b/docs/tools/vscode/micronaut/README.md index d5e98099cd1b..e9be98e88476 100644 --- a/docs/tools/vscode/micronaut/README.md +++ b/docs/tools/vscode/micronaut/README.md @@ -11,7 +11,7 @@ permalink: /tools/vscode/micronaut-extension/ The extension is Technology Preview. The extension also enables the [Micronaut Launch](https://micronaut.io/launch/) application that allows you to create Micronaut projects through an interface inside VS Code, in addition to using the console CLI. -There are, of course, other ways to create a new Micronaut application. If you provide a path to the [Micronaut CLI installation](https://micronaut-projects.github.io/micronaut-starter/latest/guide/#installation), you can create a project using the `mn` executable. If you prefer not to install the Micronaut CLI, and you are running on Linux or macOS, you can `curl` the project. Lastly, you can navigate to Micronaut Launch in a browser, create a new project, download it and open in VS Code. +There are, of course, other ways to create a new Micronaut application. If you provide a path to the [Micronaut CLI installation](https://micronaut-projects.github.io/micronaut-starter/latest/guide#installation), you can create a project using the `mn` executable. If you prefer not to install the Micronaut CLI, and you are running on Linux or macOS, you can `curl` the project. Lastly, you can navigate to Micronaut Launch in a browser, create a new project, download it and open in VS Code. In combination with the [GraalVM Tools for Java extension](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.graalvm), you can run Micronaut projects on GraalVM, and debug them directly from the VS Code development environment with different debugging protocols enabled with the extension. This extension for Micronaut was also developed to help developers build native images directly from VS Code. diff --git a/docs/tools/vscode/vscode.md b/docs/tools/vscode/vscode.md index a5dddceafd15..0425572de95e 100644 --- a/docs/tools/vscode/vscode.md +++ b/docs/tools/vscode/vscode.md @@ -8,17 +8,17 @@ permalink: /tools/vscode/ # Visual Studio Code Extensions Here you will learn about GraalVM integration into [Visual Studio Code (VS Code)](https://code.visualstudio.com/). -VS Code is an integrated development environment that provides the embedded Git and GitHub control, syntax highlighting, code refactoring, and much more. +VS Code is an integrated development environment that provides the embedded Git and GitHub control, syntax highlighting, code refactoring, and much more. The following extensions are available for download from Visual Studio Code Marketplace: -- [**GraalVM Tools for Java**](/tools/vscode/graalvm-extension/) provides a full-fledged support for the Java language and, additionally, enables a polyglot environment in VS Code, making it a comfortable and convenient integrated development environment to work with. +- [**GraalVM Tools for Java**](graalvm/README.md) provides a full-fledged support for the Java language and, additionally, enables a polyglot environment in VS Code, making it a comfortable and convenient integrated development environment to work with. Users can edit, run and debug either single-language applications written in any of the GraalVM-supported languages (Java, JS, Ruby, R, and Python), or polyglot applications without the need to install any other additional extensions. The extension also offers the installation wizard that allows to download and install GraalVM and its optional features directly from the user interface. Get the extension from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.graalvm). -- [**GraalVM Tools for Micronaut**](/tools/vscode/micronaut-extension/) provides full support for developing applications based on the [Micronaut framework](https://micronaut.io/). The extension also enables the [Micronaut Launch](https://micronaut.io/launch/) application that allows you to create Micronaut projects through an interface inside VS Code, in addition to using the console CLI. This extension is integrated with GraalVM to provide all Native Image capabilities. You can generate native images directly from VS Code, and deploy them to a Docker Registry. Get the extension from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.micronaut). +- [**GraalVM Tools for Micronaut**](micronaut/README.md) provides full support for developing applications based on the [Micronaut framework](https://micronaut.io/). The extension also enables the [Micronaut Launch](https://micronaut.io/launch/) application that allows you to create Micronaut projects through an interface inside VS Code, in addition to using the console CLI. This extension is integrated with GraalVM to provide all Native Image capabilities. You can generate native images directly from VS Code, and deploy them to a Docker Registry. Get the extension from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.micronaut). -- [**GraalVM Extension Pack for Java**](/tools/vscode/graalvm-extension-pack/) is a collection of extensions that helps users write, debug and test Java, JavaScript, Python, Ruby, R and polyglot applications running on GraalVM, either standalone or using the Micronaut framework. +- [**GraalVM Extension Pack for Java**](graalvm-pack/README.md) is a collection of extensions that helps users write, debug and test Java, JavaScript, Python, Ruby, R and polyglot applications running on GraalVM, either standalone or using the Micronaut framework. GraalVM Extension Pack for Java bundles [GraalVM Tools for Java](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.graalvm), [GraalVM Tools for Micronaut](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.micronaut), and [Apache NetBeans Language Server](https://marketplace.visualstudio.com/items?itemName=asf.apache-netbeans-java) extensions. Get the extension pack from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=oracle-labs-graalvm.graalvm-pack). As of GraalVM 21.2.0, the GraalVM Tools for Java extension introduced a new feature - the integration with VisualVM (https://visualvm.github.io), which is the all-in-one Java (and polyglot) monitoring and troubleshooting tool. From 15d324e0a423598cc162438702640bdfe6a36a40 Mon Sep 17 00:00:00 2001 From: Olga Gupalo Date: Mon, 13 Dec 2021 18:22:50 +0200 Subject: [PATCH 4/4] Use rel paths on URLs instead of permalinks --- truffle/docs/AOTOverview.md | 2 +- .../docs/AuxiliaryEngineCachingEnterprise.md | 2 +- truffle/docs/DynamicObjectModel.md | 2 +- truffle/docs/InteropMigration.md | 2 +- truffle/docs/LanguageTutorial.md | 2 +- truffle/docs/OnStackReplacement.md | 17 ++++++++------- truffle/docs/Optimizing.md | 2 +- truffle/docs/Profiling.md | 2 +- truffle/docs/README.md | 2 +- truffle/docs/StaticObjectModel.md | 21 ++++++++++++------- 10 files changed, 31 insertions(+), 23 deletions(-) diff --git a/truffle/docs/AOTOverview.md b/truffle/docs/AOTOverview.md index d03e1f3ba362..6cc08039af29 100644 --- a/truffle/docs/AOTOverview.md +++ b/truffle/docs/AOTOverview.md @@ -28,7 +28,7 @@ For more information see [TruffleLanguage.patchContext](https://www.graalvm.org/ ### Code sharing within the same Isolate/Process A polyglot engine can be used in order to determine the scope of code sharing between contexts. -An example of how that can be done can be found in the [reference manual](https://www.graalvm.org/reference-manual/embed-languages/#code-caching-across-multiple-contexts). +An example of how that can be done can be found in the [reference manual](../../docs/reference-manual/embedding/embed-languages.md#code-caching-across-multiple-contexts). When a language is initialized for a polyglot context, a new language instance is requested from an engine. If the language supports [ContextPolicy.SHARED](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.ContextPolicy.html#SHARED), then the language instance will be reused for an engine instance. The source parsing cache is associated with a language instance, so parsing happens once per language instance. diff --git a/truffle/docs/AuxiliaryEngineCachingEnterprise.md b/truffle/docs/AuxiliaryEngineCachingEnterprise.md index fc1e709deae4..3f829d487181 100644 --- a/truffle/docs/AuxiliaryEngineCachingEnterprise.md +++ b/truffle/docs/AuxiliaryEngineCachingEnterprise.md @@ -19,7 +19,7 @@ This includes: 2. Execution and profiling of the guest application in the interpreter. 3. Compilation of the AST to machine code. -Within a single OS process, the work performed during warmup can be shared by specifying an [explicit engine](https://www.graalvm.org/reference-manual/embed-languages/#code-caching-across-multiple-contexts). +Within a single OS process, the work performed during warmup can be shared by specifying an [explicit engine](../../docs/reference-manual/embedding/embed-languages.md#code-caching-across-multiple-contexts). This requires language implementations to disable context-related optimizations to avoid deoptimizations between contexts that share code. Auxiliary engine caching builds upon the mechanism for disabling context-related optimizations and adds the capability to persist an engine with ASTs and optimized machine code to disk. This way, the work performed during warmup can be significantly reduced in the first application context of a new process. diff --git a/truffle/docs/DynamicObjectModel.md b/truffle/docs/DynamicObjectModel.md index f922cbaa220b..ad63e1ae0606 100644 --- a/truffle/docs/DynamicObjectModel.md +++ b/truffle/docs/DynamicObjectModel.md @@ -184,4 +184,4 @@ public abstract class MakePairNode extends BinaryExpressionNode { A high-level description of the object model has been published in [**An Object Storage Model for the Truffle Language Implementation Framework**](http://dl.acm.org/citation.cfm?id=2647517). -See [Truffle documentation](https://github.com/oracle/graal/tree/master/truffle/docs) and [publications](https://github.com/oracle/graal/blob/master/docs/Publications.md) for more tutorials, presentations, and publications about Truffle and GraalVM. +See [Truffle publications](https://github.com/oracle/graal/blob/master/docs/Publications.md) for more presentations and publications about Truffle and GraalVM. diff --git a/truffle/docs/InteropMigration.md b/truffle/docs/InteropMigration.md index 7baf9f706f45..f311f74db028 100644 --- a/truffle/docs/InteropMigration.md +++ b/truffle/docs/InteropMigration.md @@ -7,7 +7,7 @@ permalink: /graalvm-as-a-platform/language-implementation-framework/InteropMigra # Truffle Interop 2.0 This document is targeted at guest language and tool implementers. -It is recommended to read the [Truffle Library Tutorial](https://github.com/oracle/graal/blob/master/truffle/docs/TruffleLibraries.md) first, before proceeding. +It is recommended to read the [Truffle Library Tutorial](./TruffleLibraries.md) first, before proceeding. ## Motivation diff --git a/truffle/docs/LanguageTutorial.md b/truffle/docs/LanguageTutorial.md index f64a1570b074..a90a8c9811a9 100644 --- a/truffle/docs/LanguageTutorial.md +++ b/truffle/docs/LanguageTutorial.md @@ -19,5 +19,5 @@ Conference on Programming Language Design and Implementation [PLDI 2016](http:// Next Steps: * Start to subclass [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) for your own language implementation. * Fork [SimpleLanguage](https://github.com/graalvm/simplelanguage), a toy language that demonstrates how to use many Truffle features. -* Embed Truffle languages in Java host applications using the [Polyglot API](https://graalvm.org/reference-manual/embed-languages/). +* Embed Truffle languages in Java host applications using the [Polyglot API](../../docs/reference-manual/embedding/embed-languages.md). * Read [GraalVM/Truffle publications](https://github.com/oracle/graal/blob/master/docs/Publications.md). diff --git a/truffle/docs/OnStackReplacement.md b/truffle/docs/OnStackReplacement.md index 722bf2df0161..b178488c66d2 100644 --- a/truffle/docs/OnStackReplacement.md +++ b/truffle/docs/OnStackReplacement.md @@ -1,7 +1,7 @@ --- layout: docs toc_group: truffle -link_title: On-Stack Replacement +link_title: On-Stack Replacement permalink: /graalvm-as-a-platform/language-implementation-framework/OnStackReplacement/ --- # On-Stack Replacement (OSR) @@ -15,7 +15,7 @@ On-stack replacement (OSR) is a technique used in Truffle to "break out" of the Truffle supports OSR for both AST interpreters (i.e., ASTs with `LoopNode`s) and bytecode interpreters (i.e., nodes with dispatch loops). In either case, Truffle uses heuristics to detect when a long-running loop is being interpreted and can perform OSR to speed up execution. -## OSR for AST interpreters +## OSR for AST Interpreters Languages using standard Truffle APIs get OSR for free on Graal. The runtime tracks the number of times a `LoopNode` (created using `TruffleRuntime.createLoopNode(RepeatingNode)`) executes in the interpreter. @@ -25,7 +25,7 @@ When the loop exits in the OSR execution, it returns to the interpreted executio See the `LoopNode` [javadoc](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/nodes/LoopNode.html) for more details. -## OSR for bytecode interpreters +## OSR for Bytecode Interpreters OSR for bytecode interpreters requires slightly more cooperation from the language. A bytecode dispatch node typically looks something like the following: @@ -33,9 +33,9 @@ A bytecode dispatch node typically looks something like the following: ```java class BytecodeDispatchNode extends Node { @CompilationFinal byte[] bytecode; - + ... - + @ExplodeLoop(kind = ExplodeLoop.LoopExplosionKind.MERGE_EXPLODE) Object execute(VirtualFrame frame) { int bci = 0; @@ -81,7 +81,7 @@ The example above can be refactored to support OSR as follows: class BytecodeDispatchNode extends Node implements BytecodeOSRNode { @CompilationFinal byte[] bytecode; @CompilationFinal private Object osrMetadata; - + ... Object execute(VirtualFrame frame) { @@ -161,12 +161,14 @@ Bytecode-based OSR can be tricky to implement. Some debugging tips: See the `BytecodeOSRNode` [javadoc](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/nodes/BytecodeOSRNode.html) for more details. -## Command-line options +## Command-line Options + There are two (experimental) options which can be used to configure OSR: - `engine.OSR`: whether to perform OSR (default: `true`) - `engine.OSRCompilationThreshold`: the number of loop iterations/back-edges required to trigger OSR compilation (default: `100,352`). ## Debugging + OSR compilation targets are marked with `` (or `` where `n` is the dispatch target, in the case of bytecode OSR). These targets can be seen and debugged using standard debugging tools like the compilation log and IGV. For example, in the compilation log, a bytecode OSR entry may look something like: @@ -176,4 +178,3 @@ For example, in the compilation log, a bytecode OSR entry may look something lik ``` See [Debugging](https://github.com/oracle/graal/blob/master/compiler/docs/Debugging.md) for more details on debugging Graal compilations. - diff --git a/truffle/docs/Optimizing.md b/truffle/docs/Optimizing.md index 1824da72f7aa..e8a86116117a 100644 --- a/truffle/docs/Optimizing.md +++ b/truffle/docs/Optimizing.md @@ -577,7 +577,7 @@ The `--engine.TraceCompilation` option also shows CallTarget invalidations with ## Ideal Graph Visualizer -The [Ideal Graph Visualizer (IGV)](https://docs.oracle.com/en/graalvm/enterprise/21/docs/tools/igv/) is a tool to understand Truffle ASTs and the GraalVM compiler graphs. +The [Ideal Graph Visualizer (IGV)](../../docs/tools/ideal-graph-visualizer.md) is a tool to understand Truffle ASTs and the GraalVM compiler graphs. A typical usage is to run with `--vm.Dgraal.Dump=Truffle:1 --vm.Dgraal.PrintGraph=Network`, which will show you Truffle ASTs, guest-language call graphs, and the Graal graphs as they leave the Truffle phase. If the `-Dgraal.PrintGraph=Network` flag is omitted then the dump files are placed in the `graal_dumps` directory, which you should then open in IGV. diff --git a/truffle/docs/Profiling.md b/truffle/docs/Profiling.md index 1435783b2144..c324bf8b1cbe 100644 --- a/truffle/docs/Profiling.md +++ b/truffle/docs/Profiling.md @@ -9,7 +9,7 @@ permalink: /graalvm-as-a-platform/language-implementation-framework/Profiling/ There is no shortage of tools for profiling interpreters written using Truffle. When running in JVM mode you can use standard JVM tooling such as VisualVM, Java Flight Recorder, and Oracle Developer Studio. When running in Native Image you can use `callgrind` from the Valgrind tool suite, and other system tools such as `strace`. As a language running on GraalVM, other GraalVM tools can be used. -For a broad enough definition of profiling, you can also use the [Ideal Graph Visualizer (IGV)](https://docs.oracle.com/en/graalvm/enterprise/21/docs/tools/igv/) and C1 Visualizer to inspect the compiler output. +For a broad enough definition of profiling, you can also use the [Ideal Graph Visualizer (IGV)](../../docs/tools/ideal-graph-visualizer.md) and C1 Visualizer to inspect the compiler output. This guide is less about how to use each tool and more about suggestions for extracting the most useful information from the tools, assuming a basic knowledge of their usage. diff --git a/truffle/docs/README.md b/truffle/docs/README.md index cb063485ac24..ce9d7a63a3c7 100644 --- a/truffle/docs/README.md +++ b/truffle/docs/README.md @@ -50,7 +50,7 @@ Consider reading [these publications](https://github.com/oracle/graal/blob/maste Implementing a language using Truffle offers a way to interoperate with other "Truffle" languages. To learn more about verifying that your language is a valid polyglot citizen, read more about using the [Polyglot TCK](./TCK.md). Somewhat related topics worth exploring are [Truffle Libraries](./TruffleLibraries.md), as well as how to use them to implement a language [interoperability](./InteropMigration.md). -Languages implemented with Truffle can also be embedded in Java host applications using the [Polyglot API](https://graalvm.org/reference-manual/embed-languages/). +Languages implemented with Truffle can also be embedded in Java host applications using the [Polyglot API](../../docs/reference-manual/embedding/embed-languages.md). To better understand how to improve the performance of your language please consult the documentation on [profiling](./Profiling.md) and [optimizing](./Optimizing.md) your language. Also, to better understand how to use Truffle's automated monomorphization feature (i.e., splitting), look at the [related documentation](./splitting/Monomorphization.md). diff --git a/truffle/docs/StaticObjectModel.md b/truffle/docs/StaticObjectModel.md index b19c4041b12e..99cfe6d982f3 100644 --- a/truffle/docs/StaticObjectModel.md +++ b/truffle/docs/StaticObjectModel.md @@ -1,3 +1,9 @@ +--- +layout: docs +toc_group: truffle +link_title: Static Object Model +permalink: /graalvm-as-a-platform/language-implementation-framework/StaticObjectModel/ +--- # Static Object Model This guide demonstrates how to get started with using the [StaticShape](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/staticobject/StaticShape.html) and [StaticProperty](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/staticobject/StaticProperty.html) APIs introduced with GraalVM 21.3.0. @@ -75,7 +81,7 @@ Properties of the parent shape can then be used to access values stored in stati In the following example we create a parent shape identical to the one discussed in [the previous section](#getting-started), then we extend it with a child shape that hides one of the properties of the parent shape. Finally, we demonstrate how the various properties can be accessed. -```java +``` public class Subshapes { public void simpleSubShape(TruffleLanguage language) { // Create a shape @@ -139,7 +145,7 @@ public interface MyStaticObjectFactory { ``` Finally, this is how to allocate the custom static objects: -```java +``` public void customStaticObject(TruffleLanguage language) { StaticProperty property = new DefaultStaticProperty("arg1"); StaticShape shape = StaticShape.newBuilder(language).property(property, Object.class, false).build(MyStaticObject.class, MyStaticObjectFactory.class); @@ -197,8 +203,8 @@ new MyField("property1"); On property access, the Static Object Model performs two types of safety checks: 1. That the [StaticProperty](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/staticobject/StaticProperty.html) method matches the type of the static property. -Example of wrong access: -```java +The example of wrong access: +``` public void wrongMethod(TruffleLanguage language) { StaticShape.Builder builder = StaticShape.newBuilder(language); StaticProperty property = new DefaultStaticProperty("property"); @@ -209,7 +215,7 @@ public void wrongMethod(TruffleLanguage language) { 2. That the object passed to the accessor method matches the shape generated by the builder to which the property is associated, or one of its child shapes. -Example of wrong access: +The example of wrong access: ```java public void wrongShape(TruffleLanguage language) { StaticShape.Builder builder = StaticShape.newBuilder(language); @@ -222,8 +228,9 @@ public void wrongShape(TruffleLanguage language) { ``` While these checks are often useful, they might be redundant if the language implementation already performs them, for example using a verifier. -While the first type of checks (on property type) is very efficient and cannot be disabled, the second type of checks (on the shape) is computationally expensive and can be disabled via a command line argument: -``` +While the first type of checks (on property type) is very efficient and cannot be disabled, the second type of checks (on the shape) is computationally expensive and can be disabled via a command line argument: + +```shell --experimental-options --engine.RelaxStaticObjectSafetyChecks=true ```