udp.but

putty

\# This file is so named for tradition's sake: it contains what we
\# always used to refer to, before they were written down, as
\# PuTTY's `unwritten design principles'. It has nothing to do with
\# the User Datagram Protocol.

\define{versionidudp} \versionid $Id: udp.but 5525 2005-03-19 02:29:57Z jacob $

\A{udp} PuTTY hacking guide

This appendix lists a selection of the design principles applying to
the PuTTY source code. If you are planning to send code
contributions, you should read this first.

\H{udp-portability} Cross-OS portability

Despite Windows being its main area of fame, PuTTY is no longer a
Windows-only application suite. It has a working Unix port; a Mac
port is in progress; more ports may or may not happen at a later
date.

Therefore, embedding Windows-specific code in core modules such as
\cw{ssh.c} is not acceptable. We went to great lengths to \e{remove}
all the Windows-specific stuff from our core modules, and to shift
it out into Windows-specific modules. Adding large amounts of
Windows-specific stuff in parts of the code that should be portable
is almost guaranteed to make us reject a contribution.

The PuTTY source base is divided into platform-specific modules and
platform-generic modules. The Unix-specific modules are all in the
\c{unix} subdirectory; the Mac-specific modules are in the \c{mac}
subdirectory; the Windows-specific modules are in the \c{windows}
subdirectory.

All the modules in the main source directory - notably \e{all} of
the code for the various back ends - are platform-generic. We want
to keep them that way.

This also means you should stick to what you are guaranteed by
ANSI/ISO C (that is, the original C89/C90 standard, not C99). Try
not to make assumptions about the precise size of basic types such
as \c{int} and \c{long int}; don't use pointer casts to do
endianness-dependent operations, and so on.

