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