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 do not need to change your PATH variable to use an application directory. To be found by the shell (which must be application-directory aware) it is only required that the application directory be in a PATH directory (eg '/usr/local/bin'), not that PATH point inside the application.
• Normally, you can just click on an application to run it - no need to worry about PATH at all.
• In a network environment, an application directory may contain multiple binaries (one for each platform) and will run the correct one when you click it.
• Application directories may contain source code and will then automatically compile themselves when first run.
• User choices are stored outside of the application directory. See the configuration system page for details.
• Searching (for help) from the command-line is just as easy as searching /usr/doc - just search in 'Apps/*/Help'.
• Application directories are not a new idea. They are already used by RISC OS, NextStep, MacOS and various other systems.
• Application directories do not conflict with automatic dependancy handling systems such as RPM and apt. They do, however, allow much simpler, faster and more robust systems, such as Zero Install.

You might also like to read:

• The ROX-Filer manual chapter on application directories.
• My Freshmeat article about them.
• The tutorial on creating a simple ROX application.
• I am not clueless on the design of GoboLinux (most of the points apply to application directories too).

Wrappers

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 freedesktop.org .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:

#!/bin/sh

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

VIMRUNTIME="$APP_DIR/runtime"; export VIMRUNTIME
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:

• Guide to Making Relocatable Applications (autopackage.org)

Library Directories

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

• They are not normally run by the user (except perhaps to configure them), but are used by other programs.
• They are not stored in the same place as application directories (~/Apps, /usr/local/apps, /usr/apps) but are stored in the same place as libraries (~/lib, /usr/local/lib, /usr/lib).

They are mainly used to provide libraries:

• ROX-Lib
• ROX-CLib

but can also used to provide other resources:

• Download Handler
• Thumbnail Helper

Links

• D. J. Bernstein proposes something similar in slashpackage.

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/rox.sourceforge.net/ROX-Filer/Options.

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 freedesktop.org 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 .../rox.sourceforge.net/ROX-Filer to store its configuration. Here rox.sourceforge.net 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.

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:

• If the file's user.mime_type extended attribute it set, then that is its MIME type.
• If the file's name matches a pattern in one of the globs file (usually, /usr/share/mime/globs) then the line in that file gives the type.
• If the contents of the file match a pattern in one of the magic files (usually, /usr/share/mime/magic) then that gives the type.
• Otherwise, it is text/plain (looks like text), application/x-executable (marked as executable) or application/x-octet-stream (doesn't look like UTF-8 text).

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 freedesktop.org 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/rox.sourceforge.net/MIME-types 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 freedesktop.org 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):

0launch http://rox.sourceforge.net/2005/interfaces/ROX-Filer

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/0install.net). 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/0install.net 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 0install.net site for details. Also, the Decentralised Installation Systems essay gives an introduction to systems like Zero Install.