# ============================================================================== # *** 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= 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.