summaryrefslogtreecommitdiff
path: root/Software/xdg-utils.mdwn
blob: 5c3e8d8b6396f4502eac9dee3cff1ebf320bea2a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# xdg-utils

xdg-utils is a set of tools that allows applications to easily
integrate with the desktop environment of the user, regardless of the
specific desktop environment that the user runs.

About half of the tools focus on tasks commonly required during the
installation of a desktop application and the other half focuses on
integration with the desktop environment while the application is
running.

## Download

* [Releases](http://portland.freedesktop.org/download/)
* [Git repository](http://cgit.freedesktop.org/xdg/xdg-utils/)

## Included utilities

Each utility's name is linked to its manual page.

* [xdg-desktop-menu](http://portland.freedesktop.org/doc/xdg-desktop-menu.html) -
  Install desktop menu items
* [xdg-desktop-icon](http://portland.freedesktop.org/doc/xdg-desktop-icon.html) -
  Install icons on the user's desktop
* [xdg-email](http://portland.freedesktop.org/doc/xdg-email.html) -
  Compose a new email in the user's preferred email client,
  potentially with subject and other info filled in
* [xdg-icon-resource](http://portland.freedesktop.org/doc/xdg-icon-resource.html) -
  Install icon resources
* [xdg-mime](http://portland.freedesktop.org/doc/xdg-mime.html) -
  Query and install MIME types and associations
* [xdg-open](http://portland.freedesktop.org/doc/xdg-open.html) - Open
  a URL in the user's preferred application that handles the
  respective URL or file type
* [xdg-screensaver](http://portland.freedesktop.org/doc/xdg-screensaver.html) -
  Enable, disable, or suspend the screensaver
* [xdg-settings](http://portland.freedesktop.org/doc/xdg-settings.html) -
  Get or set the default web browser and URL handlers

## Using xdg-utils

Although we expect that these scripts will generally come as part
of the operating system, we recommend that you package the scripts
that your application needs along with your product as a fallback.

We recommend that you place these scripts in a directory, and then add
that directory to the end of the `$PATH`.  So, let's say that you're
writing your post installation script, and you want to create a menu
item on any XDG compliant environment.  Let's further assume that
you've just installed to `$INSTALL_DIR`, and that your desktop file is
in `$INSTALL_DIR/mycompany-myapp.desktop`.  Finally, let's say that
you've included the xdg-utils package in your installation in
`$INSTALL_DIR/xdg-utils`.

Then a simple post install script could look like this:

    export PATH=$PATH:$INSTALL_DIR/xdg-utils/scripts
    xdg-desktop-menu install $INSTALL_DIR/mycompany-myapp.desktop

And now your product has a menu item on any XDG compliant desktop!

Note that we strongly recommend using this method - that is, putting
your copy of the xdg-utils at the end of the path, and then invoking
them without a specific path name. That will allow your users and
their system providers to use custom versions of the xdg-utils to
adjust for system specific differences.

If you wish to absolutely force the issue and only use the versions
you shipped, you could instead hard code the path to the version
you bundle with your application.  We strongly recommend against
this, as it will make your product obsolete more quickly than is
necessary.

## Relevant specifications

* [[Desktop base directory specification|Specifications/basedir-spec]]
* [[Desktop entry specification|Specifications/desktop-entry-spec]]
* [[Menu specification|Specifications/menu-spec]]
* [[Shared MIME database|Specifications/shared-mime-info-spec]]
* [[Icon Theme specification|Specifications/icon-theme-spec]]
* [[MIME applications specification|Specifications/mime-apps-spec]]
* [[File URI specification|Specifications/file-uri-spec]]

## Bugs

* [Report a bug](https://gitlab.freedesktop.org/xdg/xdg-utils/issues/new)
* [Currently open bugs](https://gitlab.freedesktop.org/xdg/xdg-utils/issues)

## Contact

* [Mailing list](http://lists.freedesktop.org/mailman/listinfo/portland)