(There are one or two aspects of ANSI C portability which we
\e{don't} care about. In particular, we expect PuTTY to be compiled
on 32-bit architectures \e{or bigger}; so it's safe to assume that
\c{int} is at least 32 bits wide, not just the 16 you are guaranteed
by ANSI C.  Similarly, we assume that the execution character
encoding is a superset of the printable characters of ASCII, though
we don't assume the numeric values of control characters,
particularly \cw{'\\n'} and \cw{'\\r'}.)

\H{udp-multi-backend} Multiple backends treated equally

PuTTY is not an SSH client with some other stuff tacked on the side.
PuTTY is a generic, multiple-backend, remote VT-terminal client
which happens to support one backend which is larger, more popular
and more useful than the rest. Any extra feature which can possibly
be general across all backends should be so: localising features
unnecessarily into the SSH back end is a design error. (For example,
we had several code submissions for proxy support which worked by
hacking \cw{ssh.c}. Clearly this is completely wrong: the
\cw{network.h} abstraction is the place to put it, so that it will
apply to all back ends equally, and indeed we eventually put it
there after another contributor sent a better patch.)

The rest of PuTTY should try to avoid knowing anything about
specific back ends if at all possible. To support a feature which is
only available in one network protocol, for example, the back end
interface should be extended in a general manner such that \e{any}
back end which is able to provide that feature can do so. If it so
happens that only one back end actually does, that's just the way it
is, but it shouldn't be relied upon by any code.

\H{udp-globals} Multiple sessions per process on some platforms

Some ports of PuTTY - notably the in-progress Mac port - are
constrained by the operating system to run as a single process
potentially managing multiple sessions.

Therefore, the platform-independent parts of PuTTY never use global
variables to store per-session data. The global variables that do
exist are tolerated because they are not specific to a particular
login session: \c{flags} defines properties that are expected to
apply equally to \e{all} the sessions run by a single PuTTY process,
the random number state in \cw{sshrand.c} and the timer list in
\cw{timing.c} serve all sessions equally, and so on. But most data
is specific to a particular network session, and is therefore stored
in dynamically allocated data structures, and pointers to these
structures are passed around between functions.

Platform-specific code can reverse this decision if it likes. The
Windows code, for historical reasons, stores most of its data as
global variables. That's OK, because \e{on Windows} we know there is
only one session per PuTTY process, so it's safe to do that. But
changes to the platform-independent code should avoid introducing
global variables, unless they are genuinely cross-session.

\H{udp-pure-c} C, not C++

PuTTY is written entirely in C, not in C++.

We have made \e{some} effort to make it easy to compile our code
using a C++ compiler: notably, our \c{snew}, \c{snewn} and
\c{sresize} macros explicitly cast the return values of \cw{malloc}
and \cw{realloc} to the target type. (This has type checking
advantages even in C: it means you never accidentally allocate the
wrong size piece of memory for the pointer type you're assigning it
to. C++ friendliness is really a side benefit.)

We want PuTTY to continue being pure C, at least in the
platform-independent parts and the currently existing ports. Patches
which switch the Makefiles to compile it as C++ and start using
classes will not be accepted. Also, in particular, we disapprove of
\cw{//} comments, at least for the moment. (Perhaps once C99 becomes
genuinely widespread we might be more lenient.)

The one exception: a port to a new platform may use languages other
than C if they are necessary to code on that platform. If your
favourite PDA has a GUI with a C++ API, then there's no way you can
do a port of PuTTY without using C++, so go ahead and use it. But
keep the C++ restricted to that platform's subdirectory; if your
changes force the Unix or Windows ports to be compiled as C++, they
will be unacceptable to us.

\H{udp-security} Security-conscious coding

PuTTY is a network application and a security application. Assume
your code will end up being fed deliberately malicious data by
attackers, and try to code in a way that makes it unlikely to be a
security risk.

In particular, try not to use fixed-size buffers for variable-size
data such as strings received from the network (or even the user).
We provide functions such as \cw{dupcat} and \cw{dupprintf}, which
dynamically allocate buffers of the right size for the string they
construct. Use these wherever possible.

\H{udp-multi-compiler} Independence of specific compiler

Windows PuTTY can currently be compiled with any of four Windows
compilers: MS Visual C, Borland's freely downloadable C compiler,
the Cygwin / \cw{mingw32} GNU tools, and \cw{lcc-win32}.

This is a really useful property of PuTTY, because it means people
who want to contribute to the coding don't depend on having a
specific compiler; so they don't have to fork out money for MSVC if
they don't already have it, but on the other hand if they \e{do}
have it they also don't have to spend effort installing \cw{gcc}
alongside it. They can use whichever compiler they happen to have
available, or install whichever is cheapest and easiest if they
don't have one.

Therefore, we don't want PuTTY to start depending on which compiler
you're using. Using GNU extensions to the C language, for example,
would ruin this useful property (not that anyone's ever tried it!);
and more realistically, depending on an MS-specific library function
supplied by the MSVC C library (\cw{_snprintf}, for example) is a
mistake, because that function won't be available under the other
compilers. Any function supplied in an official Windows DLL as part
of the Windows API is fine, and anything defined in the C library
standard is also fine, because those should be available
irrespective of compilation environment. But things in between,
available as non-standard library and language extensions in only
one compiler, are disallowed.

(\cw{_snprintf} in particular should be unnecessary, since we
provide \cw{dupprintf}; see \k{udp-security}.)

Compiler independence should apply on all platforms, of course, not
just on Windows.

\H{udp-small} Small code size

PuTTY is tiny, compared to many other Windows applications. And it's
easy to install: it depends on no DLLs, no other applications, no
service packs or system upgrades. It's just one executable. You
install that executable wherever you want to, and run it.

We want to keep both these properties - the small size, and the ease
of installation - if at all possible. So code contributions that
depend critically on external DLLs, or that add a huge amount to the
code size for a feature which is only useful to a small minority of
users, are likely to be thrown out immediately.

We do vaguely intend to introduce a DLL plugin interface for PuTTY,
whereby seriously large extra features can be implemented in plugin
modules. The important thing, though, is that those DLLs will be
\e{optional}; if PuTTY can't find them on startup, it should run
perfectly happily and just won't provide those particular features.
A full installation of PuTTY might one day contain ten or twenty
little DLL plugins, which would cut down a little on the ease of
installation - but if you really needed ease of installation you
\e{could} still just install the one PuTTY binary, or just the DLLs
you really needed, and it would still work fine.