Add export and unexport commands for desktop and CLI integration

doc/meson.build

@@ -15,6 +15,8 @@ manuals = {
     'toolbox-rm',
     'toolbox-rmi',
     'toolbox-run',
+    'toolbox-export',
+    'toolbox-unexport',
   ],
   '5': [
     'toolbox.conf',

doc/toolbox-export.1.md

@@ -0,0 +1,101 @@
+% toolbox-export 1
+
+## NAME
+toolbox\-export - Export an application or a binary from a Toolbx container
+
+## SYNOPSIS
+**toolbox export** [*--app APP* | *--bin BIN*] [*--container NAME*] [*--force*]
+
+## DESCRIPTION
+
+Makes a graphical application or a command line tool from inside a Toolbx
+container available on the host.
+
+Exporting an application writes a copy of its desktop entry to
+`$XDG_DATA_HOME/applications`, with the `Exec` and `TryExec` keys rewritten to
+go through `toolbox run`. The basename of the desktop entry is preserved,
+because Wayland compositors match the `app_id` of a window against it to find
+the corresponding icon and name. Renaming the entry would break that mapping.
+
+Icons referenced by the entry are copied to
+`$XDG_DATA_HOME/toolbx/NAME/icons/APP-ID` and referenced from the exported
+entry by their absolute path. The icon themes on the host are left untouched.
+
+Exporting a binary writes a small shell script to `$XDG_BIN_HOME`, which
+executes the binary through `toolbox run`. Note that this directory is not
+part of `PATH` on every operating system. A warning is shown if it isn't.
+
+Applications and binaries are looked up inside the container itself, using the
+container's own `XDG_DATA_HOME` and `XDG_DATA_DIRS`. The host doesn't read the
+container's file system.
+
+Exported files record the container they came from. Desktop entries get an
+`X-Toolbx-Container` key, and shell scripts get a comment in the same form.
+Files that lack such a marker, or that carry the name of a different
+container, aren't overwritten unless the `--force` option is used, and are
+never removed by `toolbox unexport`.
+
+Applications are resolved by their desktop file ID with the trailing
+`.desktop` being optional. If no exact match is found, an entry whose ID ends
+with the given name is used, so that `--app gimp` finds `org.gimp.GIMP`.
+
+## OPTIONS ##
+
+The following options are understood:
+
+**--app** APP
+
+Export the application with the given desktop entry. Can't be used together
+with `--bin`.
+
+**--bin** BIN
+
+Export the binary with the given name. The name is looked up in the
+container's `PATH`. Can't be used together with `--app`.
+
+**--container** NAME, **-c** NAME
+
+Export from the Toolbx container with the given NAME. This is useful when
+multiple containers are present.
+
+**--force**
+
+Overwrite an existing file even if it wasn't exported from the same container,
+or wasn't exported by Toolbx at all.
+
+## NOTES
+
+Two keys of an exported desktop entry are adjusted, because they're meaningless
+once the `Exec` line runs on the host:
+
+`DBusActivatable` is set to `false`. Otherwise the launcher tries to activate a
+bus name that only exists inside the container.
+
+`Path` is commented out. It's the working directory that the launcher enters
+before spawning the application, and it usually doesn't exist on the host.
+The working directory inside the container is unaffected.
+
+## EXAMPLES
+
+### Export GIMP from the default Toolbx container
+
+```
+$ toolbox export --app gimp
+```
+
+### Export Neovim from a container called fedora-toolbox-42
+
+```
+$ toolbox export --bin nvim --container fedora-toolbox-42
+```
+
+### Replace an entry that was exported from a different container
+
+```
+$ toolbox export --app gimp --container arch-toolbox-latest --force
+```
+
+## SEE ALSO
+
+`toolbox(1)`, `toolbox-run(1)`, `toolbox-unexport(1)`,
+https://specifications.freedesktop.org/desktop-entry-spec/latest/

doc/toolbox-rm.1.md

@@ -11,8 +11,15 @@ toolbox\-rm - Remove one or more Toolbx containers
 Removes one or more Toolbx containers from the host. The container should have
 been created using the `toolbox create` command.
 
+Before a container is removed, anything that was exported from it with
+`toolbox export` is removed as well, the same as running
+`toolbox unexport --all --container NAME` against it first. If a file
+couldn't be removed for some reason, this is reported as an error, but the
+container is still removed.
+
 A Toolbx container is an OCI container. Therefore, `toolbox rm` can be used
-interchangeably with `podman rm`.
+interchangeably with `podman rm`, except for the removal of exported files,
+which is a Toolbx concept `podman rm` doesn't know about.
 
 ## OPTIONS ##
 
@@ -49,4 +56,5 @@ $ toolbox rm --all --force
 
 ## SEE ALSO
 
-`toolbox(1)`, `podman(1)`, `podman-rm(1)`
+`toolbox(1)`, `toolbox-export(1)`, `toolbox-unexport(1)`, `podman(1)`,
+`podman-rm(1)`

doc/toolbox-unexport.1.md

@@ -0,0 +1,71 @@
+% toolbox-unexport 1
+
+## NAME
+toolbox\-unexport - Remove an application or a binary exported from a Toolbx container
+
+## SYNOPSIS
+**toolbox unexport** [*--all* | *--app APP* | *--bin BIN*] [*--container NAME*]
+
+## DESCRIPTION
+
+Removes what `toolbox export` made available on the host.
+
+Only files that record the given container are removed. Desktop entries are
+matched by their `X-Toolbx-Container` key, and shell scripts by a comment in
+the same form. A file that was written by hand, or that was exported from a
+different container, is left alone and reported as an error.
+
+Removing an application also removes the icons that were copied along with it,
+from `$XDG_DATA_HOME/toolbx/NAME/icons/APP-ID`.
+
+`toolbox rm` runs the equivalent of `unexport --all` on a container before
+removing it, so anything exported from that container is cleaned up
+automatically. Running `unexport` by hand beforehand is no longer necessary,
+but is still available if only some of the exported items should be removed.
+
+## OPTIONS ##
+
+The following options are understood:
+
+**--all**
+
+Remove everything that was exported from the container. Can't be used together
+with `--app` or `--bin`.
+
+**--app** APP
+
+Remove the application with the given desktop entry. The trailing `.desktop`
+is optional. Can't be used together with `--bin`.
+
+**--bin** BIN
+
+Remove the binary with the given name. Can't be used together with `--app`.
+
+**--container** NAME, **-c** NAME
+
+Remove what was exported from the Toolbx container with the given NAME. This
+is useful when multiple containers are present.
+
+## EXAMPLES
+
+### Remove GIMP exported from the default Toolbx container
+
+```
+$ toolbox unexport --app gimp
+```
+
+### Remove Neovim exported from a container called fedora-toolbox-42
+
+```
+$ toolbox unexport --bin nvim --container fedora-toolbox-42
+```
+
+### Remove a container along with everything exported from it
+
+```
+$ toolbox rm fedora-toolbox-42
+```
+
+## SEE ALSO
+
+`toolbox(1)`, `toolbox-export(1)`, `toolbox-rm(1)`

doc/toolbox.1.md

@@ -137,6 +137,10 @@ Create a new Toolbx container.
 
 Enter a Toolbx container for interactive use.
 
+**toolbox-export(1)**
+
+Export an application or a binary from a Toolbx container.
+
 **toolbox-help(1)**
 
 Display help information about Toolbx.
@@ -161,6 +165,10 @@ Remove one or more Toolbx images.
 
 Run a command in an existing Toolbx container.
 
+**toolbox-unexport(1)**
+
+Remove an application or a binary exported from a Toolbx container.
+
 ## FILES ##
 
 **toolbox.conf(5)**