flatpak-gradle-generator

A Gradle plugin to generate a sources file for offline Flatpak builds.

The plugin will output all direct and transitive dependencies for all build configurations (including plugin dependencies) in a JSON file. The JSON file can be used in a Flatpak build process to download Maven dependencies before an offline build starts. The downloaded files will be stored in a local Maven repository layout.

Example gradle.build:

plugins {
  id 'application'
  id 'io.github.jwharm.flatpak-gradle-generator' version '1.7.0'
}

repositories {
  mavenCentral()
  maven { url './offline-repository' }
}

dependencies {
  // a random dependency for this example
  implementation 'io.github.jwharm.javagi:adw:0.7.1'
}

tasks.flatpakGradleGenerator {
  outputFile = file('flatpak-sources.json')
  downloadDirectory = './offline-repository'
}

Run ./gradlew flatpakGradleGenerator --no-configuration-cache and it will write a json file with information about the dependencies:

[
  {
    "type": "file",
    "url": "https://repo.maven.apache.org/maven2/io/github/jwharm/javagi/adw/0.7.1/adw-0.7.1.module",
    "sha512": "d265d970864b3fb4c97b0fe87030ba76eafb252531d9da37cd7a51296b32e95bb70154f0075f6a0d0bc1e41fbd7f23280bdc6b317a1d5808c5a0c4b3a5ac70b5",
    "dest": "./offline-repository/io/github/jwharm/javagi/adw/0.7.1",
    "dest-filename": "adw-0.7.1.module"
  },
  {
    "type": "file",
    "url": "https://repo.maven.apache.org/maven2/io/github/jwharm/javagi/adw/0.7.1/adw-0.7.1.jar",
    "sha512": "356a1c8f8ae89d7212bdfccd9afcd607ae86301485dd850d11eb378cbfe6f05f00cee27be368f907b0b941a065564f7ca3fb7ee18b21f4aaf8bec4d4176ba65a",
    "dest": "./offline-repository/io/github/jwharm/javagi/adw/0.7.1",
    "dest-filename": "adw-0.7.1.jar"
  },
  ...etc...

Add the JSON filename to the sources list in your Flatpak manifest:

    sources:
      - flatpak-sources.json

With this addition, flatpak-builder will automatically download all dependencies into the offline Maven repository folder.

Include and exclude configurations

Specific configurations can be included and excluded with the includeConfiguration and excludeConfiguration options (the latter overrides the former). For example, to exclude test dependencies:

tasks.flatpakGradleGenerator {
    outputFile = file('flatpak-sources.json')
    excludeConfigurations = [
            'testCompileClasspath',
            'testRuntimeClasspath'
    ]
}

Configuration cache

The flatpakGradleGenerator task is incompatible with the Gradle Configuration Cache, so it needs to be run with the --no-configuration-cache command-line argument.

You can still use the Configuration Cache for other tasks in your project.

Modular builds

Because a task from one Gradle project is not allowed to directly resolve a configuration in another project, the plugin is limited to the project context in which the flatpakGradleGenerator task is declared.

In a modular Gradle build, you can add a tasks.flatpakGradleGenerator {} block in the build files of the subprojects, to generate separate files for each project.

Architecture-specific sources

Flatpak expects an "only-arches" identifier for architecture-specific sources. Most Java libraries are architecture-independent, but some, like JavaFX, contain different artifacts depending on the runtime platform. As far as I know, it is not possible to automatically recognize these in Gradle. However, as a workaround, we can generate json files with the "only-arches" field with a fixed value (set as a plugin task parameter) to all entries in the generated sources list.

To do this, run the flatpakGradleGenerator task on each platform with the "onlyArches" parameter on the task set to a correct value such as "x86_64", to produce multiple files that explicitly only support one specific platform, and then add all of those files as sources in the Flatpak manifest. Of course, a majority of the dependencies will end up being the same in all generated files, but they will be downloaded only once by flatpak-builder.

Check out the javafx testcase for an example on how to use the "onlyArches" parameter.

Compatibility

The plugin has been tested with Gradle 8.13 and 9.4. The published jar is built with Java 17.