commit: 7baf3dfc815ab6b56e96bb777c35e8964ac3552f
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Dec 22 18:49:10 2025 +0000
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Mon Dec 22 18:49:10 2025 +0000
URL: https://gitweb.gentoo.org/proj/steve.git/commit/?id=7baf3dfc
README: split install instructions, update usage
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
README.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 74 insertions(+), 21 deletions(-)
diff --git a/README.rst b/README.rst
index 298f994..18dd9c6 100644
--- a/README.rst
+++ b/README.rst
@@ -10,35 +10,72 @@ a character device to track acquisition of job tokens and
reclaim them
if processes are killed without returning them.
+Installation
+------------
+
+Steve uses the Meson_ build system. Typically, it can be built
+and installed using the following commands::
+
+ $ meson setup . build
+ $ meson install -C build
+
+For more details, please see the Meson documentation.
+
+Steve needs access to ``/dev/cuse`` which is normally restricted
+to the superuser. However, as a best security practice it is
+recommended to run steve using a dedicated user account. This can be
+achieved either by:
+
+1. using ``--user {username}`` option when starting steve, to make it
+ drop privileges after opening ``/dev/cuse``, or
+
+2. giving the user running steve permissions to open ``/dev/cuse``.
+
+The default device file created by CUSE (``/dev/steve``) is accessible
+only to root. The recommended way of changing permissions to these
+files is through udev rules. That said, world access may be
+undesirable, as malicious client could easily consume all the tokens
+and block other processes from obtaining any.
+
+The distribution provides a number of example files that can be modified
+and installed:
+
+``data/steve.service``
+ A systemd service file. It assumes that steve is installed as
+ ``/usr/bin/steve`` and runs as ``steve:steve`` user which can access
+ ``/dev/cuse``.
+
+``data/steve.initd`` and ``data/steve.initd``
+ A init.d script and conf.d file for OpenRC, with the same assumptions.
+
+``data/steve.udev``
+ Udev rules file (needs to be renamed to ``*.rules``) that gives
+ the ``jobserver`` group access to ``/dev/steve``.
+
+``data/sandbox.conf``
+ Gentoo sandbox configuration file that gives sandboxed processes
+ access to ``/dev/steve``.
+
+.. _Meson: https://mesonbuild.com/
+
+
Usage
-----
-steve needs to be started as root. When started, it claims
-``/dev/steve`` and starts serving the job tokens::
+When started without any arguments, steve claims ``/dev/steve``
+and starts serving job tokens::
$ steve
steve running on /dev/steve for 12 jobs
+ at least 1 jobs will be always available
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
+ at least 1 jobs will be always available
-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 ``jobserver`` group permission to access job tokens::
-
- $ cp data/steve.udev /etc/udev/rules.d/99-steve.rules
-
-When used with Portage, the ``portage`` user needs to be added
-to the ``jobserver`` group 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.
+For more options, see ``steve --help``.
To use steve from a build system, one needs to set ``MAKEFLAGS``
appropriately. To use it for all builds in Portage, these flags can
@@ -47,8 +84,8 @@ be set in ``make.conf``::
MAKEFLAGS="--jobserver-auth=fifo:/dev/steve"
Note that to use steve with Ninja, ``-j`` must not be passed. Given
-that ``MAKEOPTS`` is used to default other build systems, the best
-approach is to override ``NINJAOPTS``, e.g.::
+that ``MAKEOPTS`` is used to provide defaults for other build systems,
+the best approach is to override ``NINJAOPTS``, e.g.::
MAKEOPTS="-j12 -l13"
NINJAOPTS="-l13"
@@ -61,8 +98,24 @@ This will cause the process to print the current token
count, as well
as the list of processes holding them::
steve: currently 0 tokens available out of 12
- PID 71522 holds 6 tokens
- PID 71541 holds 6 tokens
+ PID 221613 (make DESTDIR= RPATH_ENVVAR=LD_LIBRARY_PATH
TARGET_SUBDIR=x86_64-pc-linux-gnu bindir=/usr/x86_64-pc-linux-gnu/gcc-bin/15
datadir) holds 3 tokens:
+ job 0x00 running for 0.0084036s
+ job 0x01 running for 0.0536742s
+ job 0x02 running for 0.163137s
+ PID 202894 (ninja -v -l16 distribution) holds 7 tokens:
+ job 0x04 running for 3.0512s
+ job 0x00 running for 3.05184s
+ job 0x09 running for 8.47799s
+ job 0x08 running for 18.8555s
+ job 0x01 running for 20.4352s
+ job 0x03 running for 20.7428s
+ job 0x02 running for 23.3102s
+ PID 194264 (make DESTDIR= RPATH_ENVVAR=LD_LIBRARY_PATH
TARGET_SUBDIR=x86_64-pc-linux-gnu bindir=/usr/x86_64-pc-linux-gnu/gcc-bin/15
datadir) holds 0 tokens:
+ PID 194247 (make DESTDIR= RPATH_ENVVAR=LD_LIBRARY_PATH
TARGET_SUBDIR=x86_64-pc-linux-gnu bindir=/usr/x86_64-pc-linux-gnu/gcc-bin/15
datadir) holds 0 tokens:
+ PID 194237 (make LDFLAGS=-Wl,-O1 -Wl,--as-needed -Wl,--hash-style=gnu
LIBPATH=/usr/lib/gcc/x86_64-pc-linux-gnu/15 STAGE1_CFLAGS=-m64 -march) holds 0
tokens:
+ PID 188922 (/usr/bin/python3.14 /usr/lib/python-exec/python3.14/emerge -vB
--nodep llvm-core/clang sys-devel/gcc --jobs) holds 2 tokens:
+ job 0x01 running for 108.73s
+ job 0x00 running for 108.735s
Use in containers
