1 files changed, 79 insertions, 0 deletions
diff --git a/doc/why.doc b/doc/why.doc
new file mode 100644
index 0000000000..a1ac84bd27
--- /dev/null
+++ b/doc/why.doc
@@ -0,0 +1,79 @@
+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.
+
+