commit: f0b1418ff11d6c3189fc39e66795c987dbae8106
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Dec 22 19:09:16 2025 +0000
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Mon Dec 22 19:09:16 2025 +0000
URL: https://gitweb.gentoo.org/proj/steve.git/commit/?id=f0b1418f
README: add compatibility notes
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
README.rst | 27 +++++++++++++++++++++++++++
1 file changed, 27 insertions(+)
diff --git a/README.rst b/README.rst
index efdbf9c..889ea28 100644
--- a/README.rst
+++ b/README.rst
@@ -182,3 +182,30 @@ 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> ...
+
+
+Compatibility notes
+-------------------
+Steve implements the `POSIX jobserver protocol`_ based on named pipes.
+Furthermore, due to use of CUSE it is limited to Linux. Support for
+other platforms is not planned at the moment.
+
+Due to technical limitations of the Linux kernel, steve cannot use
+an actual named pipe; it uses a character device instead. This may
+cause issues with strict jobserver clients that verify that
+``--jobserver-auth`` specifies an actual named pipe. However, upstreams
+can generally be convinced to allow character devices as well.
+
+Per-process accounting implies that steve requires that the same process
+acquired and returns job tokens. If a process "passes" a job token to
+a different process and exits, steve reclaims the token immediately.
+Attempting to return a token not acquired by the process returning it
+results in a ``ENOSPC`` error being returned to the client.
+
+To work around bugs in existing software, steve permits a single job
+token to be "returned" by a new client prior to acquiring any clients.
+However, this behavior is not guaranteed to be preserved in the future,
+and new clients must not rely on it.
+
+.. _POSIX jobserver protocol:
+ https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html
