# Flatpak Development Shim

A shim that allows Java programs to breakout of a Flatpak sandbox and spawn processes on the sandbox host. It is built as a Jigsaw-style module patch to override Java's `java.lang.ProcessBuilder` functionality and spawns processes on the sandbox host by communicating with the "Development" interface of the org.freedesktop.Flatpak DBus API.

## Usage

In order to enable the shim, Java 11 is required and programs must be started with the following parameters:

    --patch-module java.base=/path/to/flatpak-dev-shim.jar
    -Dsun.boot.library.path=/usr/lib/jvm/java-11/lib:/path/to/flatpak-dev-shim/libdir

And the Flatpak sandbox in which the Java program is running must be granted the following permissions:

    --filesystem=host --allow=devel --talk-name=org.freedesktop.Flatpak

Use `java.lang.ProcessBuilder` in the usual way.

## Building

This project is built using maven and requires Java 11. To build the native parts successfully, `JAVA_HOME` must be set in the environment, for example:

    JAVA_HOME=/usr/lib/jvm/java-11 mvn clean verify

To use system-specific compiler and linker flags when building the native parts, you can also set `CFLAGS` and `LDFLAGS` in the environment.

## Limitations

* Because the spawned process runs outside the sandbox, it is not visible to Java (it is outside of the sandbox's cgroup). This means we can't enumerate the process's children and traverse the process hierarchy, etc.

## Problems

Some problems encountered during development:

* Maven compiler plugin is unable to take the option "--patch-module" as descrete arguments, see: https://issues.apache.org/jira/browse/MCOMPILER-311