Changes between Initial Version and Version 1 of Obsolete/MovedToTree/LaunchDaemon


Ignore:
Timestamp:
Jul 17, 2015, 8:48:45 PM (4 years ago)
Author:
axeld
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Obsolete/MovedToTree/LaunchDaemon

    v1 v1  
     1== launch_daemon configuration ==
     2
     3In general, you should name your jobs/services after the application signature (if possible), and name the configuration files accordingly (in each case without the "application/" prefix). Alternatively, you may use the name of your package as file name. If you do so, you may want to include the version, too, but do not add the version to the name of a job.
     4
     5Let's start with a simple example:
     6{{{
     7service x-vnd.MyGreatServer {
     8}
     9}}}
     10This will register a service named MyGreatServer, and assumes it uses a BServer based application object. It will automatically launch the server either during system boot (when you place your configuration file in /system/data/launch/), or after user login (when it's in ~/config/data/launch/) via its signature (which it constructs using the job's name). Furthermore, it will create a port for the server, so that it can be immediately be talked to.
     11
     12Unfortunately, BServer is private as of now, and you didn't want to make a great effort to subclass it. In this case, you have to notify the launch_daemon of this fact by adding a "legacy" to that configuration:
     13{{{
     14service x-vnd.MyGreatServer {
     15        legacy
     16}
     17}}}
     18If you want to save the cycles for querying for your server, you can also directly specify the file that should be launched; in this case, the job name is just a name. This could look like this:
     19{{{
     20service x-vnd.MyGreatServer {
     21        launch /path/to/my/great/server
     22        legacy
     23}
     24}}}
     25This method also allows you to add additional launch arguments like this:
     26{{{
     27service x-vnd.MyGreatServer {
     28        launch /path/to/my/great/server --debug-mode
     29        legacy
     30}
     31}}}
     32If you do not want to enable the service by default, but only provide a template or basic configuration for the user, you can disable it like this:
     33{{{
     34service x-vnd.MyGreatServer {
     35        launch /path/to/my/great/server --debug-mode
     36        legacy
     37        disabled
     38}
     39}}}
     40You can then override this in the settings by redefining the service, and overwrite the parts you want to change. In this case, it might just be:
     41{{{
     42service x-vnd.MyGreatServer {
     43        disabled false
     44}
     45}}}
     46The rest of the configuration will stay intact.
     47
     48If you only want to launch your application depending on the current environment, you can define conditions which must be met to launch your application at all, and events which will trigger launching your application.
     49In the configuration file, this could look like this:
     50{{{
     51service x-vnd.MyGreatServer {
     52        launch /path/to/my/great/server
     53        if {
     54                not safemode
     55                file_exists /path/to/license/file
     56        }
     57        on {
     58                demand
     59        }
     60}
     61}}}
     62Alternatively, there are shortcuts for two of the above items, and you could also write it like this:
     63{{{
     64service x-vnd.MyGreatServer {
     65        launch /path/to/my/great/server
     66        if {
     67                file_exists /path/to/license/file
     68        }
     69        not_safemode
     70        on_demand
     71}
     72}}}
     73If you have only single line conditions/events, you may also omit the curly braces completely:
     74{{{
     75service x-vnd.MyGreatServer {
     76        launch /path/to/my/great/server
     77        if file_exists /path/to/license/file
     78        not_safemode
     79        on demand
     80}
     81}}}
     82Note, the "on demand" does not use the "on_demand" shortcut, but just saves the curly braces of "on { demand }".
     83You can also use operators like "and", "or", and "not" in conditions. If you put more than one condition into an "if" they must all be true in order to meet the condition. Conditions will be evaluated every time the launch_daemon has a reason to start your application -- the outcome of the condition may change over time.
     84Likewise, if you put more than one event into an "on" only one of them needs to be triggered in order to launch your job. While the event processing is already prepared to allow for an "and" operator, this is not yet available.
     85
     86You can also specify the environment variables for your application. They can be either specified directly, or you can let a shell script define them for you:
     87{{{
     88service  x-vnd.MyGreatServer {
     89        env {
     90                from_script /path/to/my/script.sh
     91                LC_TYPE C.UTF-8
     92        }
     93        launch /path/to/my/great/server
     94}
     95}}}
     96If you want to move the job into a specific target, you can write it like this:
     97{{{
     98target my-target {
     99        service  x-vnd.MyGreatServer {
     100                launch /path/to/my/great/server
     101        }
     102}
     103}}}
     104You will be able to move jobs into targets around in the configuration files, but this has not been implemented at the time of this writing.
     105Like jobs, and services, targets can use conditions, events, and environment variables. If you do not specify an event for your target, it will not launch automatically unless it's requested by name. Furthermore, jobs within your target will not be available unless the target has been launched either manually or by event.
     106
     107You can also let the launch_daemon create resources for your application, like additional named ports. These ports will be available to other applications without having to launch your application, and will belong to the launch_daemon throughout their lifetime.
     108
     109Finally, there is a "run" directive that you can use to launch targets unconditionally. The "run" directive also allows to use conditions, but adds the additional keywords "then", and "else" like this:
     110{{{
     111run {
     112        if read_only
     113        then installer
     114        else desktop
     115}
     116}}}
     117You can also use curly braces if you like or want to run more than one job.
     118
     119It's a good idea to look at the existing configuration files to get an idea how this is all supposed to work.