commit: 2377f46714e2beb3104bde21f17ca00d018ebd9f
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Tue Nov 25 19:06:54 2025 +0000
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Tue Nov 25 19:06:54 2025 +0000
URL: https://gitweb.gentoo.org/proj/steve.git/commit/?id=2377f467
Add a new README
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
README.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..ab6f97a
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,69 @@
+========================================================================
+ steve, the jobserver
+========================================================================
+
+steve is a GNU make-compatible system-wide jobserver implemented using
+FUSE. It enables running multiple build jobs simultaneously while
+sharing a single job pool, and therefore avoiding superlinear job count
+multiplication. Note that while GNU make uses a named pipe, steve uses
+a character device to track acquisition of job tokens and reclaim them
+if processes are killed without returning them.
+
+
+Usage
+-----
+steve needs to be started as root. When started, it claims
+``/dev/steve`` and starts serving the job tokens::
+
+ $ steve
+ steve running on /dev/steve for 12 jobs
+
+By default, steve uses the logical CPU count. The ``-j`` option can
+be used to override the job count::
+
+ $ steve -j6
+ steve running on /dev/steve for 6 jobs
+
+By default, the new device is accessible only to root. It is
+recommended to use udev rules to change the ownership and permission
+bits. An example rule is supplied in ``data/steve.udev`` that gives
+the ``portage`` group permission to access job tokens::
+
+ $ cp data/steve.udev /etc/udev/rules.d/99-steve.rules
+
+When used with Portage, sandbox rules need to be installed as well::
+
+ $ cp data/sandbox.conf /etc/sandbox.d/90steve
+
+Additionally, support files for OpenRC and systemd are provided
+in the ``data`` directory. All these bits are installed by the Gentoo
+package.
+
+To inspect the current status, ``SIGUSR1`` can be sent to steve::
+
+ $ killall -USR1 steve
+
+This will cause the process to print the current token count, as well
+as the list of processes holding them.
+
+
+Use in containers
+-----------------
+steve can be used across container boundaries, provided that
+the container system permits sharing character devices.
+For systemd-nspawn, the device can be bound to the container using
+the following configuration::
+
+ [Files]
+ Bind=/dev/steve
+ BindReadOnly=/etc/sandbox.d/90steve
+
+Additionally, when running the container as a service, it is necessary
+to permit the service to access it, e.g. via::
+
+ $ systemctl edit systemd-nspawn@${container_name}.service
+
+Then adding::
+
+ [Service]
+ DeviceAllow=/dev/steve rw
