README
1xdg-utils
2---------
3
4 The xdg-utils package is a set of simple scripts that provide
5basic desktop integration functions for any Free Desktop, such as Linux.
6
7 They are intended to provide a set of defacto standards. This
8means that:
9 * Third party software developers can rely on these xdg-utils
10 for all of their simple integration needs.
11
12 * Developers of desktop environments can make sure that their
13 environments are well supported
14
15 If a desktop developer wants to be certain that their environment
16 functions with all third party software, then can simply
17 make sure that these utilities work properly in their environment.
18
19 This will hopefully mean that 'third tier' window managers
20 such as XFCE and Blackbox can reach full parity with Gnome and KDE
21 in terms of third party ISV support.
22
23 * Distribution vendors can provide custom versions of these utilities
24
25 If a distribution vendor wishes to have unusual systems,
26 they can provide custom scripts, and the third party software
27 should still continue to work.
28
29
30OVERVIEW:
31---------
32
33 The following tools are included in xdg-utils 1.0:
34
35xdg-desktop-menu Install desktop menu items
36xdg-desktop-icon Install icons to the desktop
37xdg-icon-resource Install icon resources
38xdg-mime Query information about file type handling and
39 install descriptions for new file types
40xdg-open Open a file or URL in the user's preferred application
41xdg-email Send mail using the user's preferred e-mail composer
42xdg-screensaver Control the screensaver
43
44
45BUILD:
46------
47
48 Building is not required, all tools are located in the
49scripts/ subdirectory and are ready to be used.
50
51 You can optionally choose to install the scripts
52to a target directory. To do this, you could issue
53the following commands:
54 ./configure [--prefix=<your-place-here>]
55 make install
56that would cause the scripts to be installed to
57 <your-place-here>/bin
58
59
60USE:
61----
62
63 Although we expect that these scripts will generally come as part
64of the operating system, we recommend that you package the scripts
65that your application needs along with your product as a fallback. For
66this purpose please obtain the original version of the xdg-utils from
67http://portland.freedesktop.org. The xdg-utils scripts that are
68distributed by operating systems vendors may have been tuned for their
69particular operating system and may not work on the same broad variety
70of operating systems as the original version.
71
72 We recommend that you place these scripts in a directory, and
73then add that directory to the end of the PATH. So, let's say that
74you're writing your post installation script, and you want to create
75a menu on any xdg-util compliant environment. Let's further assume
76that you've just installed to $INSTALL_DIR, and that your menu
77desktop file is in $INSTALL_DIR/desktop/icon.desktop. Finally, let's
78say that you've included the xdg-utils package in your installation
79in $INSTALL_DIR/xdg-utils.
80
81 Then a simple post install script could look like this:
82
83 export PATH=$PATH:$INSTALL_DIR/xdg-utils
84 xdg-desktop-menu install $INSTALL_DIR/mycompany-myapp.desktop
85
86 And now your product has a menu on any XDG compliant desktop!
87
88Note that we strongly recommend using this method - that is,
89putting your copy of the xdg-utils at the end of the path,
90and then invoking them without a specific path name.
91
92That will allow your users and their system providers to
93use custom versions of the xdg-utils to adjust for system specific
94differences.
95
96If you wish to absolutely force the issue and only use the versions
97you shipped, you could instead hard code the path to the version
98you bundle with your application. We strongly recommend against
99this, as it will make your product obsolete more quickly than is
100necessary.
101