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 (@command{sh}, @command{sed} and
37 @command{tr}@footnote{@command{tr} is needed only for OMK to be
38 compatible with MinGW.}) installed. OMK aims to be developer friendly; to
39 use OMK, you do not need to understand (sometimes) cryptic syntax of
42 OMK handles properly dependencies of source files and libraries, so it
43 is not necessary to recompile the whole project if only some files are
44 changed. Also OMK greatly simplifies compilation of projects, where
45 source files are spread between multiple directories. It is also very
46 useful in combining components (libraries) from different projects to a
49 You can use OMK on all platforms where you can run GNU Make including
50 Cygwin and MinGW. MS DOS was not tested.
56 @c Easy to use for beginners.
58 @c Automatic handling of dependencies.
60 @c Supported host platforms: all Un*x operating system including Linux,
61 @c Cygwin, MS DOS and maybe others.
66 If you get some sources, which are distributed with OMK, usually the
67 following commands are sufficient to compile the whole project.
76 To use OMK in your own project, follow these steps:
80 Take appropriate @file{Makefile.rules}, put it together with leaf
81 @file{Makefile} to the root directory of your project.
83 Create @file{Makefile.omk} files in all directories you want to
84 compile something. Please refer to chapter ... to learn what to write
85 in @file{Makefile.omk} files.
87 Run @command{make omkize} in the root directory.
90 Your project is now ready to compile.
96 OMK was originally written by Pavel Pisa as a solution to have one
97 common make system for OCERA project, where we needed to compile
98 user-space programs, Linux kernel modules and RT Linux modules in one
99 package. Although this system was not accepted for the whole OCERA
100 project. Several individual developers (mostly from Czech Technical
101 University) liked it and started to use it.
103 As a number of projects using OMK grew it was necessary to modularize
104 the make system to support more ``targets''. Michal Sojka took care
105 about the process of modularization.
107 @chapter Original README
109 @b{Important notice:} This make system uses features found in recent
110 versions of GNU Make program. If you encounter problems with package
111 building, check, that you use correct version of Make program. The
112 Make older than version 3.80, could not be used. Even Make version
113 3.80 has annoying bug which causes building fail with misleading
114 message "virtual memory exhausted". Please, upgrade at least to
115 version 3.81 of GNU Make.
117 There is list of features which we want to solve with our make system:
120 Central @file{Makefile.rules} for most of components of a bigger project.
122 FIXME (our CAN framework includes more libraries common with our other
123 projects, we need to separate some utility libraries etc.)
125 The rules in more spread Makefiles are way to the hell (update for
126 different kernel, RT-Linux etc would be nightmare in other case).
128 Make system should allow to freely move cross-dependant components in
129 directory structure without need to update users of moved component (I
130 hate somethink like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
131 example. If a component is renamed or version is added to then name,
132 all Makefiles in CAN will require update).
134 Make system should be able to compile mutually cross-dependant
135 libraries and should ensure, that change in one component sources or
136 headers would result in relink or rebuild in components linked against
137 that library or including modified header file.
139 Make system has to enable compilation out of OCERA full source tree
140 (we would lost many users of particular components in other case).
142 Compile should be able to do all above work without need to install
143 any files before successful finish of build.
145 Because we use some libraries for RT-Linux build and user-space build,
146 we need to solve how to compile from same sources to both targets.
148 The build system should allow to call make for particular source
149 subdirectory. Time of recursive make through all subdirectories is
152 Make system should enable to build out of sources tree (else clean or
153 working with CVS sandbox gets fussy and simultaneous multiple targets
156 It would be good, if there is a possibility to call make from
157 read-only media sources.
159 Make system should store results of build in some separate directory
160 structure to simple install and testing.
162 Makefiles in sources directories should be simple.
165 There is probably only one alternative fully supporting above requirements
166 and it is GNU Autoheader...Automake...Autoconf... system.
167 But it is complicated and requires big amount of support files.
168 It would be acceptable if it could be easily used for OCERA framework.
169 But there are important show stoppers for that system:
172 It would require deep revision of all OCERA CVS contents and agreement
173 on this would be problematic
175 This system is not well prepared for dual compilation for Linux and
176 RT-Linux sub-targets. It would mean many changes in default autoconf
177 setup to support this. Probably simplest way would be to rebuild GCC
178 tool chain for something like i586-elf-rtlinux. This would require
179 even more space for OCERA development.
182 The problem calls for same solution, which would have minimal impact
183 on other components and would be elegant and would be maintainable
184 and small, because our main goal is components development and not
185 make systems development.
187 There is result of our trial. It is OMK make system.
188 The @file{Makefile} and @file{Makefile.omk} files should be in all source
189 directories. Common @file{Makefile.rules} file is required in the toplevel
190 sources directory. Alternatively this file could be moved
191 to link tree pointing into readonly media or can be anywhere
192 else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
194 Syntax of Makefile.omk files is for usual cases compatible
195 to Automake's Makefile.am descriptions. There are specific targets
196 for RT-Linux and Linux kernel related stuff
198 Makefile.omk user defined variables
201 list of subdirectories intended for make from actual directory
203 list of the user-space libraries
204 @item shared_LIBRARIES
205 list of the user-space shared libraries
206 @item kernel_LIBRARIES
207 list of the kernel-space libraries
208 @item rtlinux_LIBRARIES
209 list of the RT-Linux kernel-space libraries
210 @item include_HEADERS
211 list of the user-space header files
212 @item nobase_include_HEADERS
213 headers copied even with directory part
215 list of the kernel-space header files
216 @item rtlinux_HEADERS
217 list of the RT-Linux kernel-space header files
219 list of the require binary programs
221 list of the development utility programs
223 list of the kernel side modules/applications
224 @item rtlinux_MODULES
225 list of RT-Linux the kernel side modules/applications
227 list of specific target sources
229 additional include directories and defines for user-space
230 @item kernel_INCLUDES
231 additional include directories and defines for kernel-space
232 @item rtlinux_INCLUDES
233 additional include directories and defines for RT-Linux
235 list of default config assignments CONFIG_XXX=y/n ...
238 The Makefile is same for all sources directories and is only 14 lines
239 long. It is there only for convenience reasons to enable call "make"
240 from local directory. It contains code which locates
241 @file{Makefile.rules} in actual or any parent directory. With standard
242 BASH environment it works such way, that if you get into sources
243 directory over symbolic links, it is able to unwind yours steps back
244 => you can make links to readonly media component directories, copy
245 @file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
246 Makefile.omk to contain only required components and then call make in
247 top or even directories after crossing from your tree to readonly
250 The system compiles all files out of source directories. The actual
251 version of system is adapted even for OCERA tree mode if
252 @code{OCERA_DIR} variable is defined in @file{Makefile.rules}
254 There are next predefined directory name components, which can be
258 @item BUILD_DIR_NAME = _build
259 prefix of directory, where temporary build files are stored
260 @item COMPILED_DIR_NAME = _compiled
261 prefix of directory, where final compilation results are stored
262 @item GROUP_DIR_NAME = yyy
263 this is used for separation of build sub-trees in OCERA environment
264 where more @file{Makefile.rules} is spread in the tree
267 Next directories are used:
270 @item KERN_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
271 directory to store intermediate files for kernel-space targets
272 @item USER_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
273 directory to store intermediate files for user-space targets
275 @item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
276 directory to store exported include files which should be installed later
277 on user-space include path
278 @item USER_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
279 same for user-pace libraries
280 @item USER_UTILS_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
281 utilities for testing, which would not probably be installed
282 @item USER_BIN_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
283 binaries, which should go into directory on standard system PATH
284 (/usr/local/bin, /usr/bin or $(prefix)/bin)
286 @item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
287 directory to store exported include files which should be installed later
288 on kernel-space include path
289 @item KERN_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
290 same for kernel-pace libraries
291 @item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
292 builded modules for Linux kernel or RT-Linux system
295 There is more recursive passes through directories to enable
296 mutual dependant libraries and binaries to compile.
297 Next passes are defined
301 generates @file{config.omk-default} or xxx-default (FIXME) configuration file
303 checks and creates required build directories
305 copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
307 builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
309 @item binary-pass and utils-pass
310 links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
311 object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
312 @item kernel-lib-pass
313 builds libraries for kernel space targets
315 builds kernel modules
318 The amount of passes is relatively high and consumes some time. But
319 only other way to support all required features is to assemble one big
320 toplevel Makefile, which would contain all components and targets
323 Drawbacks of designed make system
326 the system is not as fast as we would like
328 it lacks Autoconf and configure extensive support for many systems
329 from UNIX to DOS and WINDOWS
331 it does not contain support for checking existence of target
332 libraries and functionalities as GNU Autoconf
334 it is heavily dependant on GNU MAKE program. But it would not be big
335 problem, because even many commercial applications distribute GNU MAKE
336 with them to be able to work in non-friendly systems
338 the key drawback is dependence on recent MAKE version 3.80 and better
339 and even version 3.80 of MAKE has important bug, which has been
340 corrected in newer sources (FIXME)
343 The last point is critical. I have not noticed it first, because
344 I use Slackware-9.2 and it contains latest released version
345 of MAKE (version 3.80).
346 The problem appears when I have tried to build bigger libraries.
347 There is bug in version 3.80, which results in misleading
348 error "Virtual memory exhausted". It is known bug with ID 1517
351 * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
355 I have optimized some rules to not push memory to the edge,
356 but there could be still issues with 3.80 version.
358 I have downloaded latest MAKE CVS sources. The compilation required
359 separate lookup and download for .po files and full Autoheader... cycle.
360 I have put together package similar to release. Only ./configure --prefix=...
361 and make is required. CVS sources contains version 3.81beta1.
362 You can download prepared sources archive from
363 @indicateurl{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
364 Or you can get our local copy from
365 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
367 The archive contains even "make" binary build by me, which should work
368 on other Linux distributions as well. Older version of MAKE (3.79.x
369 released about year 2000) found on Mandrake and RedHat are not
370 sufficient and do not support eval feature. I do not expect, that
371 Debian would be more up-to-date or contain fixes to MAKE vm exhausted
374 The local CTU archive with our CAN components prepared for inclusion
375 into OCERA SF CVS could be found in my "can" directory
377 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
379 The code should build for user-space with new make on most of Linux distros
380 when make is updated.
382 If you want to test compile for RT-Linux targets, line
385 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
388 in @file{Makefile.rules} has to be activated and updated
389 to point RT-Linux directory containing "rtl.mk".
390 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
391 (@file{can/utils/ulut/ul_rtlchk.c}).
393 The next line, if enabled, controls compilation in OCERA project tree
396 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
399 The LinCAN driver has been updated to compile out of source directories.
401 Please, check, if you could compile CAN package and help us with integration
402 into OCERA SF CVS. Send your comments and objections.
404 The OMK system has been adapted to support actual OCERA configuration process.
405 I am not happy with ocera.mk mix of defines and poor two or three rules,
406 but OMK is able to overcome that.
408 The OMK system has integrated rules (default-config) to build default
409 configuration file. The file is named @file{config.omk-default} for
410 the stand-alone compilation. The name corresponds to OCERA config +
411 "-default" if OCERA_DIR is defined. This file contains statements
412 from all @code{default_CONFIG} lines in all @file{Makefile.omk}. The
413 file should be used for building of own @file{config.omk} file, or as
414 list for all options if Kconfig is used.
416 @chapter OMK User's Manual
418 @section Basic Concepts
420 @section Dependency Tracking
422 @section Compiling Simple Programs
426 @section Configuration and Conditional Compilation
428 @section Running OMK under Windows OS
430 @chapter OMK Reference
432 @chapter OMK Development
437 @unnumbered Variable Index
442 @unnumbered Concept Index