run: Allow caller to replace /app and/or /usr

The pressure-vessel container tool in Steam will want to use this, to
replace /usr with a Steam Runtime container supplied by the Steam CDN,
instead of using the same Flatpak runtime that is used to run the Steam
client and non-containerized games.

If a custom /usr is used, the "official" Flatpak runtime is still the
one reflected in the metadata. It is also mounted at /run/parent,
with all its extensions, so that pressure-vessel has the option of using
its graphics drivers (by populating the custom /usr with symlinks into
/run/parent and/or /run/host).

When doing this, we need to put an empty directory on /app, because
the real /app expects to be run on top of the real runtime. It would
also be reasonable to substitute a custom replacement for /app, so
I've included support for that too.

Partially addresses #3797.

Signed-off-by: Simon McVittie <smcv@collabora.com>

2 files changed, 111 insertions, 0 deletions

diff --git a/doc/flatpak-metadata.xml b/doc/flatpak-metadata.xml
index abb213d2..f4cd84ce 100644
--- a/doc/flatpak-metadata.xml
+++ b/doc/flatpak-metadata.xml
@@ -530,11 +530,42 @@
                         app files, as mounted at <filename>/app</filename>
                         inside the container. Available since 0.6.10.
                     </para></listitem>
+                    <listitem><para>
+                        Since 1.12.0, if <command>flatpak run</command>
+                        was run with the <option>--app-path</option> option,
+                        this key gives the absolute path of whatever files
+                        were mounted on <filename>/app</filename>, even if
+                        that differs from the app's normal app files.
+                    </para></listitem>
+                    <listitem><para>
+                        If <command>flatpak run</command> was run with
+                        <option>--app-path=</option> (resulting in an
+                        empty directory being mounted on
+                        <filename>/app</filename>), the value is set to
+                        the empty string.
+                    </para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>original-app-path</option> (string)</term>
+                    <listitem><para>
+                        If <command>flatpak run</command> was run with the
+                        <option>--app-path</option> option, this key gives
+                        the absolute path of the app's original files,
+                        as mounted at <filename>/run/parent/app</filename>
+                        inside the container. Available since 1.12.0.
+                    </para></listitem>
+                    <listitem><para>
+                        If this key is missing, the app files are given
+                        by <option>app-path</option>.
+                    </para></listitem>
                 </varlistentry>
                 <varlistentry>
                     <term><option>app-commit</option> (string)</term>
                     <listitem><para>
                         The commit ID of the application that is running.
+                        The filename of a deployment of this commit can
+                        be found in <option>original-app-path</option>
+                        if present, or <option>app-path</option> otherwise.
                     </para></listitem>
                 </varlistentry>
                 <varlistentry>
@@ -543,6 +574,10 @@
                         A list of app extensions that are mounted into
                         the running instance. The format for each list item is
                         <option>EXTENSION_ID=COMMIT</option>.
+                        If <option>original-app-path</option> is present,
+                        the extensions are mounted below
+                        <filename>/run/parent/app</filename>; otherwise,
+                        they are mounted below <filename>/app</filename>.
                     </para></listitem>
                 </varlistentry>
                 <varlistentry>
@@ -573,11 +608,36 @@
                         runtime files, as mounted at <filename>/usr</filename>
                         inside the container. Available since 0.6.10.
                     </para></listitem>
+                    <listitem><para>
+                        Since 1.12.0, if <command>flatpak run</command>
+                        was run with the <option>--usr-path</option> option,
+                        this key gives the absolute path of whatever files
+                        were mounted on <filename>/usr</filename>, even if
+                        that differs from the app's normal runtime files.
+                    </para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>original-runtime-path</option> (string)</term>
+                    <listitem><para>
+                        If <command>flatpak run</command> was run with the
+                        <option>--runtime-path</option> option, this key gives
+                        the absolute path of the app's original runtime,
+                        as mounted at <filename>/run/parent/usr</filename>
+                        inside the container. Available since 1.12.0.
+                    </para></listitem>
+                    <listitem><para>
+                        If this key is missing, the runtime files are given
+                        by <option>runtime-path</option>.
+                    </para></listitem>
                 </varlistentry>
                 <varlistentry>
                     <term><option>runtime-commit</option> (string)</term>
                     <listitem><para>
                         The commit ID of the runtime that is used.
+                        The filename of a deployment of this commit can be
+                        found in <option>original-runtime-path</option>
+                        if present, or <option>runtime-path</option>
+                        otherwise.
                     </para></listitem>
                 </varlistentry>
                 <varlistentry>
@@ -586,6 +646,10 @@
                         A list of runtime extensions that are mounted into
                         the running instance. The format for each list item is
                         <option>EXTENSION_ID=COMMIT</option>.
+                        If <option>original-app-path</option> is present,
+                        the extensions are mounted below
+                        <filename>/run/parent/usr</filename>; otherwise,
+                        they are mounted below <filename>/usr</filename>.
                     </para></listitem>
                 </varlistentry>
                 <varlistentry>
diff --git a/doc/flatpak-run.xml b/doc/flatpak-run.xml
index 28e7f599..a9c2c947 100644
--- a/doc/flatpak-run.xml
+++ b/doc/flatpak-run.xml
@@ -636,7 +636,54 @@ key=v1;v2;
                     permissions for the application.
                 </para></listitem>
             </varlistentry>
+
+            <varlistentry>
+                <term><option>--app-path=<replaceable>PATH</replaceable></option></term>
+                <listitem><para>
+                    Instead of mounting the app's content on
+                    <filename>/app</filename> in the sandbox, mount
+                    <replaceable>PATH</replaceable> on <filename>/app</filename>,
+                    and the app's content on
+                    <filename>/run/parent/app</filename>.
+                    If the app has extensions, they will also be redirected
+                    into <filename>/run/parent/app</filename>, and will not
+                    be included in the <envar>LD_LIBRARY_PATH</envar> inside
+                    the sandbox.
+                </para></listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>--app-path=</option></term>
+                <listitem><para>
+                    As a special case, <option>--app-path=</option>
+                    (with an empty <replaceable>PATH</replaceable>)
+                    results in an empty directory being mounted on
+                    <filename>/app</filename>.
+                </para></listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term><option>--usr-path=<replaceable>PATH</replaceable></option></term>
+                <listitem><para>
+                    Instead of mounting the runtime's files on
+                    <filename>/usr</filename> in the sandbox, mount
+                    <replaceable>PATH</replaceable> on
+                    <filename>/usr</filename>,
+                    and the runtime's normal files on
+                    <filename>/run/parent/usr</filename>.
+                    If the runtime has extensions, they will also be redirected
+                    into <filename>/run/parent/usr</filename>, and will not
+                    be included in the <envar>LD_LIBRARY_PATH</envar> inside
+                    the sandbox.
+                </para></listitem>
+                <listitem><para>
+                    This option will usually only be useful if it is
+                    combined with <option>--app-path=</option> and
+                    <option>--env=LD_LIBRARY_PATH=<replaceable>...</replaceable></option>.
+                </para></listitem>
+            </varlistentry>
+
         </variablelist>
+
     </refsect1>
 
     <refsect1>