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