summaryrefslogtreecommitdiffstats
path: root/autostart/autostart-spec.xml
blob: 1a996da654c7821a05550ad57932338522afdec6 (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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY version "0.5">
  <!ENTITY dtd-version "0.5">
				  ]>

<article id="index">
  <articleinfo>
    <title>Desktop Application Autostart Specification</title>
    <releaseinfo>Version &version;</releaseinfo>
    <pubdate>13 February 2006</pubdate>
    <authorgroup>
      <author>
	<firstname>John</firstname>
	<surname>Palmieri</surname>
	<affiliation>
	  <address>
	    <email>johnp@redhat.com</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Kévin</firstname>
	<surname>Ottens</surname>
	<affiliation>
	  <address>
	    <email>ervin@ipsquad.net</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Renato</firstname>
	<surname>Caldas</surname>
	<affiliation>
	  <address>
	    <email>seventhguardian_@hotmail.com</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Rodrigo</firstname>
	<surname>Moya</surname>
	<affiliation>
	  <address>
	    <email>rodrigo@gnome-db.org</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Waldo</firstname>
	<surname>Bastian</surname>
	<affiliation>
	  <address>
	    <email>bastian@kde.org</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>
  </articleinfo>

  <sect1 id="introduction">
    <title>Introduction</title>
    <para>
      This DRAFT document defines a method for automatically starting
      applications during the startup of a desktop environment and after
      mounting a removable medium.
    </para>
    <para>
      Some of the file locations in this specification are specified based
      on the <ulink url="http://standards.freedesktop.org/basedir-spec/">
      "desktop base directory specification"</ulink>.
    </para>
    <para>
     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
     NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
     "OPTIONAL" in this document are to be interpreted as
     described in RFC 2119.
    </para>
  </sect1>
  <sect1 id="startup">
    <title>Autostart Of Applications During Startup</title>
    <para>
      By placing an application's .desktop file
      in one of the Autostart directories the application will be
      automatically launched during startup of the user's desktop environment after the user
      has logged in.
    </para>
    <sect2>
      <title>Autostart Directories</title>
      <para>
        The Autostart Directories are $XDG_CONFIG_DIRS/autostart as defined
        in accordance with the
        <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html#referencing">
        "Referencing this specification"</ulink> section in the
        <ulink url="http://standards.freedesktop.org/basedir-spec/">
        "desktop base directory specification"</ulink>.        
      </para>
      <para>
        If the same filename is located under multiple Autostart Directories
        only the file under the most important directory should be used.
      </para>
      <informalexample>
        <para>
          Example: If $XDG_CONFIG_HOME is not set the Autostart Directory
          in the user's home directory is ~/.config/autostart/
        </para>
      </informalexample>
      <informalexample>
        <para>
          Example: If $XDG_CONFIG_DIRS is not set the system wide Autostart
          Directory is /etc/xdg/autostart/
        </para>
      </informalexample>
      <informalexample>
        <para>
          Example: If $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS are not set and
          the two files /etc/xdg/autostart/foo.desktop and
          ~/.config/autostart/foo.desktop exist then only the file 
          ~/.config/autostart/foo.desktop will be used because
          ~/.config/autostart/ is more important than /etc/xdg/autostart/
        </para>
      </informalexample>
    </sect2>
    <sect2>
      <title>Application .desktop Files</title>
      <para>
        An application .desktop file must have the format as defined in
        the <ulink url="http://standards.freedesktop.org/desktop-entry-spec/">
        "Desktop Entry Specification"</ulink>. All keys should be
        interpreted as defined with the following exceptions in order to
        take into account that the .desktop files in an autostart directory
        are not shown in a menu.
      </para>
      <sect3>
        <title>Hidden Key</title>
        <para>
          When the .desktop file has the Hidden key set to true, the .desktop
          file MUST be ignored. When multiple .desktop files with the
          same name exists in multiple directories then only the Hidden key
          in the most important .desktop file must be considered: If it is
          set to true all .desktop files with the same name
          in the other directories MUST be ignored as well.
        </para>
      </sect3>
      <sect3>
        <title>OnlyShowIn and NotShowIn Keys</title>
        <para>
          The OnlyShownIn entry may contain a list of strings identifying
          the desktop environments that MUST autostart this application,
          all other desktop environments MUST NOT autostart this application.
        </para>
        <para>
          The NotShownIn entry may contain a list of strings identifying
          the desktop environments that MUST NOT autostart this
          application, all other desktop environments MUST autostart this
          application.
        </para>
        <para>
          Only one of these keys, either OnlyShowIn or NotShowIn, may appear
          in a single .desktop file.
        </para>
      </sect3>
      <sect3>
        <title>TryExec Key</title>
        <para>
          A .desktop file with a non-empty TryExec field MUST NOT be
          autostarted if the value of the TryExec key does NOT match with
          an installed executable program. The value of the TryExec field
          may either be an absolute path or the name of an executable
          without any path components. If the name of an executable is
          specified without any path components then the $PATH environment
          is searched to find a matching executable program.
        </para>
      </sect3>
    </sect2>
    <sect2>
      <title>Implementation Notes</title>
      <informalexample>
        <para>
          If an application autostarts by having a .desktop file installed
          in the system wide autostart directory, an individual user can
          disable the autotomatic start of this application by placing a
          .desktop file of the same name in its personal autostart directory
          which contains the key Hidden=true.
        </para>
      </informalexample>
    </sect2>
  </sect1>
  <sect1 id="mounting">
    <title>Autostart Of Applications After Mount</title>
    <para>
      When a desktop environment mounts a new medium, the medium may contain
      an Autostart file that can suggest to start an application or
      an Autoopen file that can suggest to open a specific file located
      on the medium.
    </para>
   <sect2>
      <title>Autostart Files</title>
      <para>
        When a new medium is mounted the root directory of the medium should
        be checked for the following Autostart files in order of precendence: 
        .autorun, autorun, autorun.sh
        Only the first file that is present should be considered.
      </para>
      <para>
        The desktop environment MAY ignore Autostart files altogether
        based on policy set by the user, system administrator or vendor.
      </para>
      <para>
        The desktop environment MUST prompt the user for confirmation before
        automatically starting an application.
      </para>
      <para>
        When an Autostart file has been detected and the user has confirmed
        its execution the autostart file MUST be executed with the
        current working directory (CWD) set to the root directory of the
        medium.
      </para>
   </sect2>
   <sect2>
      <title>Autoopen Files</title>
      <para>
        When a new medium is mounted and a) the medium does not contain an
        Autostart file or b) a policy to ignore Autostart files is in effect
        then the root directory of the medium should be checked for the
        following Autoopen files in order of precedence:
        .autoopen, autoopen .
        Only the first file that is present should be considered.
     </para>
      <para>
        The desktop environment MAY ignore Autoopen files altogether
        based on policy set by the user, system administrator or vendor.
      </para>
      <para>
        An Autoopen file MUST contain a single relative path that points to
        a non-executable file contained on the medium.
        If the file contains a newline or carriage return character then the
        newline or carriage return character itself and all characters that
        follow MUST be ignored.
      </para>
      <para>
        The relative path MUST NOT contain path components that refer to a
        parent directory (../)
      </para>
      <para>
        The relative path MUST NOT point to an executable file.
      </para>
      <para>
        The desktop environment MUST verify that the relative path points to
        a file that is actually located on the medium, taking into account any
        symbolic or other links and MUST ignore any relative path that
        points to a file location outside the medium itself.
      </para>
      <para>
        If the relative path points to an executable file then the desktop
        environment MUST NOT execute the file.
      </para>
      <para>
        The desktop environment MUST prompt the user for confirmation before
        opening the file.
      </para>
      <para>
        When an Autoopen file has been detected and the user has confirmed
        that the file indicated in the Autoopen file should be opened then
        the file indicated in the Autoopen file MUST be opened in the
        application normally preferred by the user for files of its kind
        UNLESS the user instructed otherwise.
      </para>
     </sect2>
  </sect1>

</article>