1 Short introduction into LTP build system 2 ======================================== 3 4 ****************************************************************************** 5 The following document briefly describes the steps and methodologies used for 6 the new and improved Makefile system. 7 8 Changelog: 9 10 * Initial version: Garrett Cooper <yanegomi (a] gmail.com> 11 * Reformated for asciidoc: Cyril Hrubis <chrubis (a] suse.cz> 12 ****************************************************************************** 13 14 The Problem 15 ----------- 16 17 The problem with the old Makefile system is that it was very difficult to 18 maintain and it lacked any sense of formal structure, thus developing for LTP 19 and including new targets was more difficult than it should have been 20 (maintenance). Furthermore, proper option-based cross-compilation was 21 impossible due to the fact that the Makefiles didn't support a prefixing 22 system, and the appropriate implicit / static rules hadn't been configured to 23 compile into multiple object directories for out-of-tree build support (ease of 24 use / functionality). Finally, there wasn't a means to setup dependencies 25 between components, such that if a component required libltp.a in order to 26 compile, it would go off and compile libltp.a first (ease of use). 27 28 These items needed to be fixed to reduce maintenance nightmares for the 29 development community contributing to LTP, and the project maintainers. 30 31 Design 32 ------ 33 34 The system was designed such that including a single GNU Makefile compatible 35 set in each new directory component is all that's essentially required to 36 build the system. 37 38 Say you had a directory like the following (with .c files in them which 39 directly tie into applications, e.g. baz.c -> baz): 40 41 ------------------------------------------------------------------------------- 42 .../foo/ 43 |--> Makefile 44 | 45 --> bar/ 46 | 47 --> Makefile 48 | 49 --> baz.c 50 ------------------------------------------------------------------------------- 51 52 Here's an example of how one would accomplish that: 53 54 ------------------------------------------------------------------------------- 55 .../foo/Makefile: 56 # 57 # Copyright disclaimer goes here -- please use GPLv2. 58 # 59 60 top_srcdir ?= .. 61 62 include $(top_srcdir)/include/mk/env_pre.mk 63 include $(top_srcdir)/include/mk/generic_trunk_target.mk 64 65 .../foo/bar/Makefile: 66 # 67 # Copyright disclaimer goes here -- please use GPLv2. 68 # 69 70 top_srcdir ?= .. 71 72 include $(top_srcdir)/include/mk/env_pre.mk 73 include $(top_srcdir)/include/mk/generic_leaf_target.mk 74 ------------------------------------------------------------------------------- 75 76 Kernel Modules 77 -------------- 78 79 Some of the tests need to build kernel modules, happily LTP has 80 infrastructure for this. 81 82 ------------------------------------------------------------------------------- 83 ifneq ($(KERNELRELEASE),) 84 85 obj-m := module01.o 86 87 else 88 89 top_srcdir ?= ../../../.. 90 include $(top_srcdir)/include/mk/testcases.mk 91 92 REQ_VERSION_MAJOR := 2 93 REQ_VERSION_PATCH := 6 94 MAKE_TARGETS := test01 test02 module01.ko 95 96 include $(top_srcdir)/include/mk/module.mk 97 include $(top_srcdir)/include/mk/generic_leaf_target.mk 98 99 endif 100 ------------------------------------------------------------------------------- 101 102 This is example Makefile that allows you build kernel modules inside of LTP. 103 The prerequisites for the build are detected by the 'configure' script. 104 105 The 'REQ_VERSION_MAJOR' and 'REQ_VERSION_PATCH' describe minimal kernel 106 version for which the build system tries to build the module. 107 108 The buildsystem is also forward compatible with changes in Linux kernel 109 internal API so that if modul fails to build the failure is ignored both on 110 build and installation. If the userspace counterpart of the test fails to load 111 the module because the file does not exists, the test is skipped. 112 113 Note the 'ifneq($(KERNELRELEASE),)', the reason it's there is that the 114 Makefile is executed twice, once by LTP build system and once by kernel 115 kbuild, see 'Documentation/kbuild/modules.txt' in the Linux kernel tree for 116 details on external module build. 117 118 Make Rules and Make Variables 119 ----------------------------- 120 121 When using make rules, avoid writing ad hoc rules like: 122 123 ------------------------------------------------------------------------------- 124 [prog]: [dependencies] 125 cc -I../../include $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(LDLIBS) \ 126 -o [prog] [dependencies] 127 ------------------------------------------------------------------------------- 128 129 etc. This makes cross-compilation and determinism difficult, if not impossible. 130 Besides, implicit rules are your friends and as long as you use `MAKEOPTS=;' in 131 the top-level caller (or do $(subst r,$(MAKEOPTS)) to remove -r), the compile 132 will complete successfully, assuming all other prerequisites have been 133 fulfilled (libraries, headers, etc). 134 135 ------------------------------------------------------------------------------- 136 $(AR) : The library archiver. 137 138 $(CC) : The system C compiler. 139 140 $(CXX) : The system C++ compiler. 141 142 $(CPP) : The system C preprocessor. 143 144 $(CFLAGS) : C compiler flags. 145 146 $(CPPFLAGS) : Preprocessor flags, e.g. -I arguments. 147 148 $(CXXFLAGS) : C++ compiler flags, e.g. -I arguments. 149 150 $(DEBUG_CFLAGS) : Debug flags to pass to $(CC), -g, etc. 151 152 $(DEBUG_CXXFLAGS) : Debug flags to pass to $(CXX). 153 154 $(LD) : The system linker (typically $(CC), but not 155 necessarily). 156 157 $(LDFLAGS) : What to pass in to the linker, including -L arguments 158 and other ld arguments, apart from -l library 159 includes (see $(LDLIBS)). 160 161 This should be done in the $(CC) args passing style 162 when LD := $(CC), e.g. `-Wl,-foo', as opposed to 163 `-foo'. 164 165 $(LDLIBS) : Libraries to pass to the linker (e.g. -lltp, etc). 166 167 $(OPT_CFLAGS) : Optimization flags to pass into the C compiler, -O2, 168 etc. If you specify -O2 or higher, you should also 169 specify -fno-strict-aliasing, because of gcc 170 fstrict-aliasing optimization bugs in the tree 171 optimizer. Search for `fstrict-aliasing optimization 172 bug' with your favorite search engine. 173 174 Examples of more recent bugs: 175 1. tree-optimization/17510 176 2. tree-optimization/39100 177 178 Various bugs have occurred in the past due to buggy 179 logic in the tree-optimization portion of the gcc 180 compiler, from 3.3.x to 4.4. 181 182 $(OPT_CXXFLAGS) : Optimization flags to pass to the C++ compiler. 183 184 $(RANLIB) : What to run after archiving a library. 185 186 $(WCFLAGS) : Warning flags to pass to $(CC), e.g. -Werror, 187 -Wall, etc. 188 189 $(WCXXFLAGS) : Same as $(WCFLAGS), but for $(CXX). 190 ------------------------------------------------------------------------------- 191 192 Make System Variables 193 --------------------- 194 195 A series of variables are used within the make system that direct what actions 196 need to be taken. Rather than me listing the variables here, please with their 197 intended uses, please refer to the comments contained in 198 +.../include/mk/env_pre.mk+. 199 200 Guidelines and Recommendations 201 ------------------------------ 202 203 Of course, the GNU Make manual is key to understanding the Make system, but 204 here are the following sections and chapters I suggest reviewing: 205 206 link:http://www.gnu.org/software/make/manual/make.html#Implicit-Rules[Implicit Rules] 207 link:http://www.gnu.org/software/make/manual/make.html#Using-Variables[Variables and Expansion] 208 link:http://www.gnu.org/software/make/manual/make.html#Origin-Function[Origin Use] 209 link:http://www.gnu.org/software/make/manual/make.html#Directory-Search[VPath Use] 210 211 Before Committing 212 ----------------- 213 214 One should rebuild from scratch before committing. Please see INSTALL for more 215 details. 216 217 Other Errata 218 ------------ 219 220 Please see TODO for any issues related to the Makefile infrastructure, and 221 build structure / source tree in general. 222
