Gradle plugin configuration - fakeivchenko/lwjwae GitHub Wiki

Every setting of the lwjwae {} block is optional. The example below lists all of them, each with its default in the comment. For what the plugin does and the short forms, see the Gradle plugin.

lwjwae {
    managed = true                        // false: add nothing, declare the dependencies and the processor yourself
    version = "0.11.0"                    // lwjwae-core and the backends; default: the plugin's
    codecsVersion = "0.1.3"               // the codec modules; default: the plugin's
    backends = Backends.CURRENT_PLATFORM  // or ALL, NONE
    linuxBackend = LinuxBackend.GTK3      // or GTK4: GTK 4 and WebKitGTK 6.0
    codec = Codec.NONE                    // or JACKSON, GSON, JSONB; shortcuts: jackson(), gson(), jsonb()
    jsonbProvider = "org.eclipse:yasson"  // the implementation that comes with JSONB, group:artifact
    jsonbProviderVersion = "3.0.4"        // and its version; both at once: jsonb("group:artifact:version")

    imageName = "my-app"                  // the executable; default: the project name
    displayName = "My app"                // what people see; default: imageName
    vendor = "Example <[email protected]>"   // the company, the manufacturer, the Debian maintainer
    icon = file("app.png")                // one square PNG, 256 px or larger; default: src/main/icons/app.png, if there
    embedResources = true                 // the files of src/main/resources go into the image
    optimizeForSize = true                // -Os
    maxHeapSize = "64m"                   // -R:MaxHeapSize; "" leaves it unset
    toolchainDetection = false            // true: find a GraalVM through Gradle toolchains instead of GRAALVM_HOME
    buildArgs.add("--verbose")            // appended to the native-image command line
    urlScheme("notes")                    // links that the packages register; Application.onOpen hears them
    fileType("note")                      // files that they register; or fileType("md", "text/markdown", "Markdown")

    windows {
        icon = file("custom.ico")         // a ready-made .ico instead of the one rendered from icon
        iconSizes = listOf(16, 24, 32, 48, 64, 128, 256)
        console = false                   // true: keep a console window
        fileDescription = "My app"        // default: displayName
        productName = "My product"        // default: displayName
        companyName = "Example and Co"    // default: vendor, without its address
        copyright = "(c) Example"
        version = "1.2.3"                 // default: the project version
        resourceScript = file("custom.rc")   // replaces the generated script
        signing {                         // off until a certificate is set
            certificateThumbprint = "0123...4567"   // SHA-1 of a certificate in the store of the user
            certificateFile = file("certificate.pfx")   // or a .pfx file
            certificatePassword = "..."   // default: lwjwae.windowsCertificatePassword, then LWJWAE_WINDOWS_CERTIFICATE_PASSWORD
            timestampUrl = "http://timestamp.digicert.com"
        }
    }

    macos {
        bundleIdentifier = "com.example.myapp"   // default: GROUP.NAME, other characters as -
        bundleName = "My app"             // default: displayName; also names the .app
        version = "1.2.3"                 // default: the project version
        infoPlist = file("Info.plist")    // replaces the generated property list
        signingIdentity = "Developer ID Application: Example (TEAMID)"   // codesign the bundle; unset: unsigned
        hardenedRuntime = true            // notarization requires it
        entitlements = file("entitlements.plist")   // for the signature; unset: none
        notarization {                    // off until one of the three ways in is set
            keychainProfile = "notary"    // a profile of xcrun notarytool store-credentials
            apiKey = file("AuthKey_ABC123.p8")   // or an API key of App Store Connect
            apiKeyId = "ABC123"
            apiIssuer = "UUID"
            appleId = "[email protected]"   // or an Apple ID
            teamId = "TEAMID"
            password = "..."              // default: lwjwae.notaryPassword, then LWJWAE_NOTARY_PASSWORD
        }
    }

    frontend {                            // on when the directory has a package.json
        enabled = true
        directory = file("frontend")
        outputDirectory = file("frontend/dist")
        resourcePath = "app"              // window.loadResource("app/index.html")
        buildScript = "build"             // npm run build
        devScript = "dev"                 // npm run dev, for runDev
        devServerUrl = "http://localhost:5173"   // what runDev waits for and loads
    }

    updates {                             // unset manifestUrl: no updater
        manifestUrl = "https://example.com/notes/manifest.json"
        publicKey = "MCowBQYDK2VwAyEA..."   // from generateUpdateKeys
        privateKey = "..."                // default: lwjwae.updatePrivateKey, then LWJWAE_UPDATE_PRIVATE_KEY
        notes = "What changed"            // default: nothing
        minimumVersion = "1.0.0"          // older versions see the update as mandatory; default: unset
        directory = file("build/lwjwae/update")   // the release directory
    }

    packaging {
        all()                             // every format on; one by one: deb(), arch(), appImage(), dmg(), msi()
        description = "One line about the app"   // default: the project description, or displayName
        homepage = "https://example.com"
        categories = listOf("Utility")    // the Linux menu categories

        deb {                             // a block turns the format on; enabled = false turns it off
            packageName = "my-app"        // default: imageName, lowercased
            maintainer = "Example <[email protected]>"   // required by the format; default: vendor, if it has an address
            depends = listOf("libgtk-3-0t64 | libgtk-3-0", "libwebkit2gtk-4.1-0")   // default: the packages of linuxBackend
            section = "utils"
            priority = "optional"
            version = "1.2.3"             // default: the project version
        }
        arch {
            packageName = "my-app"        // default: imageName, lowercased
            packager = "Example <[email protected]>"   // default: vendor
            depends = listOf("gtk3", "webkit2gtk-4.1")   // default: the packages of linuxBackend
            licenses = listOf("Apache-2.0")   // SPDX identifiers; default: none
            version = "1.2.3"             // pkgver; default: the project version, - as _
            release = "1"                 // pkgrel
        }
        appImage {
            fileName = "my-app"           // default: imageName
            tool = file("appimagetool-x86_64.AppImage")   // instead of the downloaded one
        }
        dmg {
            volumeName = "My app"         // default: macos.bundleName
        }
        msi {
            perUser = true                // false: Program Files, asks for elevation
            upgradeCode = "GUID"          // keep stable; default: derived from group and name
            manufacturer = "Example"      // default: vendor, without its address, or displayName
            productName = "My app"        // default: displayName
            wixVersion = "6.0.2"          // installed when no wix is on the PATH
            tool = file("wix.exe")        // instead of the PATH or the cache
            fileName = "my-app"           // default: imageName
        }
    }
}

