README.make

   1 The Make System
   2 ~~~ ~~~~ ~~~~~~
   3 To compile this program you require GNU Make. In fact you probably need
   4 GNU Make 3.76.1 or newer. The makefiles contained make use of many
   5 GNU Make specific features and will not run on other makes.
   6
   7 The make system has a number of interesting properties that are not found
   8 in other systems such as automake or the GNU makefile standards. In
   9 general some semblance of expectedness is kept so as not to be too
  10 surprising. Basically the following will work as expected:
  11
  12    ./configure
  13    make
  14  or
  15    cd build
  16    ../configure
  17    make
  18
  19 There are a number of other things that are possible that may make software
  20 development and software packaging simpler. The first of these is the
  21 environment.mak file. When configure is run it creates an environment.mak
  22 file in the build directory. This contains -all- configurable parameters
  23 for all of the make files in all of the subdirectories. Changing one
  24 of these parameters will have an immediate effect. The use of makefile.in
  25 and configure substitutions across build makefiles is not used at all.
  26
  27 Furthermore, the make system runs with a current directory equal to the
  28 source directory irregardless of the destination directory. This means
  29 #include "" and #include <> work as epected and more importantly
  30 running 'make' in the source directory will work as expected. The
  31 environment variable or make parameter 'BUILD' sets the build directory.
  32 It may be an absolute path or a path relative to the top level directory.
  33 By default build/ will be used with a fall back to ./ This means
  34 you can get all the advantages of a build directory without having to
  35 cd into it to edit your source code!
  36
  37 The make system also performs dependency generation on the fly as the
  38 compiler runs. This is extremely fast and accurate. There is however
  39 one failure condition that occures when a header file is erased. In
  40 this case you should run make clean to purge the .o and .d files to
  41 rebuild.
  42
  43 The final significant deviation from normal make practicies is
  44 in how the build directory is managed. It is not mearly a mirror of
  45 the source directory but is logically divided in the following manner
  46    bin/
  47      methods/
  48    doc/
  49      examples/
  50    include/
  51      apt-pkg/
  52      deity/
  53    obj/
  54      apt-pkg/
  55      deity/
  56      cmndline/
  57      [...]
  58 Only .o and .d files are placed in the obj/ subdirectory. The final compiled
  59 binaries are placed in bin, published headers for inter-component linking
  60 are placed in include/ and documentation is generated into doc/. This means
  61 all runnable programs are within the bin/ directory, a huge benifit for
  62 debugging inter-program relationships. The .so files are also placed in
  63 bin/ for simplicity.
  64
  65 By default make is put into silent mode. During operation there should be
  66 no shell or compiler messages only status messages from the makefiles,
  67 if any pop up that indicates there may be a problem with your environment.
  68 For debugging you can disable this by setting NOISY=1, ala
  69    make NOISY=1
  70
  71 Using the makefiles
  72 ~~~~~ ~~~ ~~~~~~~~~
  73 The makefiles for the components are really simple. The complexity is hidden
  74 within the buildlib/ directory. Each makefile defines a set of make variables
  75 for the bit it is going to make then includes a makefile fragment from
  76 the buildlib/. This fragment generates the necessary rules based on the
  77 originally defined variables. This process can be repeated as many times as
  78 necessary for as many programs or libraries as are in the directory.
  79
  80 Many of the make fragments have some useful properties involving sub
  81 directories and other interesting features. They are more completely
  82 described in the fragment code in buildlib. Some tips on writing fragments
  83 are included in buildlib/defaults.mak
  84
  85 The fragments are NEVER processed by configure, so if you make changes to
  86 them they will have an immediate effect.
  87
  88 Autoconf
  89 ~~~~~~~~
  90 Straight out of CVS you have to initialize autoconf. This requires
  91 automake (I really don't know why) and autoconf and requires doing
  92   aclocal -I buidlib
  93   autoconf
  94
  95 Autoconf is configured to do some basic system probes for optional and
  96 required functionality and generate an environment.mak and include/config.h
  97 from it's findings. It will then write a 'makefile' and run make dirs to
  98 create the output directory tree.
  99
 100 It is not my belief that autoconf should be used to generate substantial
 101 source code markup to escape OS problems. If an OS problem does crop up
 102 it can likely be corrected by installing the correct files into the
 103 build include/ dir and perhaps writing some replacement code and
 104 linking it in. To the fullest extent possible the source code should conform
 105 to standards and not cater to broken systems.
 106
 107 Autoconf will also wite a makefile into the top level of the build dir,
 108 this simply acts as a wrapper to the main top level make in the source tree.
 109 There is one big warning, you can't use both this make file and the
 110 ones in the top level tree. Make is not able to resolve rules that
 111 go to the same file through different paths and this will confuse the
 112 depends mechanism. I recommend always using the makefiles in the
 113 source directory and exporting BUILD