Building an xdg-app – part 1

Welcome to part 1 in this multi-part tutorial in how to create xdg-app applications.

First of all you need to install xdg-app. Fedora 23 ships with xdg-app packages, but some distributions do not. I have made this page with packages that you can use.

This tutorial is using xdg-app 0.4.12, which is the latest version. Older versions should work too, but minor things may need to be changed in the commands, and not all features may be supported.

A fundamental concept in xdg-app is the runtime/application split. Every app depends on a runtime, which supplies the core libraries that the app relies on. Runtimes are typically shared by many applications, but a user can have multiple runtimes installed at the same time.

For this tutorial we will be using the gnome nightly build runtime. It is available in a xdg-app repostitory on If you tried the gnome nightly builds from my previous blog entry you will have these already, but otherwise you can get it by doing:

$ wget
$ xdg-app --user remote-add --gpg-key=gnome-sdk.gpg gnome
$ xdg-app --user install gnome org.gnome.Platform 3.20

Once it is installed you can also update it by doing:

xdg-app --user update org.gnome.Platform 3.20

Now we have all that we need to create a simple application. Lets start by writing an application. Put this in a file called “”:

echo "Hello world, from a sandbox"

Then we need some information about the application. In xdg-app this is in specified in a key-value file called “metadata”. For a simple app like this it doesn’t contain much, so we can create it manually:


This specifies the application identifier (org.test.Hello) as well as the runtime the application uses and the command to start the app with.

An xdg-app really doesn’t require more than this, although the application must have a special layout. Using these sources we can create an application directory “appdir” like this:

mkdir appdir
mkdir appdir/files
mkdir appdir/files/bin
mkdir appdir/export
cp metadata appdir/
cp appdir/files/bin/
chmod a+x appdir/files/bin/

In order for xdg-app to be able to install this application we need to put it in an  repository. This is done with the build-export command:

xdg-app build-export repo appdir

This will initialize a local repository in the directory “repo”  and export the app to it. We can test it using:

xdg-app --user remote-add --no-gpg-verify tutorial-repo repo
xdg-app --user install tutorial-repo org.test.Hello
xdg-app run org.test.Hello

This will print “Hello world, from a sandbox”, which means we just created, packaged, installed and ran our first xdg-app application!

If you want to examine the sandbox a bit you can use the –command=sh argument to xdg-app run, which will give you a shell inside the application sandbox where you can explore the sandbox. For example:

[alex@localhost ~]$ xdg-app run --command=sh org.test.Hello
sh-4.3$ ls -lR /app
total 0
drwxr-xr-x 1 alex wheel 16 jan 1 1970 bin
total 4
-rwxr-xr-x 2 alex wheel 45 jan 1 1970
sh-4.3$ echo $PATH
Hello world, from a sandbox
sh-4.3$ ls -la ~/
total 0
drwxr-xr-x 3 alex wheel 60 feb 19 16:11 .
drwxr-xr-x 3 alex wheel 60 feb 19 16:11 ..
drwxr-xr-x 3 alex wheel 60 feb 19 16:11 .var
sh-4.3$ ls ~/.var/app/org.test.Hello/
cache  config  data

Here we see that all the files from the application appears in /app, and PATH points to /app/bin which means you can easily run it. We also see that by default the application has no access to any files from the users home directory (it’s empty) other than the ~/.var/app/org.test.Hello directory where the app can store its own data. You can also explore /usr, which comes from the runtime.

This is a very manual approach to creating a xdg-app, in the next part of this tutorial we will look at how to use the “xdg-app build” command and an SDK to build applications.

20 thoughts on “Building an xdg-app – part 1”

  1. How do I build my own runtime?

    Maybe you could blog about that topic at some point. You will need people to be able to build Qt/KDE runtumes at some point If you do not want xdg-app to stay gnome-only.

  2. I’ve followed all required steps, but when i run xdg-app –user install gnome-nightly org.gnome.Platform i get this “error: Can’t find org.gnome.Platform master in remote gnome-nightly”. So, how can i solve this?

  3. I have ubuntu 14.04 these are my steps:
    sudo add-apt-repository ppa:alexlarsson/xdg-app
    sudo apt-get update
    sudo apt-get install xdg-app
    xdg-app –user remote-add –gpg-key=nightly.gpg gnome-nightly
    xdg-app –user install gnome-nightly org.gnome.Platform
    error: Can’t find org.gnome.Platform master in remote gnome-nightly

    I’ve tried to remove my ~/.local/share/xdg-app like you did, but i get always “error: Can’t find org.gnome.Platform master in remote gnome-nightly” you’re right, that’s weird. Ok man thanks anyway.

  4. I tried the steps from the blogpost. When trying to install the Platform it says I have no permission to access the server.

    error: Server returned status 403: Forbidden

    Is something broken in my install or is it a real Serverside Problem?
    I am running xdg-app 0.4.12 on ArchLinux

Leave a Reply

Your email address will not be published. Required fields are marked *