How It Works

This book explains how some aspects of ROX work.

If your question isn't ROX-related (ie, if switching to GNOME or KDE wouldn't make any difference) then try these links:

Application directories

This document details the application directory system, as used in the ROX desktop. Comments are welcome. Programmers writing programs which have nothing to do with the ROX Desktop are still encouraged to consider using this system.

Normally, Unix programs are installed by running a script (possibly inside a Makefile or RPM package) as root. This script scatters files over the filesystem (hopefully without breaking anything). If you're lucky, you may get the option of uninstalling afterwards. It might even work!

Installing programs with this scheme usually requires root access, or a lot of trouble. Sometimes both.

Application directories are self contained applications. The directory contains the program's help files, images, binaries and possibly other things. They may still depend on other libraries, though.

An application directory does not normally need an installer - you can just move it wherever you want. You can `uninstall' an application by deleting the directory. You can run an application directory by clicking on it.

First, I'd like to make a few points clear:

You might also like to read:


Wrappers are tiny application directories which just run an already-installed version of the program. This is useful when you have a lot of non-application-directory packaged software installed already.

See Peter Geer's Wrappers page and the ROX-Wrap project for details.

However, note that ROX-Filer now supports .desktop files. You can often find these in /usr/share/applications or some similar location.

Re-packaging a program as an application directory

The simplest case is something like tgif where you just have an executable and a help file.
The steps would then be:

  1. Create a directory called 'TGIF'
  2. Move the executable inside as 'AppRun'
  3. Put a PNG format icon inside as '.DirIcon'
  4. Create a subdirectory called 'Help' and put the docs inside that
  5. Optionally, create an AppInfo.xml file as explained in the filer's manual (this can be used to show a tooltip for the application, etc).

You should be able to run the application now by clicking on it, copy it to another machine by copying the directory, etc.
For something like Vim with resource files the steps are similar, but put the resources (vim-runtime) into a subdirectory and make the AppRun a shell script that sets the VIMRUNTIME environment variable and runs the binary, eg:


APP_DIR=`dirname $0`
APP_DIR=`cd "$APP_DIR";pwd`

exec "$APP_DIR/Vim" "$@"

For applications which have the pathnames of their resources hard-coded you will need to edit the source code. This guide shows how:

Library Directories

LibDirs are a special case of application directories. They are implemented the same but their use differs in two ways:

They are mainly used to provide libraries:

but can also used to provide other resources:


What about all my existing applications, as installed by RPM/DEB packages?

"Changing the current system to application directories seems like a big change. It also destroys much of the 'old' systems' advantages like automatic updates and dependancy handling, because the packaging systems don't know where you dropped your application directory."

Plain AppDirs do make automatic updates difficult. However, even if you get a package manager to place them in a central directory it's still worth-while keeping each download in its own directory. It prevents conflicts between packages and makes uninstall easier. This is what AddApp does, although this does mean that deleting a launcher doesn't remove the application (instead, you need a cache cleaner similar to APT's deborphan to work out what is no longer required).

"It seems like a great idea, but I'm sure some people have doubts (just as I do right now) as in how to integrate it with current systems. So: How can I integrate existing apps in /usr/bin etc. into Rox? Do I have to create links, or can I create menus, etc?" -- Jens Benecke

You can link executables in /usr/bin to your Apps directory or panel (or run them in place), but you'll have to add the icons manually. A better way is to use the .desktop files usually found in /usr/share/applications; that way they have an icon and a tooltip too.

Configuration settings

~/Choices was the old default location for configuration files in ROX. Now, most programs' settings are stored in the (hidden) ~/.config directory, and under Choices you will just find links to the new locations.

Settings are now namespaced to avoid conflicts. So, ~/Choices/ROX-Filer/Options became ~/.config/

Use the filer's Display menu to show hidden directories, or type /.config in your home directory's window to go straight to it.

This change brings ROX into line with the base directory spec. See the specification for more information about what you can do with this system.

ROX-Lib provides a couple of modules to help you handle configuration. See the Options tutorial for more information.

ROX uses a hierarchical approach to the base directories. Inside the base directory itself is a directory for each source of applications inside which is a directory for each distinct application, plus directories for Shared configuration. For example ROX-Filer uses .../ to store its configuration. Here refers to the source of the application and ROX-Filer the application.

The convention is to use an internet domain name under the control of the authors for the source, thus ensuring that it will be unique. If an author does not have such a domain then a contact email address for the author should be suitable.

Shared configuration

As well as the private configuration data stored in the Configuration settings there is some shared configuration available for many applications.

Shared configuration in

For each MIME type of the form media/subtype there may be an icon in named media_subtype.png. If this exists then it is used in preference to the icon from the current icon theme. If a icon is not found either in MIME-icons or the icon theme then MIME-icons is checked for a generic icon of the name media.png
Thumbnail programs ordered by MIME type, as in the MIME-types directory. When ROX-Filer needs to generate a thumbnail for a file of type media/subtype it looks for an executable program or application with the name, falling back on if that is not found. If the program exists it is executed with three arguments: /path/to/input/file /path/to/output/file size-in-pixels

See Thumbnails of videos and other file types.

The application set as the run action for each file type. When ROX runs a file of MIME type media/subtype it looks up an executable program, script or application called If that is not found it then looks for If a suitable program is found it is then executed.
Handlers for launching URIs. When launching a URI of the form scheme:other-data ROX looks up an executable program, script or application called If a suitable program is found it is then executed with the URI as the sole argument. An exception is made for file: URIs which are always handled by ROX-Filer.

File types and icons

How does the filer decide what icon to show for a file, and which program to use to open it?

For each file, the filer starts by working out its MIME-Type, as follows:

Do not edit the globs and magic files directly, as they are generated from some XML files by the update-mime-database command. If the filer isn't getting the right type for a file, you can use MIME-Editor to change the rules.

Choosing an icon

Having decided on the type, the filer now finds an icon using the Icon spec. By default, this results in loading an icon from ~/.icons/ROX. You can also override the icons using the filer's Set Icon... menu item. See the Theming page for details.

Finding a program to open a file

ROX-Filer looks in your ~/.config/ directory, and tries to run the program with the same name as the MIME type. The easiest way to set a type is by choosing Set Run Action from the menu.

If no program is found various fallbacks are tried: just the first part of the MIME type, and some other configuration directories. See the basedir spec for details.

Zero Install and AddApp

When you run a launcher from the ROX-All package, or a launcher created by AddApp, you are just executing a small script of the form (for ROX-Filer, in this example):


What does this do?

Ignoring the cache for now, it downloads the named resource from the web (you can view it in your browser if you want). This file lists all available versions of ROX-Filer. For each one, it says where it can be downloaded. The 0launch command prompts you to pick one (the default is the newest one), downloads it and runs it.

Isn't it wasteful and slow to keep re-downloading software?
To make this fast, both the page listing the versions and the software itself are stored on your local computer (by default, under ~/.cache/ The next time you run it, it won't need to use the network at all.
Why is it called Zero Install?
Because you don't ask the computer to install software. You ask it to run it. Having it stored on your computer is an automatic side-effect.
What security features does it offer?
The list of versions is signed with GPG. If the key isn't known, you'll be prompted to confirm that you trust it.
The list includes cryptographic digests of each version, so the archives get checked too after they're unpacked.
Everything happens as a normal user, not as root, so there is less risk of users harming each other by running dodgy software.
What about programs that require lots of libraries?
As well as the main file listing all versions of the software, it also states what libraries each one requires. The 0launch command will download those and add them to the cache too.
Will this conflict with other software on my system?
In general, no. 0launch only puts things in your ~/.cache/ directory (nowhere else), with a different sub-directory for every version it downloads. Of course, as with any software, actually running the programs themselves may affect your system... that depends what you choose to run ;-)
I tried Zero Install, and now ROX-Session keeps trying to download programs I already have!
ROX-Session supports both traditional packages (e.g., running ROX-Filer with /usr/bin/rox) and Zero Install (using 0launch). By default, if it sees that the 0launch command is available then it will use that. To avoid downloading a second copy of ROX-Filer, you can use 0launch --feed /path/to/ROX-Filer.xml to tell 0launch about your existing copy. Having two copies on your system shouldn't cause any problems, however. Also, newer versions of 0launch are able to use distribution packages when available.
Do I have to use Zero Install to get ROX?
No, there are many ways to get the software. You can download the archives and extract them manually if you prefer, and there are packages available for various distributions. However, using Zero Install does mean you get exactly the same software we released, makes it easier for us to track down problems (we know they can't have been introduced by the packagers) and means you always have the latest version available (in addition to the advantages listed above). A few things don't work fully without it (for example, clicking on the Edit MIME rules button in ROX-Filer's Options box will run MIME-Editor if 0launch is available, or just tell you where to download MIME-Editor if not).
What does Can't find all required implementations mean?
It means that the injector couldn't find a suitable version of some component needed to run the program. Usually, this is either because you haven't run the program before and you've selected offline mode, or you have an unusual architecture for which there is currently no binary (see the ROX-Filer binary tutorial for how to compile from source). If you have any problems, please read the injector's trouble-shooting guide.
Sounds interesting... where can I learn more?
See the site for details. Also, the Decentralised Installation Systems essay gives an introduction to systems like Zero Install.