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