README for xtruss
-----------------

This is the README for xtruss, an X11 protocol tracer.

xtruss is built using CMake <https://cmake.org/>. To compile in the
simplest way, run these commands in the source directory:

  cmake .
  cmake --build .

The 'man' page is built using Halibut, from source in the `doc'
subdirectory. If you aren't using one of our source snapshots, you'll
need to do this yourself. Halibut can be found at
<https://www.chiark.greenend.org.uk/~sgtatham/halibut/>.

The xtruss home web site is

    https://www.chiark.greenend.org.uk/~sgtatham/xtruss/

See the file LICENCE for the licence conditions.

Source code organisation
------------------------

Most source files in this project are lifted almost without change
from the PuTTY source tree, because that already contained nearly
all the code necessary to handle proxying of an X11 server, checking
the authorisation in the incoming connections, and substituting the
right authorisation for the outgoing connection to the master
server; it only took about fifty lines of new code to make all of
that talk to a local listening socket in place of incoming X
forwarding channels of an SSH connection, and I had a ready-made X
proxy to which all I had to do was add (a lot of) logging code.

The files taken from PuTTY are edited as little as possible, to reduce
merge conflicts when bringing in further updates from later versions
of PuTTY: files are completely unmodified whenever possible, and
failing that, modified in a very minimal way, ideally by just
inserting '#if 0' to remove parts of a file which xtruss doesn't use
and which would otherwise be difficult to get to compile.

So you'll often find comments in the PuTTY-derived parts of the code
that refer to functions, variables and entire files that are not
actually here. This is a deliberate tradeoff to keep maintenance easy.
If you're interested in seeing what all those things really are, you
can find them in the PuTTY code base (perhaps by rewinding to the most
recent PuTTY commit id cited in the xtruss git history).

The xtruss-specific code lives in source files with 'xtruss' in the
name: xtruss*.c and xtruss*.h in the top-level directory, and
unix/uxxtruss.c for the Unix-specific part.
