description of distcc protocol version 3
copyright (C) 2007 Google, Inc

disclaimer
----------

This document is provided as explanation for people developing or
debugging distcc.  Discrepancies between this document and the distcc
code are an error in the document.

protocol
--------

Protocol 3 is a significant extension to protocol 2. It is used to send 
not the preprocessed file, but enough information to do the preprocessing
on the server.

The low level protocol (connecting, responding, encoding of short strings,
encoding of numbers, etc.) is the same as with protocols 1/2. Files are sent
compressed, just as with protocol 2. 

The protocol number (DIST) sent by the client is set to 3.  The server
must respond (DONE) in version 3.

request
-------

Protocol version 3 introduces a alternation point, between LINK and FILE.
Thus, in this version the tags are not purely decorative, as in the previous
protocols.

The following packets comprise the request:

DIST <version>
    
    Version is 3.

CDIR <len> <bytes>
    
    The working directory on the client side. Sent just like any ARGV in
    protocol versions 1/2.

ARGC <nargs>
    Just like in protocol versions 1/2.
    
ARGV <len> <bytes>
    Just like in protocol versions 1/2.

NFIL <nfiles>
    How many files or links will be sent. Similar to ARGC.

NAME <len> <bytes>
    The (absolute, crossing-no-symlinks) name of the next file or link to be
    sent.  Similar to any ARGV.

FILE <len> <bytes>
    The contents of the file. Similar to DOTI in protocol version 2.

LINK <len> <bytes>
    The contents of the link (i.e., the filename pointed to by the link).
    Similar to any ARGV. 

response
--------

Exactly as for protocol version 2, but with the following addition at the
end.

DOTD <len> <bytes>
    The contents of the result .d file. Similar to DOTO.

Notes
-----

This protocol is most useful in conjuction with an "include server" that
discovers, for each compilation unit, the list of needed files without
actually preprocessing. The protocol for talking to the include server
is simple: distcc sends a CDIR packet, and an ARGC/ARGV sequence with the 
command line, and receives an ARGC/ARGV sequence with the needed files. 

Ideally, compression of files should be independent of whether preprocessing
happens on the server or on the client. That's not currently true though.