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