doc/_build.txt

   1 Basics
   2 ======
   3
   4 * There is only one 'main' Makefile, in which everything is implemented.
   5   This Makefile resides in build/Makefile, and all other Makefiles in the
   6   tree should include it using '../..' etc. as relative path. This is done
   7   to allow invocation of make on any arbitrary level, not only on top-level
   8   (which could fail in some cases, as cross-tree dependencies on generated
   9   files don't work - see below) and the top-level Makefile must be included
  10   from all Makefiles
  11 * When invoking make, the default mode of operation is 'quiet', it means
  12   that make gives only basic and short information on what it is currently
  13   doing, but doesnt print messages about Entering/Leaving directory [1],
  14   doesn't output the whole actual commandline with all parameters as it is
  15   being invoked, etc. The verbose mode of build process can be turned on
  16   by specifying parameter V=1 to make.
  17 Example:
  18         $ make generate V=1
  19 * Makefile supports build to directory structure different from source
  20   directory structure. This can be achieves by specifying parameter OUTDIR
  21   on commandline, pointing to (existing, but preferably empty) directory,
  22   to which output of build process should be performed [2].
  23 Example:
  24         $ make OUTDIR=~/buildtree
  25   Also build to subdirectory of the current directory is supported.
  26 * Makefile prints paths relative to the project root directory when informing
  27   about currently processed file. To make it print only the filename, without
  28   the path, specify non-empty S parameter.
  29 Example:
  30         $ make S=1
  31
  32 [1] If one whises to see these and just these messages, but the rest of the
  33     build process should stay in quiet mode, -w parameter to make (which is
  34     internal make parameter, not implemented by our makefiles) should be
  35     used.
  36 [2] As the features of Makefiles are currently rapidly changing on demand
  37     of quite frequent requests for adding/modyfing features, it is possible
  38     that this (not too often used) feature breaks in some stage, without me
  39     noticing immediately. In such case, please let me know.
  40
  41 Supported targets
  42 =================
  43
  44 * <none> (aliased by 'all' target) - if make is invoked without any
  45   specified target, the following phases/targets are invoked (in this
  46   particular order) (for the description of each phase/target, see below)
  47   - predepend-recursive
  48   - generate-recursive
  49   - depend-recursive
  50   - compile-recursive
  51   - link-recursive
  52 * predepend-recursive - this is to generate first Makefile.dep, which is
  53   needed even before generated files are created. This generates dependencies
  54   of lvd and lsd files
  55 * generate-recursive (aliased by 'generate' and 'gen' targets) - this target
  56   creates generated (not compiled) files from sources specified in SFILES
  57   variable (see below). It generates
  58         .tab.cc from .y
  59         .yy.cc from .l
  60         .g.cc from .lsd
  61         .g.hh from .lsd
  62         .v.cc from .lvd
  63         .v.lsd from .lvd
  64 * depend-recursive - this target is run after the generate phase, to be able
  65   construct dependences of sources on generated sources, which must exist in
  66   the time of dependencies generation. It uses both GNU makedepend and our
  67   makedepend.xslt
  68 * compile-recursive (aliased by 'compile') - .o objects are generated from
  69   sources
  70 * link-recursive - linkage of tests (see below) and objects (see below) and
  71   default objects (see below) is performed to create executable binary.
  72 * clean - files from current directories (and recursively from directories
  73   in DIRS variable (see below)) are deleted. The deletion is performed on
  74   files which were generated and compiled by generate and compile phases (see
  75   above). This is computued from SFILES and SFILES_TEST variables from
  76   Makefile in current directory. Files specified in CLEANFILES are removed as
  77   well. All the other files are left untouched.
  78 * mrproper - same as clean, but more aggressive - in addition to what clean
  79   does, mrproper erases all "*.o *.tab.cc *.yy.cc *.v.cc *.v.lsd *.g.hh *.g.cc
  80   *.mdg.cc *.mdg.hh core* Makefile.dep" in current directory.
  81 * test - deprecated
  82 * newtest - compiles and links files specified in SFILES_TEST variable (see
  83   below) to make executable binaries, and then runs them. This is used to
  84   test funcionality of the thing you have implemented. During this phase,
  85   also all files on which this test creates (particularly files implementing
  86   the feature it is testing :) ) are automatically generated/compiled (based
  87   on generated dependencies).
  88 * doc - this is quite special target, as it is intended to be called just from
  89   top-level directory, and is used to generate documentation in doc/doxy/html
  90   directory from the doc/doxy/Doxyfile configuration file. In directories
  91   other than top-level directory this shouldn't be invoked, as it would
  92   probably fail, not finding directories it is expecting.
  93 * doc-clean - wipes out the whole doc/doxy/html directory
  94
  95 Variables in Makefiles
  96 ======================
  97
  98 Following is the list of variables on can use in per-directory Makefile and
  99 explanation of their meaning.
 100
 101 * DIRS - list of directories for recursive descent of make process
 102 * SFILES - should contain all filenames, which serve as 'sources', either
 103   for compilation or generation. The proper action (compile/generate) is
 104   derived automagically from the file extension.
 105 * SFILES_TEST - list of files that should be compiled only if 'make newtest'
 106   is issued. Sources specified in this variable are linked into executable
 107   binary (for linkage process, see below).
 108 * CLEANFILES - list of additional files that should be removed when performing
 109   'make clean' or 'make mrproper'. Typically used for files that are output
 110   by tests, as they have arbitrary names and thus are not covered by any of
 111   the usual rules.
 112 * TESTS - specifies which of the binaries, coming from compilation of files
 113   in SFILES_TEST, should be run and their return value checked. If you wonder
 114   in what situation file could be in SFILES_TEST and not in TESTS, then the
 115   answer is that it could be if you want to test the linkage of things
 116   together, but you are not interested in running the resulting binary itself.
 117 * MD_CC_FILES - list of files (*.mdg.cc) which are generated in quite
 118   different way from all other generated files (lsd/lvd). These files are
 119   generated by running xsltproc on machine_description.md (in proper
 120   directory) and *.mdg.cc.xslt stylesheet (in proper directory). The
 121   main biggest difference from lsd/lvd is, that the lsd/lvd file is not
 122   in current directory, but files are generated into current directory. This
 123   is used just by jaz, as far as I know
 124 * MD_HH_FILES - same as previous variable, just for .mdg.hh files
 125
 126 Variables used for linking
 127 --------------------------
 128 * EFILES - the list of executable files that should be created as the result
 129   of linking compiled object files. Which object files is specified by adding
 130   '.objects' suffix to the name specified in this variable (see example
 131   below). The path must be absolute from the top-level directory of the
 132   project.
 133   Outside of the objects specified in <executable>.objects variable, there
 134   are some default objects, linked to every executable by default. The list
 135   of these objects can be obtained by looking at variable DEFAULT_OBJECTS in
 136   build/Makefile
 137
 138 Example Makefile
 139 ================
 140
 141 This makefile
 142
 143 - descends recursively into subdirectories named 'subdir1' and 'subdir2'
 144 - generates .hh headers from source3.lsd and source4.lvd
 145 - generates .cc sources from source2.l source3.lsd source4.lvd
 146 - compiles source1.cc all .cc files coming from 'generate' phase into objects
 147   of the corresponding names
 148 - links lestes/lang/my/current/directory/source1.o and
 149   lestes/lang/blah/foo/bar/some/object.o and objects specified in
 150   DEFAULT_OBJECTS in main Makefile, into executable 'source1'
 151
 152 When issued as 'make newtest', after resolving dependencies, it does the
 153 following:
 154 - compiles source1.test.cc into source1.test.o, when issued as 'make newtest'
 155 - links source1.test.o with source1.o and objects specified in DEFAULT_OBJECTS
 156   in main Makefile
 157 - runs ./source1.test
 158
 159 DIRS = subdir1 subdir2
 160 SFILES = source1.cc     \
 161          source2.l      \
 162          source3.lsd    \
 163          source4.lvd
 164
 165 SFILES_TEST = source1.test.cc
 166
 167 TESTS = source1.test
 168
 169 EFILES = source1
 170
 171 source1.objects = lestes/lang/blah/foo/bar/some/object.o        \
 172                   lestes/lang/my/current/directory/source1.o    \
 173
 174 source1.test.objects = lestes/lang/my/current/directory/source1.o
 175
 176 BUILDMAKEFILE = ../../../../../build/Makefile
 177 include $(BUILDMAKEFILE)
 178
 179
 180 -- jikos, 20.1.2005
 181