1 \input texinfo @c -*-texinfo-*-
4 @settitle Ocera Make System
8 Manual for Ocera Make System (OMK)
10 Copyright @copyright{} 2007 Michal Sojka, Pavel Pisa
14 @title Ocera Make System Manual
16 @vskip 0pt plus 1filll
24 @top Ocera Make System
34 OMK is an advanced make system written entirely in GNU make. Compiling
35 software using OMK requires only GNU make binary and standard UNIX
36 utilities installed. OMK aims to be developer friendly; to use OMK,
37 you do not need to understand (sometiles) cryptic syntax of makefile
45 OMK was originally written by Pavel Pisa as a solution to have one
46 common make system for OCERA project, where we needed to compile
47 user-space programs, Linux kernel modules and RT Linux modules in one
48 package. Although this system was not accepted for the whole OCERA
49 project. Several individual developers (mostly from Czech Technical
50 University) liked it and started to use it.
52 As number of users grew it was necessary to modularize the make system
53 to support more ``targets''. Michal Sojka took care about the process
56 @chapter Original README
58 @b{Important notice:} This make system uses features found in recent
59 versions of GNU Make program. If you encounter problems with package
60 building, check, that you use correct version of Make program. The
61 Make older than version 3.80, could not be used. Even Make version
62 3.80 has annoying bug which causes building fail with misleading
63 message "virtual memory exhausted". Please, upgrade at least to
64 version 3.81 of GNU Make.
66 There is list of features which we want to solve with our make system:
69 Central @file{Makefile.rules} for most of components of a bigger project.
71 FIXME (our CAN framework includes more libraries common with our other
72 projects, we need to separate some utility libraries etc.)
74 The rules in more spread Makefiles are way to the hell (update for
75 different kernel, RT-Linux etc would be nightmare in other case).
77 Make system should allow to freely move cross-dependant components in
78 directory structure without need to update users of moved component (I
79 hate somethink like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
80 example. If a component is renamed or version is added to then name,
81 all Makefiles in CAN will require update).
83 Make system should be able to compile mutually cross-dependant
84 libraries and should ensure, that change in one component sources or
85 headers would result in relink or rebuild in components linked against
86 that library or including modified header file.
88 Make system has to enable compilation out of OCERA full source tree
89 (we would lost many users of particular components in other case).
91 Compile should be able to do all above work without need to install
92 any files before successful finish of build.
94 Because we use some libraries for RT-Linux build and user-space build,
95 we need to solve how to compile from same sources to both targets.
97 The build system should allow to call make for particular source
98 subdirectory. Time of recursive make through all subdirectories is
101 Make system should enable to build out of sources tree (else clean or
102 working with CVS sandbox gets fussy and simultaneous multiple targets
105 It would be good, if there is a possibility to call make from
106 read-only media sources.
108 Make system should store results of build in some separate directory
109 structure to simple install and testing.
111 Makefiles in sources directories should be simple.
114 There is probably only one alternative fully supporting above requirements
115 and it is GNU Autoheader...Automake...Autoconf... system.
116 But it is complicated and requires big amount of support files.
117 It would be acceptable if it could be easily used for OCERA framework.
118 But there are important show stoppers for that system:
121 It would require deep revision of all OCERA CVS contents and agreement
122 on this would be problematic
124 This system is not well prepared for dual compilation for Linux and
125 RT-Linux sub-targets. It would mean many changes in default autoconf
126 setup to support this. Probably simplest way would be to rebuild GCC
127 tool chain for something like i586-elf-rtlinux. This would require
128 even more space for OCERA development.
131 The problem calls for same solution, which would have minimal impact
132 on other components and would be elegant and would be maintainable
133 and small, because our main goal is components development and not
134 make systems development.
136 There is result of our trial. It is OMK make system.
137 The @file{Makefile} and @file{Makefile.omk} files should be in all source
138 directories. Common @file{Makefile.rules} file is required in the toplevel
139 sources directory. Alternatively this file could be moved
140 to link tree pointing into readonly media or can be anywhere
141 else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
143 Syntax of Makefile.omk files is for usual cases compatible
144 to Automake's Makefile.am descriptions. There are specific targets
145 for RT-Linux and Linux kernel related stuff
147 Makefile.omk user defined variables
150 list of subdirectories intended for make from actual directory
152 list of the user-space libraries
153 @item shared_LIBRARIES
154 list of the user-space shared libraries
155 @item kernel_LIBRARIES
156 list of the kernel-space libraries
157 @item rtlinux_LIBRARIES
158 list of the RT-Linux kernel-space libraries
159 @item include_HEADERS
160 list of the user-space header files
161 @item nobase_include_HEADERS
162 headers copied even with directory part
164 list of the kernel-space header files
165 @item rtlinux_HEADERS
166 list of the RT-Linux kernel-space header files
168 list of the require binary programs
170 list of the development utility programs
172 list of the kernel side modules/applications
173 @item rtlinux_MODULES
174 list of RT-Linux the kernel side modules/applications
176 list of specific target sources
178 additional include directories and defines for user-space
179 @item kernel_INCLUDES
180 additional include directories and defines for kernel-space
181 @item rtlinux_INCLUDES
182 additional include directories and defines for RT-Linux
184 list of default config assignments CONFIG_XXX=y/n ...
187 The Makefile is same for all sources directories and is only 14 lines
188 long. It is there only for convenience reasons to enable call "make"
189 from local directory. It contains code which locates
190 @file{Makefile.rules} in actual or any parent directory. With standard
191 BASH environment it works such way, that if you get into sources
192 directory over symbolic links, it is able to unwind yours steps back
193 => you can make links to readonly media component directories, copy
194 @file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
195 Makefile.omk to contain only required components and then call make in
196 top or even directories after crossing from your tree to readonly
199 The system compiles all files out of source directories. The actual
200 version of system is adapted even for OCERA tree mode if
201 @code{OCERA_DIR} variable is defined in @file{Makefile.rules}
203 There are next predefined directory name components, which can be
207 @item BUILD_DIR_NAME = _build
208 prefix of directory, where temporary build files are stored
209 @item COMPILED_DIR_NAME = _compiled
210 prefix of directory, where final compilation results are stored
211 @item GROUP_DIR_NAME = yyy
212 this is used for separation of build sub-trees in OCERA environment
213 where more @file{Makefile.rules} is spread in the tree
216 Next directories are used:
219 @item KERN_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
220 directory to store intermediate files for kernel-space targets
221 @item USER_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
222 directory to store intermediate files for user-space targets
224 @item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
225 directory to store exported include files which should be installed later
226 on user-space include path
227 @item USER_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
228 same for user-pace libraries
229 @item USER_UTILS_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
230 utilities for testing, which would not probably be installed
231 @item USER_BIN_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
232 binaries, which should go into directory on standard system PATH
233 (/usr/local/bin, /usr/bin or $(prefix)/bin)
235 @item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
236 directory to store exported include files which should be installed later
237 on kernel-space include path
238 @item KERN_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
239 same for kernel-pace libraries
240 @item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
241 builded modules for Linux kernel or RT-Linux system
244 There is more recursive passes through directories to enable
245 mutual dependant libraries and binaries to compile.
246 Next passes are defined
250 generates @file{config.omk-default} or xxx-default (FIXME) configuration file
252 checks and creates required build directories
254 copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
256 builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
258 @item binary-pass and utils-pass
259 links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
260 object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
261 @item kernel-lib-pass
262 builds libraries for kernel space targets
264 builds kernel modules
267 The amount of passes is relatively high and consumes some time. But
268 only other way to support all required features is to assemble one big
269 toplevel Makefile, which would contain all components and targets
272 Drawbacks of designed make system
275 the system is not as fast as we would like
277 it lacks Autoconf and configure extensive support for many systems
278 from UNIX to DOS and WINDOWS
280 it does not contain support for checking existence of target
281 libraries and functionalities as GNU Autoconf
283 it is heavily dependant on GNU MAKE program. But it would not be big
284 problem, because even many commercial applications distribute GNU MAKE
285 with them to be able to work in non-friendly systems
287 the key drawback is dependence on recent MAKE version 3.80 and better
288 and even version 3.80 of MAKE has important bug, which has been
289 corrected in newer sources (FIXME)
292 The last point is critical. I have not noticed it first, because
293 I use Slackware-9.2 and it contains latest released version
294 of MAKE (version 3.80).
295 The problem appears when I have tried to build bigger libraries.
296 There is bug in version 3.80, which results in misleading
297 error "Virtual memory exhausted". It is known bug with ID 1517
300 * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
304 I have optimized some rules to not push memory to the edge,
305 but there could be still issues with 3.80 version.
307 I have downloaded latest MAKE CVS sources. The compilation required
308 separate lookup and download for .po files and full Autoheader... cycle.
309 I have put together package similar to release. Only ./configure --prefix=...
310 and make is required. CVS sources contains version 3.81beta1.
311 You can download prepared sources archive from
312 @indicateurl{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
313 Or you can get our local copy from
314 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
316 The archive contains even "make" binary build by me, which should work
317 on other Linux distributions as well. Older version of MAKE (3.79.x
318 released about year 2000) found on Mandrake and RedHat are not
319 sufficient and do not support eval feature. I do not expect, that
320 Debian would be more up-to-date or contain fixes to MAKE vm exhausted
323 The local CTU archive with our CAN components prepared for inclusion
324 into OCERA SF CVS could be found in my "can" directory
326 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
328 The code should build for user-space with new make on most of Linux distros
329 when make is updated.
331 If you want to test compile for RT-Linux targets, line
334 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
337 in @file{Makefile.rules} has to be activated and updated
338 to point RT-Linux directory containing "rtl.mk".
339 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
340 (@file{can/utils/ulut/ul_rtlchk.c}).
342 The next line, if enabled, controls compilation in OCERA project tree
345 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
348 The LinCAN driver has been updated to compile out of source directories.
350 Please, check, if you could compile CAN package and help us with integration
351 into OCERA SF CVS. Send your comments and objections.
353 The OMK system has been adapted to support actual OCERA configuration process.
354 I am not happy with ocera.mk mix of defines and poor two or three rules,
355 but OMK is able to overcome that.
357 The OMK system has integrated rules (default-config) to build default
358 configuration file. The file is named @file{config.omk-default} for
359 the stand-alone compilation. The name corresponds to OCERA config +
360 "-default" if OCERA_DIR is defined. This file contains statements
361 from all @code{default_CONFIG} lines in all @file{Makefile.omk}. The
362 file should be used for building of own @file{config.omk} file, or as
363 list for all options if Kconfig is used.
365 @chapter OMK User Manual
367 @section Basic Concepts
369 @section Dependency Tracking
371 @section Compiling Simple Programs
375 @section Configuration and Conditional Compilation
377 @chapter OMK Reference
379 @chapter OMK Development
384 @unnumbered Variable Index
389 @unnumbered Concept Index