common.toml

# ==============================================================================
# *** Welcome to Jaunch's base configuration file! ***
# ==============================================================================
#
# Jaunch is a native binary (two per platform, actually) to discover non-native
# runtimes including Python and the Java Virtual Machine (JVM), start them, and
# run programs using them. Via its TOML-based configuration mechanism, Jaunch
# is designed to be powerful and flexible without the need to edit or recompile
# the Jaunch source code.
#
# This common.toml file contains useful general-purpose, non-application-specific
# configuration that defines some sensible defaults for typical launchers.
# You can of course edit it to customize Jaunch's behavior however you like.
#
# Each application will have its own extensions to the general configuration
# defined in another TOML file named the same as its native launcher executable.
# For example, if you have a native executable named fizzbuzz for launching your
# FizzBuzz application, you would also write a fizzbuzz.toml companion file that
# overrides or augments this configuration with fizzbuzz-specific settings.
#
# Alternately, if you would like to keep all configuration together in one file
# for simplicity, you can write a single TOML file with everything, and name it
# either `jaunch.toml` or the same as your native launcher (e.g. `fizzbuzz.toml`).
#
# For simple and concrete demo application examples, see doc/EXAMPLES.md.
#
# Without further ado, let's dive into the configuration!

# ==============================================================================
# jaunch-version
# ==============================================================================
# The version of Jaunch with which this configuration file is intended to work.
# Leave this value be, unless you are upgrading from an older version of Jaunch.

jaunch-version = 2

# ==============================================================================
# program-name
# ==============================================================================
# The name of your program! This name will appear in usage text and dialog boxes.

#program-name = 'FizzBuzz'

# ==============================================================================
# includes
# ==============================================================================
# Other configuration files to recursively combine with this one.
# This mechanism can help to better organize your configuration logic.
# Or turn it into a gigantic mess, if you enjoy overengineered spaghetti.

includes = []

# ==============================================================================
# supported-options
# ==============================================================================
# The list of command line options supported by Jaunch out of the box.
#
# These are arguments that Jaunch will interpret, transforming them in various ways
# into arguments to the main program that is launched, and/or the runtime itself.
#
# The syntax here is hopefully self-explanatory by reading through the list.
# But here are the technical details anyway just in case:
#
# * The pipe symbol (|) divides the declaration of the option itself from its help text.
#   The help text is not required, but recommended, and will be shown when Jaunch's help
#   directive is invoked (which happens out of the box when the --help option is given).
#
# * Options may be standalone (like --debug), or may take a parameter.
#
# * To declare an option as requiring a parameter, simply write an equals sign
#   (=) after the option flag. What you write after the equals sign does not
#   matter, except that it will be shown that way in the help text.
#
# * Jaunch parses parameters given as either a single argument --count=123 with an
#   equals sign (=), or as two arguments (--count 123) separated by a space.
#
# * The parameter value given by the user will be stored into Jaunch's variables
#   using the canonical name of the option in question. So for example,
#   --count=456 will store the value "456" into the variable called count.
#   Variables can be used within strings using `${...}` syntax, e.g. `${count}`.
#   Jaunch also recognizes system environment variables, so you can use
#   expressions like e.g. `${PATH}` if you like as well.
#
# * Options may have any number of aliases, separated by commas. So e.g.
#   --size,length=<number> would let both --size=37 and --length=37 work,
#   storing the value "37" into the variable called "size" since it comes first.
#
# * If you need to use an actual pipe symbol (|) as part of your option or help text, you
#   can't, sorry! It's not a good idea anyway, because that symbol is used by shells to
#   indicate I/O piping between processes. So making it part of an option would be super
#   tricky and confusing. That's why Jaunch uses the pipe symbol as its separator:
#   because it is very unlikely to be needed as an actual character anywhere.
#
# See python.toml and jvm.toml for more supported-options examples.

supported-options = [
    '--help,-h|show this help',
    '--version|print the version of the software',
    '--dry-run|show the command line, but do not run anything',
    '--debug|verbose output',
    '--headless|run in text mode (without any GUI)',
    '--print-app-dir|print directory where the application is located',
    '--print-config-dir|print directory where the configuration files are located',
    '--system|do not try to run bundled runtime',
]

