# HG changeset patch
# User Doug Simon <doug.simon@oracle.com>
# Date 1418868611 -36000
# Node ID ae5033a78f1dda17d60a23a5ae8697da55d68210
# Parent  ed8477e2561c201a06dd0716727bdbfd5da3348e
improved documentation around the mechanism for generating graalRuntime.inline.hpp

diff -r ed8477e2561c -r ae5033a78f1d graal/com.oracle.graal.hotspot.sourcegen/src/com/oracle/graal/hotspot/sourcegen/GenGraalRuntimeInlineHpp.java
--- a/graal/com.oracle.graal.hotspot.sourcegen/src/com/oracle/graal/hotspot/sourcegen/GenGraalRuntimeInlineHpp.java	Tue Dec 16 21:48:16 2014 +0100
+++ b/graal/com.oracle.graal.hotspot.sourcegen/src/com/oracle/graal/hotspot/sourcegen/GenGraalRuntimeInlineHpp.java	Thu Dec 18 12:10:11 2014 +1000
@@ -34,7 +34,22 @@
 import com.oracle.graal.options.*;
 
 /**
- * Command line utility for generating the source code of {@code GraalRuntime.inline.hpp}.
+ * Command line utility for generating the source code of {@code graalRuntime.inline.hpp}. The
+ * generated code is comprised of:
+ * <ul>
+ * <li>{@code -G} command line option parsing {@linkplain #genSetOption(PrintStream) helper}</li>
+ * <li>{@link Service} loading {@linkplain #genGetServiceImpls(PrintStream) helper}</li>
+ * </ul>
+ *
+ * The purpose of the generated code is to avoid executing Graal related Java code as much as
+ * possible during initialization of the Graal runtime. Future solutions such as some kind of AOT
+ * system may make such a mechanism redundant in terms of minimizing Graal's impact on VM startup
+ * time.
+ *
+ * The input for the generation is all classes that implement {@link Service} or contain fields
+ * annotated by {@link Option}. As such, the code generation process must be executed with a class
+ * path including all Graal jars that contains such classes. Currently, this is
+ * {@code graal-truffle.jar}.
  */
 public class GenGraalRuntimeInlineHpp {
 
diff -r ed8477e2561c -r ae5033a78f1d mx/mx_graal.py
--- a/mx/mx_graal.py	Tue Dec 16 21:48:16 2014 +0100
+++ b/mx/mx_graal.py	Thu Dec 18 12:10:11 2014 +1000
@@ -588,6 +588,12 @@
     """
 
     if dist.name == 'GRAAL_TRUFFLE':
+        # The content in graalRuntime.inline.hpp is generated from Graal
+        # classes that implement com.oracle.graal.api.runtime.Service
+        # or contain com.oracle.graal.options.Option annotated fields.
+        # Since GRAAL_TRUFFLE is the leaf most distribution containing
+        # such classes, the generation is triggered when GRAAL_TRUFFLE
+        # is (re)built.
         _update_graalRuntime_inline_hpp(dist)
     jdks = _jdksDir()