This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/master by this push:
new 989a19d Add GraalVM documentation page
989a19d is described below
commit 989a19d44d8ec4857a241ecbb83d882f65af6f64
Author: remm <[email protected]>
AuthorDate: Wed Sep 18 11:25:12 2019 +0200
Add GraalVM documentation page
It seems more appropriate than a wiki page or the readme, and it
describes the process that I used for the ApacheCon presentation. The
downside is that it is more annoying to update.
---
res/tomcat-maven/README.md | 27 +------
webapps/docs/changelog.xml | 7 ++
webapps/docs/graal.xml | 185 +++++++++++++++++++++++++++++++++++++++++++++
webapps/docs/project.xml | 1 +
4 files changed, 194 insertions(+), 26 deletions(-)
diff --git a/res/tomcat-maven/README.md b/res/tomcat-maven/README.md
index 1072faa..b5e54f7 100644
--- a/res/tomcat-maven/README.md
+++ b/res/tomcat-maven/README.md
@@ -80,32 +80,7 @@ oc policy add-role-to-user view system:serviceaccount:$(oc
project -q):default -
## Native Image
-Download Graal native-image and tools.
-```
-export JAVA_HOME=/absolute...path...to/graalvm-ce-19.2.0.1
-export TOMCAT_MAVEN=/absolute...path...to/tomcat-maven
-cd $JAVA_HOME/bin
-./gu install native-image
-```
-As Graal does not support dynamic class loading, all Servlets and support
classes of the webapp, which would traditionally be placed
-in `/WEB-INF/classes` and `/WEB-INF/lib`, must be included as part of the
tomcat-maven build process, so they are packaged into the
-`target/tomcat-maven-1.0.jar`.
-
-Run Tomcat with the agent in full trace mode. The arguments are identical to
regular Tomcat with the addition of the trace agent which attempts to
-intercept all relevant reflection calls.
-```
-cd $TOMCAT_MAVEN
-$JAVA_HOME/bin/java
-agentlib:native-image-agent=trace-output=$TOMCAT_MAVEN/target/trace-file.json
-Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -jar
target/tomcat-maven-1.0.jar
-```
-Then exercise necessary paths of your service with the Tomcat configuration.
Any changes to the Tomcat configuration requires running
-the substrate VM with the agent again.
-
-Generate the final json files using native-image-configuration then use native
image using the generated reflection metadata:
-```
-$JAVA_HOME/bin/native-image-configure generate
--trace-input=$TOMCAT_MAVEN/target/trace-file.json
--output-dir=$TOMCAT_MAVEN/target
-$JAVA_HOME/bin/native-image --no-server --allow-incomplete-classpath
--enable-https
--initialize-at-build-time=org.eclipse.jdt,org.apache.el.parser.SimpleNode,javax.servlet.jsp.JspFactory,org.apache.jasper.servlet.JasperInitializer,org.apache.jasper.runtime.JspFactoryImpl
-H:+JNI -H:+ReportUnsupportedElementsAtRuntime -H:+ReportExceptionStackTraces
-H:EnableURLProtocols=http,https,jar
-H:ConfigurationFileDirectories=$TOMCAT_MAVEN/target/
-H:ReflectionConfigurationFiles=$TOMCAT_MAVEN/tomc [...]
-./tomcat-maven-1.0 -Djava.library.path=$JAVA_HOME/jre/lib/amd64
-Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties
-```
+The Tomcat documentation includes information on using the native-image tool
(docs/graal.html).
Running in a container is possible, an example `DockerfileGraal` is given. To
use a native image in a container that is not identical to the build platform,
the `native-image` call will need to use the additional `--static` parameter
to statically link base libraries (this will then require zlib and glibc
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 48f3408..652eba3 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -54,6 +54,13 @@
</fix>
</changelog>
</subsection>
+ <subsection name="Web Applications">
+ <changelog>
+ <docs>
+ Add base GraalVM documentation. (remm)
+ </docs>
+ </changelog>
+ </subsection>
</section>
<section name="Tomcat 9.0.26 (markt)" rtext="release in progress">
<subsection name="Other">
diff --git a/webapps/docs/graal.xml b/webapps/docs/graal.xml
new file mode 100644
index 0000000..b90817c
--- /dev/null
+++ b/webapps/docs/graal.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="graal.html">
+
+ &project;
+
+ <properties>
+ <title>GraalVM support</title>
+ </properties>
+
+<body>
+
+<section name="Table of Contents">
+<toc/>
+</section>
+
+ <section name="Introduction">
+
+ <p>
+ Tomcat supports using the GraalVM Native Image tool to produce a native
+ binary including the container. This documentation page describes the
+ build process of such an image.
+ </p>
+
+ </section>
+
+ <section name="Setup">
+
+ <p>
+ The native image tool is much easier to use with single JARs, as a result
+ the process will use the Maven shade plugin JAR packaging (fat JAR). The
+ idea is to produce a single JAR that contains all necessary classes from
+ Tomcat, the webapps and all additional dependencies. Although Tomcat has
+ received compatibility fixes to support GraalVM native images, any library
+ may not be compatible and may require replacement code (the GraalVM
+ documentation has more details about this).
+ </p>
+
+ <p>
+ Download and install GraalVM. The first step is then to add the
+ native-image tool.
+ <source>export JAVA_HOME=/absolute...path...to/graalvm-ce-x.y.z
+cd $JAVA_HOME/bin
+./gu install native-image</source>
+ Download the Tomcat Maven packaging from
+ https://github.com/apache/tomcat/tree/master/res/tomcat-maven and place
+ all the files in a folder (named tomcat-maven in this documentation.
+ <source>export TOMCAT_MAVEN=/absolute...path...to/tomcat-maven</source>
+ The build process now requires both Ant and Maven.
+ </p>
+
+ </section>
+
+ <section name="Packaging and Building">
+
+ <p>
+ Inside the tomcat-maven folder, the directory structure is the same as for
+ regular Tomcat. The main configuration files are placed in the conf folder,
+ and if using the default server.xml the webapps are placed in the webapps
+ folder. If using the default server.xml file, some Server listeners have
+ to be removed from the configuration as they are not compatible with native
+ images, such as a JMX listener (JMX is unsupported) and leak prevention
+ listeners (not needed here, and using internal code that does not exist).
+ </p>
+
+ <p>
+ The first step is to build the fat Tomcat JAR with all dependencies.
+ Any JSP in the webapp must all be precompiled and packaged.
+ <source>cd $TOMCAT_MAVEN
+mvn package
+ant -Dwebapp.name=somewebapp -f graal-webapp.ant.xml</source>
+ Dependencies for the webapp should now be added to the main pom.xml,
+ following with building the complete fat JAR.
+ <source>mvn package</source>
+ </p>
+
+ </section>
+
+ <section name="Native image configuration">
+
+ <p>
+ Native images do not support any form of dynamic classloading or
+ reflection unless it is defined explicitly in descriptors. Generating
+ them uses a tracing agent from the GraalVM, and needs additional manual
+ configuration in some cases.
+ </p>
+
+ <p>
+ Run the GraalVM substrate VM using the trace agent:
+ <source>$JAVA_HOME/bin/java\
+
-agentlib:native-image-agent=trace-output=$TOMCAT_MAVEN/target/trace-file.json\
+ -Dcatalina.base=.
-Djava.util.logging.config.file=conf/logging.properties\
+ -jar target/tomcat-maven-1.0.jar</source>
+ </p>
+
+ <p>
+ Now all paths from the webapp that lead to dynamic classloading
+ (ex: Servlet access, websockets, etc) need to be accessed using a script
+ that will exercise the webapp. Servlets may be loaded on startup
+ instead of needing an actual access. Listeners may also be used to load
+ additional classes on startup.
+ </p>
+
+ <p>
+ Once that is done, the VM may be shut down. The descriptors can now be
+ generated from the trace file.
+ <source>$JAVA_HOME/bin/native-image-configure generate\
+ --trace-input=$TOMCAT_MAVEN/target/trace-file.json\
+ --output-dir=$TOMCAT_MAVEN/target</source>
+ At this point, further configuration must be made to add items that are
+ not traced, including: base interfaces, resource bundles, BeanInfo based
+ reflection, etc. Please refer to the Graal documentation for more
+ information on this process.
+ </p>
+
+ </section>
+
+ <section name="Building the native image">
+
+ <p>
+ If everything has been done properly, the native image can now be built
+ using the native-image tool.
+ <source>$JAVA_HOME/bin/native-image --no-server\
+ --allow-incomplete-classpath --enable-https\
+
--initialize-at-build-time=org.eclipse.jdt,org.apache.el.parser.SimpleNode,javax.servlet.jsp.JspFactory,org.apache.jasper.servlet.JasperInitializer,org.apache.jasper.runtime.JspFactoryImpl\
+ -H:+JNI -H:+ReportUnsupportedElementsAtRuntime\
+ -H:+ReportExceptionStackTraces -H:EnableURLProtocols=http,https,jar\
+ -H:ConfigurationFileDirectories=$TOMCAT_MAVEN/target/\
+ -H:ReflectionConfigurationFiles=$TOMCAT_MAVEN/tomcat-reflection.json\
+ -H:ResourceConfigurationFiles=$TOMCAT_MAVEN/tomcat-resource.json\
+ -H:JNIConfigurationFiles=$TOMCAT_MAVEN/tomcat-jni.json\
+ -jar $TOMCAT_MAVEN/target/tomcat-maven-1.0.jar</source>
+ </p>
+
+ <p>
+ Running the native image is then:
+ <source>./tomcat-maven-1.0 -Djava.library.path=$JAVA_HOME/jre/lib/amd64\
+ -Dcatalina.base=.
-Djava.util.logging.config.file=conf/logging.properties</source>
+ </p>
+
+ </section>
+
+ <section name="Compatibility">
+
+ <p>
+ Servlets, JSPs, EL, websockets, the Tomcat container, tomcat-native,
HTTP/2\
+ are all supported out of the box in a native image. However, EL uses
+ BeanInfo reflection which needs manual descriptor configuration.
+ At the time of writing this documentation, JULI is not supported as the
+ log manager configuration property is not supported by Graal, in addition
+ to some static initializer problems, and the regular java.util.logging
+ loggers and implementation should be used instead.
+ </p>
+
+ <p>
+ An a descriptor example, the EL expression
+ <source>${pageContext.servletContext.serverInfo}</source> needs full
+ reflection information on the concrete Jasper page context class, as well
+ as the Catalina Servlet context implementation. Graal error messages
+ during runtime generally indicate which classes are missing reflection
+ as the BeanInfo reported for these will be empty.
+ </p>
+
+ </section>
+
+</body>
+</document>
diff --git a/webapps/docs/project.xml b/webapps/docs/project.xml
index 0fc55bc..b7f8ee8 100644
--- a/webapps/docs/project.xml
+++ b/webapps/docs/project.xml
@@ -75,6 +75,7 @@
<item name="32) WebSocket" href="web-socket-howto.html"/>
<item name="33) Rewrite" href="rewrite.html"/>
<item name="34) CDI 2 and JAX-RS" href="cdi.html"/>
+ <item name="35) GraalVM Support" href="graal.html"/>
</menu>
<menu name="Reference">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
