README

Short intruction to how glick works:

There is a main fuse filesystem (glick-fs) that automatically mounts itself
on ~/.glick when run. Inside this there is an "exports" directory where
everything that gets exported from installed bundles are exposed. The idea is
that ~/.glick/exports/share gets put in your XDG_DATA_DIRS and XDG_CONFIG_DIRS
environment variable to get the desktop environment to pick this up.

This is all handled by the glick-session helper, which you need to run
in the xinit script such that it is a parent of the main X session process.
This helper does a bunch of things:
 * It creates a new mount namespace for the desktop session to isolate it
   from other sessions
 * It creates the per-session /opt/session directory with symlinks to
   ~/.glick/bundles and ~/.glick/exports.
 * It makes all other mounts rshared in the session namespace, which means
   that by default anything that gets mounted inside the session or in
   child namespaces (such as bundles) get propagated to all the other
   session namespaces.
 * It sets up the XDG_DATA_DIRS and XDG_CONFIG_DIRS env vars.

As mentioned above, there is also a ~/.glick/bundles subdirectory, where
symbolic links to installed bundles appears, named by the bundle ids. Since
this is in the session directory we can use absolute pathnames like
/opt/session/bundles/<bundle-id> to refer to the bundle binaies in for
instance desktop files.

In addition to the exports and bundles directory each currently mounted bundle
also appears in the ~/.glick directory. This way other application can look into
the files from a running bundle. This is useful for instance when the application
wants the help reader to display the applications help file, but the help reader
might be running outside the bundle namespace. To facilitate this glick sets
the BUNDLE_PREFIX environment variable to point to the publically visible prefix
for the bundle.

glick-fs looks for installed bundles in ~/.local/bundles and $libdir/bundles. It
also installs an inotify watch to pick up changes to these directories at
runtime.

In a typical glick-integrated setup glick-fs will be started by the session
using an autostart desktop file. However, if its not running when you start
a bundle it will be started automatically.

Bundles are started by using the glick-runner binary, like:

  glick-runner foo.bundle --args --for --app

However, for easier use glick2 ships with a binfmt_misc config file
that gets installed in $sysconfdir/glick2.conf. If your distribution
supports this that means you only need to make sure your bundles
have execute permissions and you can launch them directly.

Bundles list a default executable in the metadata, but you can also
start other executables inside the bundle like:
 glick-runner foo.bundle -exec bin/alt_app --some --args
or
 ./foo.bundle -exec bin/alt_app --some --args

When a bundle is started it connects to the glick filesystem, requesting
the bundle to be mounted (by opening ~/.glick/socket and passing the open
fd to it), and then the setuid helper $libexecdir/glick-helper creates
a new mount namespace for the bundle process and binds mounts /opt/bundle to
the ~/.glick/<subdir> where the bundle gets mounted. This means you can
build your bundles with a static prefix of /opt/bundle and each bundle
instance will see its files there. When the last process in the bundle
exits the bundle will automatically be unmounted.

Bundles are created with the glick-mkbundle program. You pass it a directory
and a filename, and it will create a bundle containing all the files in
the directory. Additionally you have to specify a bundle id and a version.
Bundle ids look like dbus/java style reverse dns names (org.domain.my.MyApp) and
version is supposed to be an rpm-style version string.

Additionally you can specify a set of exports which is files that should be
put in the "exports" dir when the bundle is installed. Typically things like
desktop files, app icons and custom mimetypes. There are some built in triggers
inside glick that will automatically do things like rebuild icon caches and
mime databases when files are added in the right directories.

So, a typical bundle creation would be something like:
./configure --prefix=/opt/bundle
make
make install DESTDIR=/tmp
glick-mkbundle -i org.gnome.App -v 1.1.2 -e bin/the_app \
   -E /share/mime-info -E /share/icons -E /share/applications \
   /tmp/opt/bundle app.bundle

Although, ideally when building a set of bundles common binaries for
dependencies should be used to maximize file sharing between bundles.