Package org.graalvm.launcher

Class Launcher

java.lang.Object
org.graalvm.launcher.Launcher
Direct Known Subclasses:
LanguageLauncherBase
public abstract class Launcher extends Object

  • Field Details

    • LAUNCHER_OPTIONS_INDENT

      public static final int LAUNCHER_OPTIONS_INDENT
      Default option description indentation.
      See Also:

  • Constructor Details

    • Launcher

      protected Launcher()

  • Method Details

    • getLogFile

      protected final Path getLogFile()
      Provides the name of the log file, if specified on the command line.
      Returns:
      log file Path. null if unspecified.
      Since:
      20.0

    • setOutput

      protected final void setOutput(PrintStream ps)
      Uses the defined output to print messages.
      Parameters:
      ps - printStream to use as out
      Since:
      20.0

    • setError

      protected final void setError(PrintStream ps)
      Uses the defined output to print error messages.
      Parameters:
      ps - printStream to use as err
      Since:
      20.0

    • getOutput

      protected final PrintStream getOutput()
      Returns:
      the stream for regular output. Defaults to System.out
      Since:
      20.0

    • getError

      protected final PrintStream getError()
      Returns:
      the stream for errors. Defaults to System.err
      Since:
      20.0

    • exit

      protected final Launcher.AbortException exit()
      Exits the launcher, indicating success. This exits by throwing an Launcher.AbortException.

    • exit

      protected final Launcher.AbortException exit(int exitCode)
      Exits the launcher with the provided exit code. This exits by throwing an Launcher.AbortException.
      Parameters:
      exitCode - the exit code of the launcher process.

    • abort

      protected final Launcher.AbortException abort(String message)
      Exits the launcher, indicating failure. This aborts by throwing an Launcher.AbortException.
      Parameters:
      message - an error message that will be printed to stderr. If null, nothing will be printed.

    • abort

      protected final Launcher.AbortException abort(String message, int exitCode)
      Exits the launcher, with the provided exit code. This aborts by throwing an Launcher.AbortException.
      Parameters:
      message - an error message that will be printed to stderr. If null, nothing will be printed.
      exitCode - the exit code of the launcher process.

    • abort

      protected final Launcher.AbortException abort(Throwable t)
      Exits the launcher, indicating failure because of the provided Throwable. This aborts by throwing an Launcher.AbortException.
      Parameters:
      t - the exception that causes the launcher to abort.

    • abort

      protected final Launcher.AbortException abort(Throwable t, int exitCode)
      Exits the launcher with the provided exit code because of the provided Throwable. This aborts by throwing an Launcher.AbortException.
      Parameters:
      t - the exception that causes the launcher to abort.
      exitCode - the exit code of the launcher process.

    • abort

      protected final Launcher.AbortException abort(IOException e)
      Exits the launcher, indicating failure because of the provided IOException. This tries to build a helpful error message based on exception. This aborts by throwing an Launcher.AbortException.
      Parameters:
      e - the exception that causes the launcher to abort.

    • abort

      protected final Launcher.AbortException abort(IOException e, int exitCode)
      Exits the launcher with the provided exit code because of the provided IOException. This tries to build a helpful error message based on exception. This aborts by throwing an Launcher.AbortException.
      Parameters:
      e - the exception that causes the launcher to abort.
      exitCode - the exit code of the launcher process

    • abortUnrecognizedArgument

      protected Launcher.AbortException abortUnrecognizedArgument(String argument)
      This is called to abort execution when an argument can neither be recognized by the launcher or as an option for the polyglot engine.
      Parameters:
      argument - the argument that was not recognized.

    • abortInvalidArgument

      protected final Launcher.AbortException abortInvalidArgument(String argument, String message)
      Exits the launcher, indicating failure because of an invalid argument. This aborts by throwing an Launcher.AbortException.
      Parameters:
      argument - the problematic argument.
      message - an error message that is printed to stderr.

    • abortInvalidArgument

      protected final Launcher.AbortException abortInvalidArgument(String argument, String message, int exitCode)
      Exits the launcher with the provided exit code because of an invalid argument. This aborts by throwing an Launcher.AbortException.
      Parameters:
      argument - the problematic argument.
      message - an error message that is printed to stderr.
      exitCode - the exit code of the launcher process.

    • warn

      protected void warn(String message)

    • warn

      protected void warn(String message, Object... args)

    • setOptionIndent

      protected final void setOptionIndent(int indent)
      Sets the indentation for option descriptions. Sets number of spaces in the first column reserved for option names. Defaults to LAUNCHER_OPTIONS_INDENT.
      Parameters:
      indent - the new indent.
      Since:
      20.0

    • printHelp

      protected abstract void printHelp(org.graalvm.options.OptionCategory maxCategory)
      Prints a help message to stdout. This only prints options that belong to categories maxCategory or less.
      Parameters:
      maxCategory - the maximum category of options that should be printed.

    • printVersion

      protected abstract void printVersion()
      Prints version information on stdout.

    • collectArguments

      protected abstract void collectArguments(Set<String> options)
      Add all known arguments to the options list.
      Parameters:
      options - list to which valid arguments must be added.

    • findOptionDescriptor

      protected abstract org.graalvm.options.OptionDescriptor findOptionDescriptor(String group, String key)
      Finds the a descriptor for the option.
      Parameters:
      group - option group
      key - the option name (including the group)
      Returns:
      descriptor or null.
      Since:
      20.0

    • canPolyglot

      protected boolean canPolyglot()
      Determines if the tool supports polyglot. Returns true, if --polyglot option is valid for this tool and polyglot launcher works for it. The default implementation returns false only when isStandalone() is true.
      Returns:
      true, if polyglot is relevant in this launcher.
      Since:
      20.0

    • maybePrintAdditionalHelp

      protected void maybePrintAdditionalHelp(org.graalvm.options.OptionCategory helpCategory)
      Should print tool-specific help. Regular languages print info on the installed tools and languages. The default implementation prints nothing.
      Parameters:
      helpCategory - category of options to print
      Since:
      20.0

    • getMainClass

      protected String getMainClass()
      Returns the name of the main class for this launcher. Typically: 
       return MyLauncher.class.getName();

    • getDefaultVMType

      protected Launcher.VMType getDefaultVMType()
      The return value specifies the default VM when none of --jvm, --native options is used.
      Returns:
      the default VMType

    • isAOT

      public static boolean isAOT()
      Returns true if the current launcher was compiled ahead-of-time to native code.

    • isGraalVMAvailable

      protected boolean isGraalVMAvailable()

    • isStandalone

      protected boolean isStandalone()

    • getGraalVMHome

      protected Path getGraalVMHome()

    • getGraalVMBinaryPath

      protected final Path getGraalVMBinaryPath(String binaryName)
      Returns filename of the binary, depending on OS. Binary will be searched in bin directory.
      Parameters:
      binaryName - binary name, without path.
      Returns:
      OS-dependent binary filename.

    • runLauncherAction

      protected boolean runLauncherAction()
      Runs launcher's action as version print or help. Returns true, if the execution should terminate, e.g. after printing help. parseCommonOption(java.lang.String, java.util.Map<java.lang.String, java.lang.String>, boolean, java.lang.String) should be called for commandline argument(s) prior to this method to set up flags to display help etc.
      Returns:
      true when execution should be terminated.
      Since:
      20.0

    • printDefaultHelp

      protected void printDefaultHelp(org.graalvm.options.OptionCategory printCategory)
      Prints default help text. Prints options, starting with tool specific options. Launcher implementations can override to provide launcher-specific intro / summary.
      Parameters:
      printCategory - options category to print.
      Since:
      20.0

    • printOtherHelpCategory

      protected void printOtherHelpCategory(String kind, String option)
      Instructs that information about other help categories should be printed.
      Parameters:
      kind - category kind name
      option - the option to print the category
      Since:
      20.0

    • parseUnrecognizedOptions

      protected final void parseUnrecognizedOptions(String defaultOptionPrefix, Map<String,String> polyglotOptions, List<String> unrecognizedArgs)
      Parses otherwise unrecognized options. Terminates the application if an option is not among the generic launcher / VM ones.
      Parameters:
      defaultOptionPrefix - (language) prefix for the options
      polyglotOptions - options being built for the polyglot launcher
      unrecognizedArgs - arguments (options) to evaluate
      Since:
      20.0

    • parseCommonOption

      protected boolean parseCommonOption(String defaultOptionPrefix, Map<String,String> polyglotOptions, boolean experimentalOptions, String arg)
      Parses an option, returning success. The method is called to parse `arg` option from the commandline, not recognized by the application. The method may contribute to the `polyglotOptions` (in/out parameter, modifiable) to alter polyglot behaviour. If the option is recognized, the method must return true.
      Parameters:
      defaultOptionPrefix - default prefix for the option names, derived from the launching application.
      polyglotOptions - options for polyglot engine
      experimentalOptions - true, if experimental options are explicitly allowed
      arg - argument to parse
      Returns:
      true, if the option was recognized.
      Since:
      20.0

    • launcherOption

      protected void launcherOption(String option, String description)
      Prints a line for a launcher option. Uses indentation set by setOptionIndent(int) to align option's description. If option name is too long, description is printed on the next line, indented.
      Parameters:
      option - option name, including dash(es)
      description - description
      Since:
      20.0

    • isTTY

      protected static boolean isTTY()
      Returns true if stdin and stdout are both TTY, false otherwise.
      Since:
      24.0

    • println

      protected final void println(String l)
      Prints a single line to the output stream, terminated with newline.
      Parameters:
      l - line text.
      Since:
      20.0

    • println

      protected final void println(String... lines)
      Prints sequence of lines to the output stream. Each argument will be printed as a whole line, terminated by a newline.
      Parameters:
      lines - lines
      Since:
      20.0

    • getProgramName

      protected static String getProgramName()
      Returns what is an equivalent of argv[0]}, i.e., the command that executed the launcher. If the launcher was executed via a symlink, this returns the symlink. If the launcher was executed via a command resolved via the user's PATH environment variable, this returns that command.
      Returns:
      The program name or null if not available.

    • maybeNativeExec

      @Deprecated(since="20.3") protected final void maybeNativeExec(List<String> args, boolean isPolyglotLauncher, Map<String,String> polyglotOptions)
      Deprecated.

    • maybeNativeExec

      protected final void maybeNativeExec(List<String> originalArgs, List<String> unrecognizedArgs, boolean isPolyglotLauncher)
      Possibly re-executes the launcher when JVM or polyglot mode is requested; call only if isAOT() is true. If the result is to run native, then it applies VM options on the current process. The method parses the unrecognizedArgs for --jvm/--native/--polyglot flags and --vm.* options. If JVM mode is requested, it execs a Java process configured with supported JVM parameters and system properties over this process - in this case, the method does not return (except errors).
      Parameters:
      originalArgs - the original arguments from main(), unmodified.
      unrecognizedArgs - a subset of originalArgs that was not recognized by AbstractLanguageLauncher.preprocessArguments(List, Map). All arguments recognized by maybeExec are removed from the list.
      isPolyglotLauncher - whether this is the PolyglotLauncher (bin/polyglot)
      Since:
      20.0

    • executeJVM

      @Deprecated(since="20.3") protected void executeJVM(String classpath, List<String> jvmArgs, List<String> remainingArgs, Map<String,String> polyglotOptions)
      Deprecated.

    • executeJVM

      protected void executeJVM(String classpath, List<String> jvmArgs, List<String> remainingArgs)
      Called if a JVM has to be started instead of AOT binary. The method is only called in AOT mode. Subclasses may override to apply different options or launch mechanism
      Parameters:
      classpath - class path to be used with the JVM
      jvmArgs - arguments for the VM
      remainingArgs - main arguments

    • executePolyglot

      @Deprecated(since="20.3") protected void executePolyglot(List<String> mainArgs, Map<String,String> polyglotOptions, boolean forceNative)
      Deprecated.

    • executePolyglot

      protected void executePolyglot(List<String> mainArgs, boolean forceNative)
      Called to execute the bin/polyglot launcher with the supplied options. Subclasses may eventually override and implement in a different way.
      Parameters:
      mainArgs - program arguments

    • newLogStream

      public static OutputStream newLogStream(Path path) throws IOException
      Creates a new log file. The method uses a supplemental lock file to determine the file is still opened for output; in that case, it creates a different file, named `path'1, `path`2, ... until it finds a free name. Files not locked (actively written to) are overwritten.
      Parameters:
      path - the desired output for log
      Returns:
      the OutputStream for logging
      Throws:
      IOException - in case of I/O error opening the file
      Since:
      20.0