doc/why.doc

This file is more of a note for other people who wish to understand why
the build environment is the way it is :-).

The include files 'depend' as follows.
Each of 
crypto/*/*.c includes crypto/cryptlib.h
ssl/*.c include ssl/ssl_locl.h
apps/*.c include apps/apps.h
crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
all include e_os.h which contains OS/environment specific information.
If you need to add something todo with a particular environment,
add it to this file.  It is worth remembering that quite a few libraries,
like lhash, des, md, sha etc etc do not include crypto/cryptlib.h.  This
is because these libraries should be 'independantly compilable' and so I
try to keep them this way.
e_os.h is not so much a part of SSLeay, as the placing in one spot all the
evil OS dependant muck.

I wanted to automate as many things as possible.  This includes
error number generation.  A
make errors
will scan the source files for error codes, append them to the correct
header files, and generate the functions to print the text version
of the error numbers.  So don't even think about adding error numbers by
hand, put them in the form
XXXerr(XXXX_F_XXXX,YYYY_R_YYYY);
on line and it will be automatically picked up my a make errors.

In a similar vein, programs to be added into ssleay in the apps directory
just need to have an entry added to E_EXE in makefile.ssl and
everthing will work as expected.  Don't edit progs.h by hand.

make links re-generates the symbolic links that are used.  The reason why
I keep everything in its own directory, and don't put all the
test programs and header files in 'test' and 'include' is because I want
to keep the 'sub-libraries' independant.  I still 'pull' out
indervidual libraries for use in specific projects where the code is
required.  I have used the 'lhash' library in just about every software
project I have worked on :-).

make depend generates dependancies and
make dclean removes them.

You will notice that I use perl quite a bit when I could be using 'sed'.
The reason I decided to do this was to just stick to one 'extra' program.
For Windows NT, I have perl and no sed.

The util/mk1mf.pl program can be used to generate a single makefile.
I use this because makefiles under Microsoft are horrific.
Each C compiler seems to have different linker formats, which have
to be used because the retarted C compilers explode when you do
cl -o file *.o.

Now some would argue that I should just use the single makefile.  I don't
like it during develoment for 2 reasons.  First, the actuall make
command takes a long time.  For my current setup, if I'm in
crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
which is nice when you are modifying prototypes in bn.h which
half the SSLeay depends on.  The second is that to add a new souce file
I just plonk it in at the required spot in the local makefile.  This
then alows me to keep things local, I don't need to modify a 'global'
tables (the make for unix, the make for NT, the make for w31...).
When I am ripping apart a library structure, it is nice to only
have to worry about one directory :-).

Having said all this, for the hell of it I put together 2 files that
#include all the souce code (generated by doing a ls */*.o after a build).
crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
for my pentium100.  Much faster that the normal build :-).
Again, the problem is that when using libraries, every program linked
to libcrypto.a would suddenly get 330k of library when it may only need
1k.  This technique does look like a nice way to do shared libraries though.

Oh yes, as a final note, to 'build' a distribution, I just type
make dist.
This cleans and packages everything.  The directory needs to be called
SSLeay since the make does a 'cd ..' and renames and tars things up.