README.mk-devel

   1 ==============================
   2 Introduction
   3 ==============================
   4
   5 The following document briefly describes the steps and methodologies used for
   6 the new and improved Makefile system.
   7
   8 ==============================
   9 The Problem
  10 ==============================
  11
  12 The problem with the old Makefile system is that it was very difficult to
  13 maintain and it lacked any sense of formal structure, thus developing for LTP
  14 and including new targets was more difficult than it should have been
  15 (maintenance). Furthermore, proper option-based cross-compilation was
  16 impossible due to the fact that the Makefiles didn't support a prefixing
  17 system, and the appropriate implicit / static rules hadn't been configured to
  18 compile into multiple object directories for out-of-tree build support (ease of
  19 use / functionality). Finally, there wasn't a means to setup dependencies
  20 between components, such that if a component required libltp.a in order to
  21 compile, it would go off and compile libltp.a first (ease of use).
  22
  23 These items needed to be fixed to reduce maintenance nightmares for the
  24 development community contributing to LTP, and the project maintainers.
  25
  26 ==============================
  27 Design
  28 ==============================
  29
  30 The system was designed such that including a single GNU Makefile compatible
  31 set in each new directory component is all that's essentially required to
  32 build the system.
  33
  34 Say you had a directory like the following (with .c files in them which
  35 directly tie into applications, e.g. baz.c -> baz):
  36
  37         .../foo/
  38              |--> Makefile
  39              |
  40               --> bar/
  41                    |
  42                     --> Makefile
  43                    |
  44                     --> baz.c
  45
  46 Here's an example of how one would accomplish that:
  47
  48 .../foo/Makefile:
  49 #
  50 # Copyright disclaimer goes here -- please use GPLv2.
  51 #
  52
  53 top_srcdir              ?= ..
  54
  55 include $(top_srcdir)/include/mk/env_pre.mk
  56 include $(top_srcdir)/include/mk/generic_trunk_target.mk
  57
  58 .../foo/bar/Makefile:
  59 #
  60 # Copyright disclaimer goes here -- please use GPLv2.
  61 #
  62
  63 top_srcdir              ?= ..
  64
  65 include $(top_srcdir)/include/mk/env_pre.mk
  66 include $(top_srcdir)/include/mk/generic_leaf_target.mk
  67
  68 ==============================
  69 Make Rules and Make Variables
  70 ==============================
  71
  72 When using make rules, avoid writing ad hoc rules like:
  73
  74 [prog]: [dependencies]
  75         cc -I../../include $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(LDLIBS) \
  76             -o [prog] [dependencies]
  77
  78 etc. This makes cross-compilation and determinism difficult, if not impossible.
  79 Besides, implicit rules are your friends and as long as you use `MAKEOPTS=;' in
  80 the top-level caller (or do $(subst r,$(MAKEOPTS)) to remove -r), the compile
  81 will complete successfully, assuming all other prerequisites have been
  82 fulfilled (libraries, headers, etc).
  83
  84 $(AR)                   : The library archiver.
  85
  86 $(CC)                   : The system C compiler.
  87
  88 $(CXX)                  : The system C++ compiler.
  89
  90 $(CPP)                  : The system C preprocessor.
  91
  92 $(CFLAGS)               : C compiler flags.
  93
  94 $(CPPFLAGS)             : Preprocessor flags, e.g. -I arguments.
  95
  96 $(CXXFLAGS)             : C++ compiler flags, e.g. -I arguments.
  97
  98 $(DEBUG_CFLAGS)         : Debug flags to pass to $(CC), -g, etc.
  99
 100 $(DEBUG_CXXFLAGS)       : Debug flags to pass to $(CXX).
 101
 102 $(LD)                   : The system linker (typically $(CC), but not
 103                           necessarily).
 104
 105 $(LDFLAGS)              : What to pass in to the linker, including -L arguments
 106                           and other ld arguments, apart from -l library
 107                           includes (see $(LDLIBS)).
 108
 109                           This should be done in the $(CC) args passing style
 110                           when LD := $(CC), e.g. `-Wl,-foo', as opposed to
 111                           `-foo'.
 112
 113 $(LDLIBS)               : Libraries to pass to the linker (e.g. -lltp, etc).
 114
 115 $(OPT_CFLAGS)           : Optimization flags to pass into the C compiler, -O2,
 116                           etc. If you specify -O2 or higher, you should also
 117                           specify -fno-strict-aliasing, because of gcc
 118                           fstrict-aliasing optimization bugs in the tree
 119                           optimizer. Search for `fstrict-aliasing optimization
 120                           bug' with your favorite search engine.
 121
 122                           Examples of more recent bugs:
 123                           1. tree-optimization/17510
 124                           2. tree-optimization/39100
 125
 126                           Various bugs have occurred in the past due to buggy
 127                           logic in the tree-optimization portion of the gcc
 128                           compiler, from 3.3.x to 4.4.
 129
 130 $(OPT_CXXFLAGS)         : Optimization flags to pass to the C++ compiler.
 131
 132 $(RANLIB)               : What to run after archiving a library.
 133
 134 $(WCFLAGS)              : Warning flags to pass to $(CC), e.g. -Werror,
 135                           -Wall, etc.
 136
 137 $(WCXXFLAGS)            : Same as $(WCFLAGS), but for $(CXX).
 138
 139 ==============================
 140 Make System Variables
 141 ==============================
 142
 143 A series of variables are used within the make system that direct what actions
 144 need to be taken. Rather than me listing the variables here, please with their
 145 intended uses, please refer to the comments contained in
 146 `.../include/mk/env_pre.mk'.
 147
 148 ==============================
 149 Guidelines and Recommendations
 150 ==============================
 151
 152 Of course, the GNU Make manual is key to understanding the Make system, but
 153 here are the following sections and chapters I suggest reviewing:
 154
 155 - implicit rules: http://www.gnu.org/software/make/manual/make.html#Implicit-Rules
 156 - variables and expansion: http://www.gnu.org/software/make/manual/make.html#Using-Variables
 157 - origin use: http://www.gnu.org/software/make/manual/make.html#Origin-Function
 158 - vpath use: http://www.gnu.org/software/make/manual/make.html#Directory-Search
 159
 160 ==============================
 161 Before Committing
 162 ==============================
 163
 164 One should rebuild from scratch before committing. Please see INSTALL for more
 165 details.
 166
 167 ==============================
 168 Other Errata
 169 ==============================
 170
 171 Please see TODO for any issues related to the Makefile infrastructure, and
 172 build structure / source tree in general.