Accordingly, the PuTTY configuration box, and the PuTTYgen control window, are deliberately kept just small enough to fit comfortably on a 640×480 display. If you're adding controls to either of these boxes and you find yourself wanting to increase the size of the whole box, don't. Split it into more panels instead.
D.11 Automatically generated Makefile s
PuTTY is intended to compile on multiple platforms, and with multiple compilers. It would be horrifying to try to maintain a single Makefile which handled all possible situations, and just as painful to try to directly maintain a set of matching Makefile s for each different compilation environment.
Therefore, we have moved the problem up by one level. In the PuTTY source archive is a file called Recipe, which lists which source files combine to produce which binaries; and there is also a script called mkfiles.pl, which reads Recipe and writes out the real Makefile s. (The script also reads all the source files and analyses their dependencies on header files, so we get an extra benefit from doing it this way, which is that we can supply correct dependency information even in environments where it's difficult to set up an automated make depend phase.)
You should never edit any of the PuTTY Makefile s directly. They are not stored in our source repository at all. They are automatically generated by mkfiles.pl from the file Recipe.
If you need to add a new object file to a particular binary, the right thing to do is to edit Recipe and re-run mkfiles.pl. This will cause the new object file to be added in every tool that requires it, on every platform where it matters, in every Makefile to which it is relevant, and to get all the dependency data right.
If you send us a patch that modifies one of the Makefile s, you just waste our time, because we will have to convert it into a change to Recipe. If you send us a patch that modifies all of the Makefile s, you will have wasted a lot of your time as well!
(There is a comment at the top of every Makefile in the PuTTY source archive saying this, but many people don't seem to read it, so it's worth repeating here.)
D.12 Coroutines in ssh.c
Large parts of the code in ssh.c are structured using a set of macros that implement (something close to) Donald Knuth's ‘coroutines’ concept in C.
Essentially, the purpose of these macros are to arrange that a function can call crReturn() to return to its caller, and the next time it is called control will resume from just after that crReturn statement.
This means that any local (automatic) variables declared in such a function will be corrupted every time you call crReturn. If you need a variable to persist for longer than that, you must make it a field in one of the persistent state structures: either the local state structures s or st in each function, or the backend-wide structure ssh.
See
http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html
for a more in-depth discussion of what these macros are
for and how they work.
D.13 Single compilation of each source file
The PuTTY build system for any given platform works on the following very simple model:
•Each source file is compiled precisely once, to produce a single object file.
•Each binary is created by linking together some combination of those object files.
Therefore, if you need to introduce functionality to a particular module which is only available in some of the tool binaries (for example, a cryptographic proxy authentication mechanism which needs to be left out of PuTTYtel to maintain its usability in crypto-hostile jurisdictions), the wrong way to do it is by adding #ifdef s in (say) proxy.c. This would require separate compilation of proxy.c for PuTTY and PuTTYtel, which means that the entire Makefile-generation architecture (see
section D.11
) would have to
be significantly redesigned. Unless you are prepared to do that redesign yourself, and guarantee that it will still port to any future platforms we might decide to run on, you should not attempt this!