# ==============================================================================
# os-aliases, arch-aliases
# ==============================================================================
# Aliases for operating system names and CPU architectures, respectively.
# Used when analyzing root directory names.

os-aliases = [
    "LINUX:linux",
    "MACOSX:darwin,macos,macosx",
    "WINDOWS:win,windows",
    "IOS:ios",
    "ANDROID:android",
]
arch-aliases = [
    "ARM32:aarch32,arm32",
    "ARM64:aarch64,arm64",
    "X86:i386,i486,i586,i686,x86-32,x86_32,x86",
    "X64:amd64,x86-64,x86_64,x64",
]

# ==============================================================================
# modes
# ==============================================================================
# List of additional hints to enable or disable based on other hints.
#
# ------------------------------------------------------------------------------
# Before we talk about modes, though, we need to explain what hints are.
#
# In many of Jaunch's sections, each string element may be prefixed with one or
# more segments separated by pipes. Each such segment is a *hint* for Jaunch
# regarding a flag that must be set for that particular line to be considered.
# A hint prefixed by a bang symbol (!) negates the hint, making that segment
# match only when that particular hint is *not* set.
#
# Here is an example:
#     '!--quiet|OS:LINUX|ARCH:X64|-Dmessage=Linuuuux-64-BITS!',
#
# Above, the string '-Dmessage=Linuuuux-64-BITS!' will be included in
# the list if and only if the hints OS:LINUX and ARCH:X64 are set, and
# the --quiet hint is NOT set (since it is negated with the bang symbol).
#
# Jaunch sets hint flags based on a few sources:
#
# * Active operating system: OS:LINUX, OS:MACOSX, OS:WINDOWS,
#   OS:IOS, OS:ANDROID, OS:WASM, OS:TVOS, OS:WATCHOS, or OS:UNKNOWN.
#
# * Active CPU architecture: ARCH:ARM32, ARCH:ARM64, ARCH:X86, ARCH:X64,
#   ARCH:MIPS32, ARCH:MIPSEL32, ARCH:WASM32, or ARCH:UNKNOWN.
#
# * Option hints, set from arguments passed to Jaunch, each of which sets a matching
#   hint. For example, passing the --system option will set a hint '--system'.
#
# * Mode hints, set from evaluation of the modes field (we're getting there!).
#
# * Runtime-specific hints, based on the runtime installation(s) selected.
#   For example:
#
#   - PYTHON:3.9 if the selected Python installation is version 3.9.
#   - PYTHON:3.9+ if the selected Python installation is version 3.9 or later.
#   - JAVA:9 if the selected Java installation is version 9.
#   - JAVA:9+ if the selected Java installation is version 9 or later.
#   - and so on.
#
#   Of course, runtime hints will only be set after matching an installation.
#   For more details about runtime hints, see the root-paths documentation in
#   runtime-specific configuration files python.toml and jvm.toml.
#
# ------------------------------------------------------------------------------
# Now that we understand hints: what is this modes section all about?
#
# With modes, you can set (or unset) a single hint in response to different other
# hints, which can help to consolidate rules in other sections of the configuration.
# Modes can also be used to negate hints. It's easiest to explain via an example.
#
# Suppose your program wants to support the following three options:
#
# * --headless, which enables headless mode, disabling the GUI.
# * --batch, which enables a mode to run sequential computations.
# * --big-gui, to use the *BIG* GUI, when you like it large!
#
# Let's say that use of the batch mode implies headless operation,
# while use of the big GUI is incompatible with headless.
#
# You might define the following modes here:
#
#     '--headless|headless',
#     '--batch|headless',
#     '--big-gui|!headless',
#
# In this way, whenever either --headless or --batch is passed, the headless mode hint
# will be enabled, and whenever --big-gui is passed, the headless mode is disabled.
# If multiple conflicting arguments are passed, the ultimate state of headless mode will
# depend on the order of such arguments, since mode lines are evaluated sequentially.
#
# The main advantage of this extra layer of indirection is that configuration elsewhere
# in the TOML file based on whether headless mode is active can simply use the single
# unified headless hint, rather than needing to recapitulate all the (possibly evolving
# over time) special cases in multiple places, improving config clarity and maintenance.

modes = []

