From b074dae4e6ec6ea5a9313743badb38fdefb5f9b5 Mon Sep 17 00:00:00 2001 From: Luka Vandervelden Date: Tue, 12 Nov 2019 20:03:45 +0100 Subject: [PATCH] WIP documentation. --- doc/service.1.scd | 117 ++++++++++++++++++++++++++++++++++++++++++++++ doc/service.7.scd | 52 +++++++++++++++++++++ project.zsh | 43 +++++++++++++++++ 3 files changed, 212 insertions(+) create mode 100644 doc/service.1.scd create mode 100644 doc/service.7.scd diff --git a/doc/service.1.scd b/doc/service.1.scd new file mode 100644 index 0000000..e33bc93 --- /dev/null +++ b/doc/service.1.scd @@ -0,0 +1,117 @@ +service(1) + +# NAME + +service - system services control and querying interface + +# SYNOPSIS + +*service* add [options] + +*service* start + +*service* stop + +*service* status [-v] [service [service [...]] + +*service* reload + +*service* del + +*service* show + +# DESCRIPTION + +**service** is a tool that starts, stops, lists, queries, creates or removes system services. +**service** abstracts their configuration and handles their dependencies to one another. + +Some general concepts about WeirdOS’ services management and boot procedure can be found in *service*(7). + +# USAGE + +## Identifying Services + + service show + + service status [-v|--verbose] [id [id [...]]] + +Service ids are the name of a service, that may be prefixed by the name of their environment and a slash ('/'). + +*service show* shows all of a service’s relationship to other services as well as its full configuration as handled by `service`. + +*service status* shows the status of one or multiple services, including whether they are currently running or not. +If no parameter is provided to the `status` command, it will show the status of all services. +If the `--verbose` flag is provided, informations about what tokens a service produces or consumes, as well as the ports it reserves, will be displayed as well. + +## Starting Services + + service start + +If a service that has dependencies is requested to be started, its dependencies will be started beforehand. + +If a service is depended on by a non-runnable service, the non-runnable services will have their configuration and deployable files generated once its last dependency is started. +An example for this is a static website that depends on a web server: if the web server is started, the static website’s files and possible configuration will be generated or installed where they will be served. + +## Stopping Services + + service stop + +## Adding Services + + service add [options] + +The **service add** command can be used to create a service. +Only services that have been “added” to the list of known services can be started. + +It takes as first parameter the *id* of the service to create. + +The service type defaults to the name of the service to be created. + +## Removing Services + + service del [options] + +The **service del** command removes a service from the system. +Be careful, as this command also removes its configuration and data. + +*service del* will not let you remove services that are being depended on unless you provide a `--force` flag. + +*service del* will stop services before removing them. + +# EXAMPLES + +## Starting a Service + + $ service start gitea + +## Registering a Single Service + + service add postgresql + + service start postgresql + +## Registering Multiple Services with Dependencies + + service add nginx + + service add postgresql + + service add gitea http=nginx postgresql=postgresql domain=gitea.test + +In this example, the dependencies of the “gitea” service could have been guessed automatically. +The following example does the exact same thing but lets `service` guess dependencies. + + service add nginx + + service add postgresql + + service add gitea domain=gitea.test + +# SEE ALSO + +*servîce*(7) + +# AUTHORS + +Luka Vandervelden + diff --git a/doc/service.7.scd b/doc/service.7.scd new file mode 100644 index 0000000..ec588a5 --- /dev/null +++ b/doc/service.7.scd @@ -0,0 +1,52 @@ +service(7) + +# NAME + +service - services and applications management + +# DESCRIPTION + +The *service*(1) tool is used to manage services. + +The *rc*(1) script is used to start the components of the system not handled by *init*(1). +*rc* is usually the first application to call *service*. + +# SERVICE IDS + +Service ids are the name of a service, that may be prefixed by the name of their environment and a slash ('/'). + +The default environment for services, if none is provided, is named *root*. + +# TOKENS + +Interactions between services is represented by *tokens*. +Their names and behavior are arbitrary, and they only serve in establishing conventions between services. + +# FILES + +## /etc/rc/services + +Directory in which the metadata about instances of services handled by *service*(1) are stored. + +## /etc/rc/environments + +Directory in which the metadata about environments of services handled by *service*(1) are stored. + +The *root* environment is virtual and does not have a matching entry. + +## /usr/weirdos/share/services + +Directory in which the behavior of services is stored. + +## /usr/weirdos/share/templates + +Directory in which configuration templates to be used by service’s *gen-config* are stored. + +# SEE ALSO + +*spec*(5) + +# AUTHORS + +Luka Vandervelden + diff --git a/project.zsh b/project.zsh index a4249ca..753f3fa 100644 --- a/project.zsh +++ b/project.zsh @@ -45,6 +45,14 @@ for file in utils/*; do type[$file]=script done +for file in doc/*; do + [[ "$file" =~ .*\.scd$ ]] || continue + + targets+=(${file%.scd}) + type[${file%.scd}]=scdoc + sources[${file%.scd}]=${file} +done + # FIXME: This should be upstreamed. function script.install { if [[ "false" = "${install[$target]}" ]]; then @@ -56,3 +64,38 @@ function script.install { install[status]='$(LIBEXECDIR)/service' +function scdoc.prelude { + for target in $targets; do + [[ "${type[$target]}" == "scdoc" ]] || continue + + if [[ -z "${install[$target]}" ]]; then + local section="${file%.scd}" + section="${section#*.}" + + install[$target]="\$(SHAREDIR)/man/man${section}" + fi + done +} + +function SCD { + SED "$@" | sed 's|SED|SCD|' +} + +function scdoc.build { + write "${target}: ${sources[$target]}" + write "\t@echo '$(SCD $target)'" + write "\t${Q}scdoc < ${sources[$target]} > $target || rm $target" +} + +function scdoc.install { + script.install "$@" +} + +function scdoc.uninstall { + script.uninstall "$@" +} + +function scdoc.clean { + script.clean "$@" +} +