make: POSIX Jobserver

1 
1 13.1.1 POSIX Jobserver Interaction
1 ----------------------------------
1 
1 On POSIX systems the jobserver is implemented as a simple UNIX pipe.
1 The pipe will be pre-loaded with one single-character token for each
1 available job.  To obtain an extra slot you must read a single character
1 from the jobserver pipe; to release a slot you must write a single
1 character back into the jobserver pipe.
1 
1    To access the pipe you must parse the 'MAKEFLAGS' variable and look
1 for the argument string '--jobserver-auth=R,W' where 'R' and 'W' are
1 non-negative integers representing file descriptors: 'R' is the read
1 file descriptor and 'W' is the write file descriptor.
1 
1    It's important that when you release the job slot, you write back the
1 same character you read from the pipe for that slot.  Don't assume that
1 all tokens are the same character; different characters may have
1 different meanings to GNU 'make'.  The order is not important, since
1 'make' has no idea in what order jobs will complete anyway.
1 
1    There are various error conditions you must consider to ensure your
1 implementation is robust:
1 
1    * Usually you will have a command-line argument controlling the
1      parallel operation of your tool.  Consider whether your tool should
1      detect situations where both the jobserver and the command-line
1      argument are specified, and how it should react.
1 
1    * If your tool determines that the '--jobserver-auth' option is
1      available in 'MAKEFLAGS' but that the file descriptors specified
1      are closed, this means that the calling 'make' process did not
1      think that your tool was a recursive 'make' invocation (e.g., the
1      command line was not prefixed with a '+' character).  You should
1      notify your users of this situation.
1 
1    * Your tool should also examine the first word of the 'MAKEFLAGS'
1      variable and look for the character 'n'.  If this character is
1      present then 'make' was invoked with the '-n' option and your tool
1      should stop without performing any operations.
1 
1    * Your tool should be sure to write back the tokens it read, even
1      under error conditions.  This includes not only errors in your tool
1      but also outside influences such as interrupts ('SIGINT'), etc.
1      You may want to install signal handlers to manage this write-back.
1