# ==============================================================================
# directives
# ==============================================================================
# Commands that define what actually happens during launch.
#
# Each one runs at a particular (hardcoded) time during configuration.
# Directives unsupported by the configurator program are ignored.
#
# This may seem confusingly abstract, but the basic idea is this: maybe you want
# Jaunch *not* to launch the usual program this time, but rather to do something else!
#
# What sorts of other things? you might ask. And how can we possibly define
# such open-ended behavior in a mere TOML configuration file? Well, the short
# answer is: we can't. Jaunch has some built-in directives, and that's it.
# As of this writing, those are:
#
# * ABORT              - Cancel the launch without displaying an error message.
#
# * ERROR              - Cancel the launch and display an error message to the user.
#
# * SETCWD             - Change the current working directory (CWD) of the process.
#                        Useful e.g. to ensure the application starts in ${app-dir}
#                        regardless of the platform -- e.g. macOS apps launched via
#                        Finder start in the root directory (/) by default.
#
# * INIT_THREADS       - Call X11's XInitThreads() function to enable multithreading.
#                        Has no effect on non-Linux platforms. See also doc/LINUX.md.
#
# * RUNLOOP            - Set the runloop mode for macOS event handling. Values:
#                        main (run on main thread), park (park main thread),
#                        none (no special handling), auto (automatic selection).
#
# * help               - Display the usage text, built from the supported-options above.
#
# * dry-run            - Display the final launch command with runtime args + main args.
#                        Useful to see what would happen, without it actually happening.
#
# * print-app-dir      - Print out the path to the application. Typically, this will be
#                        the folder containing the launcher.
#
# * print-config-dir   - Print out the path to the configuration directory.
#
# Directives in UPPER CASE are native launch modes handled on the C/native side,
# while directives in web-case are executed on the configurator side.
#
# Some additional directives are runtime-specific; see the directives documentation
# in runtime-specific configuration files python.toml and jvm.toml.
#
# If you need to support other directives besides those above, you'll have to
# hack the Kotlin and/or C source code, and also write rules here in the TOML.
#
# But if you simply want to disable e.g. Jaunch's built-in help, you can safely
# remove the `--help` and `-h` lines below to do so.

directives = [
  '--dry-run|dry-run,ABORT',  # <-- Order matters! Turn on dry-run mode right away.
  '--help|help,ABORT',
  '-h|help,ABORT',
  '--version|version,ABORT',
  '--print-app-dir|print-app-dir',
  '--print-config-dir|print-config-dir',
]

# ==============================================================================
# allow-unrecognized-args
# ==============================================================================
# Whether to allow unrecognized arguments to be passed to the runtime.
#
# When the minus-minus (--) divider is absent, the only args that end up as
# runtime args will be ones from the runtime-specific `recognized-args` lists
# (see python.toml and jvm.toml for examples). But if the minus-minus divider
# *is* given, it becomes possible to force a particular argument to be construed
# as an argument to the runtime, even when it does not appear on the list.
#
# For example, suppose for a JVM-based application called JFizzBuzz the user writes:
#
#     ./jfb -ZZ:SuperSecretOption -- 1 2 3 4 5
#
# Using the config in jvm.toml, Jaunch would translate this into something like:
#
#     .../bin/java -ZZ:SuperSecretOption org.fizzbuzz.FizzBuzz 1 2 3 4 5
#
# However, depending on your application, it might not be desirable for
# such unrecognized args to be allowed through to the program launch.
#
# * If you want to allow all user-specified runtime args through to the
#   program launch, even when they aren't recognized, set this value to true.
#
# * If you want full control over what arguments the user can pass to the runtime,
#   set this value to false, and edit the appropriate recognized-args list
#   according to your needs. Then Jaunch will fail fast when told to pass an
#   unrecognized option to the runtime.
#
# If you know Java, you probably know that it will barf when confronted with an
# argument like -ZZ:SuperSecretOption. But maybe you are using a custom build of
# OpenJDK produced by your organization's new superintelligent AI, which
# actually *does* have this option! Who is Jaunch to judge? (In that case, I
# would argue you should really just add '-ZZ:*' to the `jvm.recognized-args`
# list in jvm.toml, but then I would be judging.) Or maybe you just want to
# trust your users as OpenJDK evolves, rather than dealing with the bureaucracy
# of updating the TOML file every time OpenJDK changes its supported options.
# In such cases, this option is here for you.

allow-unrecognized-args = false

# You did it! It's the end. :clap: Bye now.