From 087097faa52791f941daaab5c14200a470f6aebe Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 7 Jul 2015 21:11:25 +0000 Subject: - More doc! - Cosmetic fixes in s6-rc-compile --- doc/s6-rc-compile.html | 311 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 218 insertions(+), 93 deletions(-) (limited to 'doc/s6-rc-compile.html') diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html index 33d8bcd..4d9aeeb 100644 --- a/doc/s6-rc-compile.html +++ b/doc/s6-rc-compile.html @@ -19,145 +19,270 @@

The s6-rc-compile program

- s6-rc is a machine state manager: it brings the machine to a -desired state, by starting or stopping services as needed. + s6-rc-compile is a service database compiler. It takes a series +of service definitions in the source format, and compiles +them into a directory, which is the compiled format. +

+ +

+ The administrator can then examine that compiled database via +s6-rc-db, put it into a place where +it will be registered at boot time as the current compiled database +by s6-rc-init, or even live update +the current service database via +s6-rc-update.

Interface 

-     s6-rc [ -v verbosity ] [ servicenames... ]
+     s6-rc-compile [ -v verbosity ] compiled source...

Options

-

s6-rc control

- + +

Source format

+ +

+ s6-rc-compile scans every source directory to find +service definition directories in it. It ignores every +file that is not a directory, or that starts with a dot. For +every service definition directory that it finds, it creates a +service with the same name as the directory. Names cannot be +duplicated and cannot contain a slash or a newline; they can +contain spaces and tabs, but using anything else than alphanumerical +characters, underscores and dashes is discouraged - the s6-rc programs +will handle weird names just fine, but other tools, especially +shell scripts, may not. +

+ +

+ Every service +definition directory service is expected to contain the following files: +

+ +

For every service

+ + + +

For bundles

+ + -

Up or down

+

+ It is possible to use bundle names in a contents file. +However, if s6-rc-compile detects a cycle in bundle definitions, it will +complain and exit 1. +

+ +

For atomic services

-

Service selection

+

+ It is unnecessary to manually define complete sets of dependencies in the +dependency file, because +s6-rc will properly handle dependency chains. +anyway. If A depends on B, no matter the underlying +implementation of B, and the current implementation of B +depends on C, then you should just put B in +A/dependencies; when starting the set, +s6-rc will start C first, then +B, then A. If the underlying implementation of B +changes and does not depend on C, then you will just have to +modify the dependencies for B, not for A +

+ +

+ Of course, if A depends on C anyway, you should add +both B and C to A/dependencies. +

+ +

+ If s6-rc-compile detects a cycle in dependencies across services, it will +complain and exit 1. +

+ +

For oneshots

-

Actions

+ +

+ up and down are interpreted by +execlineb, but +that does not mean they have to be entirely written in the +execline language. The +execlineb +lexer is only used because it can compile a Unix command line from a text file +and store the compiled result, whereas a shell would have to be invoked +everytime the script is run. There are many ways to write up and +down scripts: +

-

Usage examples

+

+ Don't think you have to learn all the intricacies of the execline language +just because the up and down scripts get lexed by it. +You don't. +

+ +

For longruns

-
 s6-rc myservicebundle

- Brings up all the services represented by myservicebundle, -dependencies first. + The s6-rc service definition directory for a longrun service is similar to +a s6 service +directory, but there are a few differences:

-
 s6-rc -Sad
+ +

- Brings down all the services in an orderly manner. This is typically -run at shutdown time. + The following files must or may appear in a longrun definition directory:

-
 s6-rc -Au myservicebundle
+ +

- Prints the names of all atomic services represented by -myservicebundle, as well as everything they depend on. + Be aware that service directories will be relocated, and copied at boot time, +so if your run or finish scripts refer to files in the service directory +(probably in the data or env subdirectories!), they should +use relative paths, not absolute ones.

-
 s6-rc -Ad myservicebundle

- Prints the names of all atomic services represented by -myservicebundle, as well as everything that depends on them. + Note that you cannot create a down file in a generated service +directory. Even if such a file exists in the definition directory, it will +be ignored. This is intentional: +s6-rc internally uses down files to mark longrun +services that are down.

-
 s6-rc -pun0 myservicebundle

- Prints what s6-rc would do to bring the state to just -myservicebundle and its dependencies. + The logger and producer files are support for logged services: +A service defined as a logger for producer p will have its s6 service +directory set to p/log. Logged service definitions must be consistent:

+ + +

A complete example

-

Internals

+

+ The examples/source subdirectory of the s6-rc package contains a set +of service definition directories, which is actually a working, valid set for a +Linux system running +busybox and the +skarnet.org packages. You can compile +it with s6-rc-compile /tmp/compiled examples/source, then examine the +resulting compiled database with +s6-rc-db -c /tmp/compiled subcommand. +

-- cgit v1.2.3