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