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 6a3cae6 Update Graal documentation to reflect changes
6a3cae6 is described below
commit 6a3cae6adf866a40eed8df3a571253bc295ec421
Author: remm <r...@apache.org>
AuthorDate: Thu Jun 25 14:57:54 2020 +0200
Update Graal documentation to reflect changes
---
webapps/docs/graal.xml | 70 ++++++++++++++++++++++++++++++++++----------------
1 file changed, 48 insertions(+), 22 deletions(-)
diff --git a/webapps/docs/graal.xml b/webapps/docs/graal.xml
index 0852595..b89dc1d 100644
--- a/webapps/docs/graal.xml
+++ b/webapps/docs/graal.xml
@@ -35,7 +35,7 @@
<section name="Introduction">
<p>
- Tomcat supports using the GraalVM Native Image tool to produce
+ Tomcat supports using the GraalVM/Mandrel Native Image tool to produce
a native binary including the container. This documentation page
describes the build process of such an image.
</p>
@@ -49,21 +49,31 @@
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
+ received compatibility fixes to support 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-javaX-x.y.z
+ Download and install GraalVM or Mandrel.
+ </p>
+
+ <p>
+ If using GraalVM, the first step is then to add the Native Image tool.
+ <source>export JAVA_HOME=/absolute...path...to/graalvm-ce-javaX-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>
+ Mandrel already includes the Native Image tool ready to use, so this
+ step can be skipped. Only JAVA_HOME must be set to the mandrelJDK folder,
+ such as:
+ <source>export
JAVA_HOME=/absolute...path...to/mandrel-javaXX-platform-x.x.x.x</source>
+ </p>
+
+ <p>
+ Download the Tomcat Stuffed module from
+ https://github.com/apache/tomcat/tree/master/modules/stuffed and place
+ all the files in a folder <code>stuffed</code> in this documentation.
+ <source>export TOMCAT_STUFFED=/absolute...path...to/stuffed</source>
The build process now requires both Ant and Maven.
</p>
@@ -72,7 +82,7 @@ cd $JAVA_HOME/bin
<section name="Packaging and Building">
<p>
- Inside the tomcat-maven folder, the directory structure is the same as for
+ Inside the tomcat-stuffed 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.
@@ -81,14 +91,28 @@ cd $JAVA_HOME/bin
<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
+ <source>cd $TOMCAT_STUFFED
mvn package
-ant -Dwebapp.name=somewebapp -f graal-webapp.ant.xml</source>
+ant -Dwebapp.name=somewebapp -f webapp-jspc.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>
+ <p>
+ As it is best to avoid using reflection whenever possible with Ahead of
+ Time compilation, it can be a good idea to generate and compile Tomcat
+ Embedded code out of the main server.xml configuration as well as the
+ context.xml files used to configure the contexts.
+ <source>$JAVA_HOME/bin/java\
+ -Dcatalina.base=.
-Djava.util.logging.config.file=conf/logging.properties\
+ -jar target/tomcat-stuffed-1.0.jar --catalina -generateCode
src/main/java
+mvn package</source>
+ The rest of the process described here will assume this step was done and
+ the <code>--catalina -useGeneratedCode</code> arguments are added to the
+ command lines. If this was not the case, they should be removed.
+ </p>
+
</section>
<section name="Native image configuration">
@@ -103,9 +127,9 @@ ant -Dwebapp.name=somewebapp -f
graal-webapp.ant.xml</source>
<p>
Run the GraalVM substrate VM using the trace agent:
<source>$JAVA_HOME/bin/java\
- -agentlib:native-image-agent=config-output-dir=$TOMCAT_MAVEN/target/\
+ -agentlib:native-image-agent=config-output-dir=$TOMCAT_STUFFED/target/\
-Dcatalina.base=.
-Djava.util.logging.config.file=conf/logging.properties\
- -jar target/tomcat-maven-1.0.jar</source>
+ -jar target/tomcat-stuffed-1.0.jar --catalina
-useGeneratedCode</source>
</p>
<p>
@@ -136,18 +160,18 @@ ant -Dwebapp.name=somewebapp -f
graal-webapp.ant.xml</source>
--initialize-at-build-time=org.eclipse.jdt,org.apache.el.parser.SimpleNode,jakarta.servlet.jsp.JspFactory,org.apache.jasper.servlet.JasperInitializer,org.apache.jasper.runtime.JspFactoryImpl\
-H:+JNI -H:+ReportUnsupportedElementsAtRuntime\
-H:+ReportExceptionStackTraces
-H:EnableURLProtocols=http,https,jar,jrt\
- -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>
+ -H:ConfigurationFileDirectories=$TOMCAT_STUFFED/target/\
+ -H:ReflectionConfigurationFiles=$TOMCAT_STUFFED/tomcat-reflection.json\
+ -H:ResourceConfigurationFiles=$TOMCAT_STUFFED/tomcat-resource.json\
+ -H:JNIConfigurationFiles=$TOMCAT_STUFFED/tomcat-jni.json\
+ -jar $TOMCAT_STUFFED/target/tomcat-stuffed-1.0.jar</source>
The additional <code>--static</code> parameter enables static linking of
glibc, zlib and libstd++ in the generated binary.
</p>
<p>
Running the native image is then:
- <source>./tomcat-maven-1.0 -Dcatalina.base=.
-Djava.util.logging.config.file=conf/logging.properties</source>
+ <source>./tomcat-stuffed-1.0 -Dcatalina.base=.
-Djava.util.logging.config.file=conf/logging.properties --catalina
-useGeneratedCode</source>
</p>
</section>
@@ -176,9 +200,11 @@ ant -Dwebapp.name=somewebapp -f
graal-webapp.ant.xml</source>
<p>
Missing items for better Tomcat functionality:
<ul>
- <li>Java serialization: Clustering and session persistence are not
+ <li><a href="https://github.com/oracle/graal/issues/460";>Java
+ serialization</a>: Clustering and session persistence are not
functional</li>
- <li>JMX: The usual monitoring and management is not usable</li>
+ <li><a href="https://github.com/oracle/graal/issues/2103";>JMX</a>:
+ The usual monitoring and management is not usable</li>
<li>java.util.logging LogManager: Configuration through a system property
is not implemented, so standard java.util.logging must be used instead
of JULI</li>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
