diff options
Diffstat (limited to 'doc/Build-System.rest')
| -rw-r--r-- | doc/Build-System.rest | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/doc/Build-System.rest b/doc/Build-System.rest new file mode 100644 index 000000000..e078fa7f7 --- /dev/null +++ b/doc/Build-System.rest @@ -0,0 +1,218 @@ +Short introduction into LTP build system +======================================== + +****************************************************************************** +The following document briefly describes the steps and methodologies used for +the new and improved Makefile system. + +Changelog: + + * Initial version: Ngie Cooper <yaneurabeya@gmail.com> + * Reformated for asciidoc: Cyril Hrubis <chrubis@suse.cz> +****************************************************************************** + +The Problem +----------- + +The problem with the old Makefile system is that it was very difficult to +maintain and it lacked any sense of formal structure, thus developing for LTP +and including new targets was more difficult than it should have been +(maintenance). Furthermore, proper option-based cross-compilation was +impossible due to the fact that the Makefiles didn't support a prefixing +system, and the appropriate implicit / static rules hadn't been configured to +compile into multiple object directories for out-of-tree build support (ease of +use / functionality). Finally, there wasn't a means to setup dependencies +between components, such that if a component required libltp.a in order to +compile, it would go off and compile libltp.a first (ease of use). + +These items needed to be fixed to reduce maintenance nightmares for the +development community contributing to LTP, and the project maintainers. + +Design +------ + +The system was designed such that including a single GNU Makefile compatible +set in each new directory component is all that's essentially required to +build the system. + +Say you had a directory like the following (with .c files in them which +directly tie into applications, e.g. baz.c -> baz): + +------------------------------------------------------------------------------- +.../foo/ + |--> Makefile + | + --> bar/ + | + --> Makefile + | + --> baz.c +------------------------------------------------------------------------------- + +Here's an example of how one would accomplish that: + +------------------------------------------------------------------------------- +.../foo/Makefile: +# +# Copyright disclaimer goes here -- please use GPLv2. +# + +top_srcdir ?= .. + +include $(top_srcdir)/include/mk/env_pre.mk +include $(top_srcdir)/include/mk/generic_trunk_target.mk + +.../foo/bar/Makefile: +# +# Copyright disclaimer goes here -- please use GPLv2. +# + +top_srcdir ?= .. + +include $(top_srcdir)/include/mk/env_pre.mk +include $(top_srcdir)/include/mk/generic_leaf_target.mk +------------------------------------------------------------------------------- + +Kernel Modules +-------------- + +Some of the tests need to build kernel modules, happily LTP has +infrastructure for this. + +------------------------------------------------------------------------------- +ifneq ($(KERNELRELEASE),) + +obj-m := module01.o + +else + +top_srcdir ?= ../../../.. +include $(top_srcdir)/include/mk/testcases.mk + +REQ_VERSION_MAJOR := 2 +REQ_VERSION_PATCH := 6 +MAKE_TARGETS := test01 test02 module01.ko + +include $(top_srcdir)/include/mk/module.mk +include $(top_srcdir)/include/mk/generic_leaf_target.mk + +endif +------------------------------------------------------------------------------- + +This is example Makefile that allows you build kernel modules inside of LTP. +The prerequisites for the build are detected by the 'configure' script. + +The 'REQ_VERSION_MAJOR' and 'REQ_VERSION_PATCH' describe minimal kernel +version for which the build system tries to build the module. + +The buildsystem is also forward compatible with changes in Linux kernel +internal API so that if module fails to build the failure is ignored both on +build and installation. If the userspace counterpart of the test fails to load +the module because the file does not exists, the test is skipped. + +Note the 'ifneq($(KERNELRELEASE),)', the reason it's there is that the +Makefile is executed twice, once by LTP build system and once by kernel +kbuild, see 'Documentation/kbuild/modules.txt' in the Linux kernel tree for +details on external module build. + +Make Rules and Make Variables +----------------------------- + +When using make rules, avoid writing ad hoc rules like: + +------------------------------------------------------------------------------- +[prog]: [dependencies] + cc -I../../include $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(LDLIBS) \ + -o [prog] [dependencies] +------------------------------------------------------------------------------- + +etc. This makes cross-compilation and determinism difficult, if not impossible. +Besides, implicit rules are your friends and as long as you use `MAKEOPTS=;' in +the top-level caller (or do $(subst r,$(MAKEOPTS)) to remove -r), the compile +will complete successfully, assuming all other prerequisites have been +fulfilled (libraries, headers, etc). + +------------------------------------------------------------------------------- +$(AR) : The library archiver. + +$(CC) : The system C compiler. + +$(CPP) : The system C preprocessor. + +$(CFLAGS) : C compiler flags. + +$(CPPFLAGS) : Preprocessor flags, e.g. -I arguments. + +$(DEBUG_CFLAGS) : Debug flags to pass to $(CC), -g, etc. + +$(KVM_LD) : Special linker for wrapping KVM payload binaries + into linkable object files. Defaults to $(LD). + Change this variable if the KVM Makefile fails + to build files named *-payload.o. + +$(LD) : The system linker (typically $(CC), but not + necessarily). + +$(LDFLAGS) : What to pass in to the linker, including -L arguments + and other ld arguments, apart from -l library + includes (see $(LDLIBS)). + + This should be done in the $(CC) args passing style + when LD := $(CC), e.g. `-Wl,-foo', as opposed to + `-foo'. + +$(LDLIBS) : Libraries to pass to the linker (e.g. -lltp, etc). + +$(LTPLDLIBS) : LTP internal libraries i.e. these in libs/ directory. + +$(OPT_CFLAGS) : Optimization flags to pass into the C compiler, -O2, + etc. If you specify -O2 or higher, you should also + specify -fno-strict-aliasing, because of gcc + fstrict-aliasing optimization bugs in the tree + optimizer. Search for `fstrict-aliasing optimization + bug' with your favorite search engine. + + Examples of more recent bugs: + 1. tree-optimization/17510 + 2. tree-optimization/39100 + + Various bugs have occurred in the past due to buggy + logic in the tree-optimization portion of the gcc + compiler, from 3.3.x to 4.4. + +$(RANLIB) : What to run after archiving a library. + +$(WCFLAGS) : Warning flags to pass to $(CC), e.g. -Werror, + -Wall, etc. +------------------------------------------------------------------------------- + +Make System Variables +--------------------- + +A series of variables are used within the make system that direct what actions +need to be taken. Rather than me listing the variables here, please with their +intended uses, please refer to the comments contained in ++.../include/mk/env_pre.mk+. + +Guidelines and Recommendations +------------------------------ + +Of course, the GNU Make manual is key to understanding the Make system, but +here are the following sections and chapters I suggest reviewing: + +link:http://www.gnu.org/software/make/manual/make.html#Implicit-Rules[Implicit Rules] +link:http://www.gnu.org/software/make/manual/make.html#Using-Variables[Variables and Expansion] +link:http://www.gnu.org/software/make/manual/make.html#Origin-Function[Origin Use] +link:http://www.gnu.org/software/make/manual/make.html#Directory-Search[VPath Use] + +Before Committing +----------------- + +One should rebuild from scratch before committing. Please see INSTALL for more +details. + +Other Errata +------------ + +Please see TODO for any issues related to the Makefile infrastructure, and +build structure / source tree in general. |