Backends, LinuxBackend, and Codec are in the dev.ivchenko.lwjwae.gradle package. Import them at the top of build.gradle.kts, or write the full name, such as dev.ivchenko.lwjwae.gradle.Backends.ALL. The codec has short forms that need neither: jackson(), gson(), and jsonb().

graalvmNative {} of the Native Build Tools plugin stays available for anything that isn't listed.

The passwords and the private key have defaults that read a Gradle property, such as -Plwjwae.notaryPassword=... or a line in ~/.gradle/gradle.properties, and then an environment variable, so they stay out of the build script and the repository.

Signing

windows.signing signs with a certificate in the store of the user, by certificateThumbprint, or with a .pfx file, by certificateFile and certificatePassword. With neither, nothing is signed.

macos.notarization takes one of three ways into the notary service of Apple:

Settings	When to use it
keychainProfile	On a Mac of your own, after xcrun notarytool store-credentials saved the profile.
apiKey, apiKeyId, apiIssuer	In CI, with an API key of App Store Connect.
appleId, teamId, password	With an Apple ID and an app-specific password.

Notarization needs signingIdentity and the hardened runtime. See Gradle plugin.

Dependencies

Backends.CURRENT_PLATFORM selects lwjwae-windows, lwjwae-macos, or the backend of linuxBackend by the operating system that runs the build, which is the right backend for a native image built on that machine. On Linux, that is lwjwae-gtk by default, or lwjwae-gtk4 for distributions that ship WebKitGTK 6.0 without 4.1; the Depends of the .deb follow the choice. Backends.ALL puts all four backends on the classpath, for a JAR file that runs anywhere.

Names

displayName and vendor fill in the names of every platform, which you can still set one by one:

Setting	Default
windows.fileDescription, windows.productName	displayName
windows.companyName	vendor, without the address
macos.bundleName, which also names the .app	displayName
packaging.deb.maintainer	vendor, when it has an address in <>; the .deb needs one
packaging.arch.packager	vendor, or else Unknown Packager
packaging.msi.manufacturer	vendor, without the address, or else displayName
packaging.msi.productName	displayName
packaging.description	The project description, or else displayName

Packages

A format is off until the build script names it: with packaging.all(), with its short form such as deb(), or with its block, such as deb { section = "editors" }. enabled = false in a block turns the format off again.

Every setting is wired lazily, through providers, so the lwjwae {} block can come anywhere after the plugins {} block.