fix pk7_doit.c for new i2d_ASN1_SET argument
[openssl.git] / doc / why.doc
1 This file is more of a note for other people who wish to understand why
2 the build environment is the way it is :-).
3
4 The include files 'depend' as follows.
5 Each of 
6 crypto/*/*.c includes crypto/cryptlib.h
7 ssl/*.c include ssl/ssl_locl.h
8 apps/*.c include apps/apps.h
9 crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h
10 all include e_os.h which contains OS/environment specific information.
11 If you need to add something todo with a particular environment,
12 add it to this file.  It is worth remembering that quite a few libraries,
13 like lhash, des, md, sha etc etc do not include crypto/cryptlib.h.  This
14 is because these libraries should be 'independantly compilable' and so I
15 try to keep them this way.
16 e_os.h is not so much a part of SSLeay, as the placing in one spot all the
17 evil OS dependant muck.
18
19 I wanted to automate as many things as possible.  This includes
20 error number generation.  A
21 make errors
22 will scan the source files for error codes, append them to the correct
23 header files, and generate the functions to print the text version
24 of the error numbers.  So don't even think about adding error numbers by
25 hand, put them in the form
26 XXXerr(XXXX_F_XXXX,YYYY_R_YYYY);
27 on line and it will be automatically picked up my a make errors.
28
29 In a similar vein, programs to be added into ssleay in the apps directory
30 just need to have an entry added to E_EXE in makefile.ssl and
31 everthing will work as expected.  Don't edit progs.h by hand.
32
33 make links re-generates the symbolic links that are used.  The reason why
34 I keep everything in its own directory, and don't put all the
35 test programs and header files in 'test' and 'include' is because I want
36 to keep the 'sub-libraries' independant.  I still 'pull' out
37 indervidual libraries for use in specific projects where the code is
38 required.  I have used the 'lhash' library in just about every software
39 project I have worked on :-).
40
41 make depend generates dependancies and
42 make dclean removes them.
43
44 You will notice that I use perl quite a bit when I could be using 'sed'.
45 The reason I decided to do this was to just stick to one 'extra' program.
46 For Windows NT, I have perl and no sed.
47
48 The util/mk1mf.pl program can be used to generate a single makefile.
49 I use this because makefiles under Microsoft are horrific.
50 Each C compiler seems to have different linker formats, which have
51 to be used because the retarted C compilers explode when you do
52 cl -o file *.o.
53
54 Now some would argue that I should just use the single makefile.  I don't
55 like it during develoment for 2 reasons.  First, the actuall make
56 command takes a long time.  For my current setup, if I'm in
57 crypto/bn and I type make, only the crypto/bn directory gets rebuilt,
58 which is nice when you are modifying prototypes in bn.h which
59 half the SSLeay depends on.  The second is that to add a new souce file
60 I just plonk it in at the required spot in the local makefile.  This
61 then alows me to keep things local, I don't need to modify a 'global'
62 tables (the make for unix, the make for NT, the make for w31...).
63 When I am ripping apart a library structure, it is nice to only
64 have to worry about one directory :-).
65
66 Having said all this, for the hell of it I put together 2 files that
67 #include all the souce code (generated by doing a ls */*.o after a build).
68 crypto.c takes only 30 seconds to build under NT and 2 minutes under linux
69 for my pentium100.  Much faster that the normal build :-).
70 Again, the problem is that when using libraries, every program linked
71 to libcrypto.a would suddenly get 330k of library when it may only need
72 1k.  This technique does look like a nice way to do shared libraries though.
73
74 Oh yes, as a final note, to 'build' a distribution, I just type
75 make dist.
76 This cleans and packages everything.  The directory needs to be called
77 SSLeay since the make does a 'cd ..' and renames and tars things up.
78
79