========================================================================
                          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 use steve from a build system, one needs to set ``MAKEFLAGS``
appropriately.  To use it for all builds in Portage, these flags can
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.::

    MAKEOPTS="-j12 -l13"
    NINJAOPTS="-l13"

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::

    steve: currently 0 tokens available out of 12
    PID 71522 holds 6 tokens
    PID 71541 holds 6 tokens


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


Docker invocation
-----------------
To run a container and make the device available inside the container,
add the device mapping when invoking Docker. For example::

    $ docker run ... --device /dev/steve:/dev/steve:rw <image> ...
