skip to content

What is the CreateStartScripts task type, and what does the generated launcher script actually do at runtime?

level: middleimportance: must knowfreq 50%

answer

  1. type CreateStartScripts
  2. <name> + <name>.bat
  3. classpath from lib/
  4. JAVA_OPTS + <APP>_OPTS
  5. custom unix/windows generator

basics

~10 s

CreateStartScripts is the task type behind the startScripts task. It generates the bin/<name> (Unix) and bin/<name>.bat (Windows) launchers that build the classpath from lib/, locate the JVM, apply JVM options, and run your mainClass.

solid answer

~40 s

`startScripts` is a task of type `CreateStartScripts` registered by the Application plugin. It writes two cross-platform launchers into `build/scripts` (and into `bin/` of any install/distribution): a POSIX shell script `<name>` and a Windows batch file `<name>.bat`. At runtime each script resolves its own directory to find the install root, assembles the classpath from the jars in `lib/`, reads `JAVA_OPTS`, a per-application `<APP_NAME>_OPTS` env var, and any `applicationDefaultJvmArgs` baked in at generation time, then locates the JVM via `JAVA_HOME` or `java` on PATH and execs `java -cp ... <mainClass> "$@"`. Key configurable inputs on the task include `mainClass`, `applicationName`, `classpath`, `defaultJvmOpts`, `executableDir`, and even `unixStartScriptGenerator`/`windowsStartScriptGenerator` (you can supply a custom template). Because it's a normal task, you can wire `tasks.named("startScripts")` to tweak these.

code

kotlin · 8 lines
kotlin
tasks.named<CreateStartScripts>("startScripts") {
    // override mainClass just for the launcher
    mainClass.set("com.acme.cli.Launcher")
    defaultJvmOpts = listOf("-Xss2m", "-XX:+UseZGC")
    // provide a custom unix template
    (unixStartScriptGenerator as TemplateBasedScriptGenerator).template =
        resources.text.fromFile("src/dist/templates/unixStartScript.txt")
}

go deeper

for a junior

Know that startScripts generates the two launchers (Unix + .bat) that run your app.

for a middle

Explain the runtime steps: classpath from lib/, JAVA_HOME/PATH JVM lookup, JAVA_OPTS/<APP>_OPTS, exec mainClass — and that it's a CreateStartScripts task.

for a senior

Configure defaultJvmOpts/executableDir and discuss supplying custom unix/windows generators; mention long-classpath handling on Windows.

for a principal

Standardize a templated start-script generator across the org for consistent JVM tuning, env conventions, and security hardening.

## The task behind the launchers When you apply the **Application plugin**, it registers a task named **`startScripts`** whose **type is `CreateStartScripts`**. Its job is to generate the platform launchers that end up in `bin/` of every `installDist`/distribution image. It produces **two** files: - `<applicationName>` — a **POSIX shell** script for Linux/macOS. - `<applicationName>.bat` — a **Windows batch** script. The default output directory of the task itself is `build/scripts/`; `installDist` then copies these into `bin/`. ## What the script does when executed A generated launcher performs roughly these steps: 1. **Find the app home** — it resolves its own path (e.g. via `$0`) and walks up to the install root, so the install is relocatable. 2. **Build the classpath** — it joins all jars in `lib/`. (Long classpaths on Windows can be shortened via a pathing/manifest jar.) 3. **Collect JVM options** in this order: `applicationDefaultJvmArgs` baked in at generation time, then `JAVA_OPTS`, then a **per-app** env var named after the upper-cased app name with `_OPTS` (e.g. `MYAPP_OPTS`). 4. **Locate the JVM** — prefer `$JAVA_HOME/bin/java`, else `java` from `PATH`; error out if neither is found. 5. **Exec** `java <jvm opts> -cp <classpath> <mainClass> "$@"`, forwarding all CLI arguments. ## Configurable inputs `CreateStartScripts` exposes properties you can set directly: ```kotlin tasks.named<CreateStartScripts>("startScripts") { applicationName = "myapp" mainClass.set("com.acme.Main") defaultJvmOpts = listOf("-Xmx512m", "-Dfile.encoding=UTF-8") executableDir = "runtime/bin" // relative location of scripts inside the dist } ``` Most of these are normally set via the `application { }` extension (`mainClass`, `applicationName`, `applicationDefaultJvmArgs`, `executableDir`) and propagated to the task, but you can override on the task for advanced cases. ## Custom templates For full control over the generated text, the task has `unixStartScriptGenerator` and `windowsStartScriptGenerator` properties (each a `TemplateBasedScriptGenerator`) — you can point them at your own template resource to inject extra environment setup, JVM detection logic, or branding. ## Why it matters The start scripts are the *user-facing entry point* of a JVM app distribution. Knowing they are a regular configurable task — not a black box — lets you add JVM tuning, rename the executable, change where it sits in the layout, or template it for your org's conventions.

  • Which env var lets a user pass extra JVM args at launch time without rebuilding?
    JAVA_OPTS, or the per-app <APP_NAME>_OPTS variable (e.g. MYAPP_OPTS); both are read by the generated script at runtime.
  • How do you fully customize the generated script text?
    Set the unixStartScriptGenerator / windowsStartScriptGenerator template properties to your own TemplateBasedScriptGenerator template file.
  • Where does the startScripts task write before installDist runs?
    Into build/scripts/ by default; installDist copies them into bin/ of the install image.

saying these in an interview costs you the question

  • Saying the start script embeds the classpath as a fat jar — it instead references each jar in lib/.
  • Claiming JVM args can only be set at build time — JAVA_OPTS and <APP>_OPTS are honored at runtime.

context

resolving links…