From ce14260d436af0338c91a8dd87430ff190d25212 Mon Sep 17 00:00:00 2001
From: maxice8 <thinkabit.ukim@gmail.com>
Date: Sat, 2 Mar 2019 15:01:55 -0300
Subject: [PATCH] Manual.md: document guidelines for writing runit services.

---
 Manual.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/Manual.md b/Manual.md
index 36d8a8f057f..a79d478dc30 100644
--- a/Manual.md
+++ b/Manual.md
@@ -31,6 +31,7 @@ packages for XBPS, the `Void Linux` native packaging system.
 	* [INSTALL and REMOVE files](#install_remove_files)
 	* [INSTALL.msg and REMOVE.msg files](#install_remove_files_msg)
 	* [Creating system accounts/groups at runtime](#runtime_account_creation)
+	* [Writing runit services](#writing_runit_services)
 	* [32bit packages](#32bit_pkgs)
 	* [Subpackages](#pkgs_sub)
 	* [Development packages](#pkgs_development)
@@ -1190,6 +1191,45 @@ accounts.
 > NOTE: The underscore policy does not apply to old packages, due to the inevitable breakage of
 > changing the username only new packages should follow it.
 
+<a id="writing_runit_services"></a>
+### Writing runit services
+
+Void Linux uses [runit](http://smarden.org/runit/) for booting and supervision of services.
+
+Most information about how to write them can be found in their
+[FAQ](http://smarden.org/runit/faq.html#create). The following are guidelines specific to
+Void Linux on how to write services.
+
+If the service daemon supports CLI flags, consider adding support for changing it via the
+`OPTS` variable by reading a file called `conf` in the same directory as the daemon.
+
+```sh
+#!/bin/sh
+[ -r conf ] && . ./conf
+exec daemon ${OPTS:- --flag-enabled-by-default}
+```
+
+If the service requires the creation of a directory under `/run` or its link `/var/run`
+for storing runtime information (like Pidfiles) write it into the service file. It
+is advised to use `install` if you need to create it with specific permissions instead
+of `mkdir -p`.
+
+```sh
+#!/bin/sh
+install -d -m0700 /run/foo
+exec foo 
+```
+
+```sh
+#!/bin/sh
+install -d -m0700 -o bar -g bar /run/bar
+exec bar
+```
+
+If the service requires directories in parts of the system that are not generally in
+temporary filesystems. Then use the `make_dirs` variable in the template to create
+those directories when the package is installed.
+
 <a id="32bit_pkgs"></a>
 ### 32bit packages