1/*
2 * Copyright 2017 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Axel D��rfler, axeld@pinc-software.de
7 */
8
9
10/*!
11	\page launch_intro Introduction to the Launch Daemon
12
13In general, you should name your jobs/services after the application signature
14(if possible), and name the configuration files accordingly (in each case
15without the "application/" prefix). Alternatively, you may use the name of your
16package as file name. If you do so, you may want to include the version, too,
17but do not add the version to the name of a job.
18
19A "service" is re-started automatically by the launch_daemon as soon as it's
20quit (or has crashed). Use a "job" instead, if you don't want this behavior.
21
22Let's start with a simple example:
23<code>
24service x-vnd.MyGreatServer {
25}
26</code>
27This will register a service named MyGreatServer, and assumes it uses a BServer
28based application object. It will automatically launch the server either
29during system boot (when you place your configuration file in
30<code>/system/data/launch/</code>), or after user login (when it's in
31<code>~/config/data/launch/</code>) via its signature (which it constructs
32using the job's name). Furthermore, it will create a port for the server, so
33that it can be immediately be talked to.
34
35Unfortunately, BServer is private as of now, and you didn't want to make a
36great effort to subclass it. In this case, you have to notify the launch_daemon
37of this fact by adding a "legacy" to that configuration:
38\code
39service x-vnd.MyGreatServer {
40	legacy
41}
42\endcode
43If you want to save the cycles for querying for your server, you can also
44directly specify the file that should be launched; in this case, the job name
45is just a name. This could look like this:
46\code
47service x-vnd.MyGreatServer {
48	launch /path/to/my/great/server
49	legacy
50}
51\endcode
52This method also allows you to add additional launch arguments like this:
53\code
54service x-vnd.MyGreatServer {
55	launch /path/to/my/great/server --debug-mode
56	legacy
57}
58\endcode
59If you do not want to enable the service by default, but only provide a
60template or basic configuration for the user, you can disable it like this:
61\code
62service x-vnd.MyGreatServer {
63	launch /path/to/my/great/server --debug-mode
64	legacy
65	disabled
66}
67\endcode
68You can then override this in the settings by redefining the service, and
69overwrite the parts you want to change. In this case, it might just be:
70\code
71service x-vnd.MyGreatServer {
72	disabled false
73}
74\endcode
75The rest of the configuration will stay intact.
76
77If you only want to launch your application depending on the current
78environment, you can define conditions which must be met to launch your
79application at all, and events which will trigger launching your application.
80
81In the configuration file, this could look like this:
82\code
83service x-vnd.MyGreatServer {
84	launch /path/to/my/great/server
85	if {
86		not safemode
87		file_exists /path/to/license/file
88	}
89	on {
90		demand
91	}
92}
93\endcode
94Alternatively, there are shortcuts for two of the above items, and you could
95also write it like this:
96\code
97service x-vnd.MyGreatServer {
98	launch /path/to/my/great/server
99	if {
100		file_exists /path/to/license/file
101	}
102	not_safemode
103	on_demand
104}
105\endcode
106If you have only single line conditions/events, you may also omit the curly
107braces completely:
108\code
109service x-vnd.MyGreatServer {
110	launch /path/to/my/great/server
111	if file_exists /path/to/license/file
112	not_safemode
113	on demand
114}
115\endcode
116Note, the "on demand" does not use the "on_demand" shortcut, but just saves the
117curly braces of "on { demand }".
118
119You can also use operators like "and", "or", and "not" in conditions. If you
120put more than one condition into an "if" they must all be true in order to meet
121the condition. Conditions will be evaluated every time the launch_daemon has a
122reason to start your application -- the outcome of the condition may change
123over time.
124
125Likewise, if you put more than one event into an "on" only one of them needs to
126be triggered in order to launch your job. While the event processing is already
127prepared to allow for an "and" operator, this is not yet available.
128
129You can also specify the environment variables for your application. They can
130be either specified directly, or you can let a shell script define them for you:
131\code
132service  x-vnd.MyGreatServer {
133	env {
134		from_script /path/to/my/script.sh
135		LC_TYPE C.UTF-8
136	}
137	launch /path/to/my/great/server
138}
139\endcode
140If you want to move the job into a specific target, you can write it like this:
141\code
142target my-target {
143	service  x-vnd.MyGreatServer {
144		launch /path/to/my/great/server
145	}
146}
147\endcode
148You will be able to move jobs into targets around in the configuration files,
149but this has not been implemented at the time of this writing.
150
151Like jobs, and services, targets can use conditions, events, and environment
152variables. If you do not specify an event for your target, it will not launch
153automatically unless it's requested by name. Furthermore, jobs within your
154target will not be available unless the target has been launched either
155manually or by event.
156
157You can also let the launch_daemon create resources for your application, like
158additional named ports. These ports will be available to other applications
159without having to launch your application, and will belong to the launch_daemon
160throughout their lifetime.
161
162Finally, there is a "run" directive that you can use to launch targets
163unconditionally. The "run" directive also allows to use conditions, but adds
164the additional keywords "then", and "else" like this:
165\code
166run {
167	if read_only
168	then installer
169	else desktop
170}
171\endcode
172You can also use curly braces if you like or want to run more than one job.
173
174It's a good idea to look at the existing configuration files to get an idea how
175this is all supposed to work.
176*/
177