1 \input texinfo @c -*-texinfo-*-
3 @setfilename omk-manual
4 @settitle OMK: 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
23 @node Top, Overview of OMK, (dir), (dir)
24 @top Ocera Make System
38 @node Overview of OMK, OMK User's Manual, Top, Top
42 OMK is an advanced make system written entirely in GNU make. Compiling
43 software using OMK requires only GNU make binary and standard UNIX
44 utilities (@command{sh}, @command{sed}, @command{cmp} and
45 @command{tr}@footnote{@command{tr} is needed only for OMK to be
46 compatible with MinGW.}) installed. OMK aims to be developer friendly;
47 to use OMK, you do not need to understand (sometimes) cryptic syntax of
50 You can use OMK on all platforms where you can run GNU Make including
51 Cygwin and MinGW. MS DOS was not tested.
57 @c Easy to use for beginners.
59 @c Automatic handling of dependencies.
61 @c Supported host platforms: all Un*x operating system including Linux,
62 @c Cygwin, MS DOS and maybe others.
71 @node Why to Use OMK?, Quick Start, Overview of OMK, Overview of OMK
72 @section Why to Use OMK?
74 Here we list some of OMK features, which we think are important for
75 choosing of a make system.
80 Makefile in source directories are usually very @b{simple}.
82 There is only @b{one} @file{Makefile.rules} for most of components of
85 OMK greatly simplifies compilation of projects, where source files are
86 spread between @b{multiple directories}.
88 OMK handles properly @b{dependencies} of source files and libraries,
89 so it is not necessary to recompile the whole project if only several
92 OMK allows to freely @b{move} cross-dependant components @b{in
93 directory structure} without the need to update users of moved
94 component. I hate something like
95 @option{-I../../sched/rtlshwq/include} in makefiles for example. If a
96 component is renamed or version is added to the name, many Makefiles
97 in the project would require an update.
99 The above feature is very helpful in @b{combining components}
100 (libraries) from different projects/developers to a single project by
101 simply creating symbolic links to external components.
103 Compilation of an OMK based projects don't require to install any
104 files before successful finish of build.
106 OMK allows to call @command{make} for a particular subdirectory in the
109 Under OMK all products of compilation are stored @b{out of source
110 directories}. This simplifies work with version control systems and
111 helps when simultaneous compilation for multiple targets/platforms is
116 @node Quick Start, History, Why to Use OMK?, Overview of OMK
119 If you get some sources, which are distributed with OMK, usually the
120 following commands are sufficient to compile the whole project.
129 @noindent To use OMK in your own project, follow these steps:
133 Take appropriate @file{Makefile.rules}, put it together with leaf
134 @file{Makefile} to the root directory of your project.
136 Create @file{Makefile.omk} files in all directories you want to
137 compile something. Please refer to @ref{OMK User's Manual} to learn
138 what to write in @file{Makefile.omk} files.
140 Run @command{make omkize} in the root directory.
143 @noindent Your project is now ready to compile.
146 @node History, , Quick Start, Overview of OMK
149 OMK was originally written by Pavel Pisa as a solution to have one
150 common make system for OCERA project, where we needed to compile
151 user-space programs, Linux kernel modules and RT Linux modules in one
152 package. Although this system was not accepted for the whole OCERA
153 project. Several individual developers (mostly from Czech Technical
154 University) liked it and started to use it.
156 As a number of projects using OMK grew it was necessary to modularize
157 the make system to support more ``targets''. Michal Sojka took care
158 about the process of modularization.
160 @node OMK User's Manual, Original README, Overview of OMK, Top
161 @chapter OMK User's Manual
166 * Compiling Programs::
168 * Multiple Directories::
169 * Dependency Tracking::
170 * Configuration and Conditional Compilation::
171 * Advanced OMK Features::
172 * Running OMK under Windows OS::
173 * Interfacing OMK to popular IDEs::
177 @node Basic Concepts, Invoking OMK, OMK User's Manual, OMK User's Manual
178 @section Basic Concepts
180 The main concept of OMK is very simple. In the root directory of the
181 projects resides a file called @file{Makefile.rules}. This file contains
182 all compilation rules needed for compilation of a particular
183 project. There are different @file{Makefile.rules} for different
184 platforms (Unix, RTEMS, system-less, ...). In every subdirectory a
185 @file{Makefile.omk} is stored. This file determines what should be done
186 in the respective directory (e.g. compile a program from several source
187 files). Its syntax is very simple -- see the following sections.
189 Since make searches by default for a @file{Makefile} and not for
190 @file{Makefile.rules} or @file{Makefile.omk}, there must be a small
191 generic @file{Makefile} in every directory, whose task is only to find
192 @file{Makefile.rules} in the actual or any parent directory and include
193 it. This search is performed only once at the beginning of compilation.
195 @c TODO: Pavel's note about qmake.
197 The compilation process itself is comprised of several passes. Every
198 pass traverses the whole directory structure@footnote{In future, we are
199 planning some optimization that allows OMK to traverse the directories
200 only once and thus decrease compilation time.} and does a particular
201 task in every directory of the project. Typically, these passes are:
203 @anchor{include-pass}
205 This pass takes all include files marked for ``export'' and copies
206 (or links) them to the @file{include} directory under
207 @file{_compiled} directory. @xref{Header Files}.
209 Also, during this pass, automatically generated header file are
210 generated according to the current
211 configuration. @xref{Configuration and Conditional Compilation}.
213 During this pass, all include files are in place, so all libraries
216 Finally, programs can be compiled and linked against libraries
217 created in the previous pass.
220 The results of compilation are stored under the @file{_compiled}
221 directory. This directory is structured as a classical Unix file-system
222 (it contains directories like @file{bin}, @file{lib} and @file{include})
223 and can be directly copied to the target device or to some directory on
224 a host computer (e.g. @file{/usr/local}).
226 Besides @file{_compiled} directory, there in a @file{_build}
227 directory. Under this directory are stored some temporary files and
228 intermediate compilation products (object files, dependency files etc.).
230 In the next section, we provide an overview of methods, how to invoke
231 OMK from command line. Section @ref{Interfacing OMK to popular IDEs}
232 covers running of OMK from popular IDEs.
234 Sections @ref{Compiling Programs} through @ref{Configuration and
235 Conditional Compilation} deals with the content of
236 @file{Makefile.omk}. Its syntax in usual cases compatible to GNU
237 Automake's @file{Makefile.am} syntax. Also, the scheme for naming
238 variables was inspired by Automake so most OMK variables have the name
239 like @samp{@var{target}_@var{TYPE}}.
241 @node Invoking OMK, Compiling Programs, Basic Concepts, OMK User's Manual
242 @section Invoking OMK
244 Before using OMK for the first time, you have to call:
246 @command{make default-config}
248 @noindent See @ref{Configuration and Conditional Compilation} for
249 details. If you forget to do this, OMK will notice you.
251 To compile the whole project or only some subtree of the project, call
255 @noindent in the appropriate directory.
257 To clean files in @file{_build} directory but not in @file{_compiled}
263 To clean the compilation completely, you can either remove
264 @file{_compiled} and @file{_build} directories manually, or call
266 @command{make distclean}
268 @noindent which does the same. This command removes these directories
269 even if you call it from a subdirectory.
271 To debug compilation problems, you can use @code{V} variable (see
277 You can also set values of some other variables on command line for
278 temporary change something. The example below compiles the code
279 temporarily with debugging information:
281 @command{make CFLAGS="-g -O0 -Wall"}
287 If this variable equals to @samp{1}, the whole command lines for all
288 executed commands are displayed. Otherwise, only short messages are
292 @node Compiling Programs, Libraries, Invoking OMK, OMK User's Manual
293 @section Compiling Programs
295 To tell OMK to compile a program, you need to set some variables in
296 @file{Makefile.omk} (usually) in the directory where program sources are
299 In the example bellow a program @command{test} will be compiled from
300 source @file{test.c}.
303 @verbatiminclude ../tests/programs/Makefile.omk
306 @noindent The variables are:
308 @anchor{bin_PROGRAMS}
310 Contains a list of names (whitespace separated) of programs to be
311 compiled in this directory.
314 @defvar test_PROGRAMS
315 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
316 stored in @file{bin-tests} directory instead of @file{bin}. This
317 variable is intended for various test programs not to be mixed with
321 @defvar utils_PROGRAMS
322 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
323 stored in @file{bin-utils} directory instead of @file{bin}. This
324 variable is intended for various development utilities not to be mixed
325 with the final product.
329 For every program name @var{xxx} in @code{bin_PROGRAMS}, this variable
330 contains a list of sources that are needed to compile the
331 executable. OMK uses an extension of the filename to determine the
332 compiler to compile this source.
336 This variable contains a list of libraries the program @var{xxx} will
345 This variable contains a list of libraries all programs in this
346 directory needs to be linked to.
350 Directives passed to the C or C++ compiler with additional directories
351 to be searched for header files. In most cases you need to specify an
352 absolute path. To specify a directory relative to the source
353 directory, you can use the @code{$(SOURCES_DIR)} variable, which
354 refers to the directory, where @file{Makefile.omk} is located. This
355 variable applies to all compilations invoked in the current directory.
358 INCLUDES = -I$(SOURCES_DIR)/my_include_dir
363 Directives passed to the C or C++ compiler with preprocessor macro
364 definitions. This variable applies to all compilations invoked in the
373 @c FIXME: INCLUDES variable should not be set by rtlinux rules.
375 @node Libraries, Multiple Directories, Compiling Programs, OMK User's Manual
379 With OMK, you can easily create statically or dynamically linked
380 libraries. The way of creating libraries is very similar to how programs
381 are created. @xref{Compiling Programs}.
383 In @file{Makefile.omk}, you specify several variables, which defines how
384 the libraries should be compiled. In the example below the library
385 @samp{mylib} is created from two sources @file{funca.c} and
386 @file{funcb.c}. Interface of this library is defined in
387 @file{myfunc.h}. Therfore, we export this header for use by other
391 @verbatiminclude ../tests/libraries/Makefile.omk
394 @noindent Variables for use with libraries are:
396 @defvar lib_LIBRARIES
397 Specifies a list of statically linked libraries to be compiled.
400 @defvar shared_LIBRARIES
401 Specifies a list of dynamically linked libraries to be compiled.
405 For every library name @var{xxx} in @code{lib_LIBRARIES} or
406 @code{shared_LIBRARIES}, this variable contains a list of sources that
407 are needed to compile the library. OMK uses an extension of the
408 filename to determine the compiler to compile this source.
415 @node Header Files, , Libraries, Libraries
416 @subsection Header Files
418 C and C++ libraries are not very useful without header files. OMK
419 provides several variables that specify activities on header files.
421 During compilation, header files are copied (or linked) from source
422 directories to the @file{_compiled} tree
423 (see @ref{include-pass}). Libraries and programs are then compiled against
426 @anchor{include_HEADERS}
427 @defvar include_HEADERS
428 Specifies the list of header files to be exported for use by other
429 libraries/programs. The files are exported directly to the
430 @file{include} directory even if the file is located in a subdirectory
431 (like @file{sci_regs.h} in the example below)
434 include_HEADERS = regs.h periph/sci_regs.h
438 @defvar nobase_include_HEADERS
439 Similar to @ref{include_HEADERS}, but the directory prefix is always
440 kept. To include the file exported by this variable, use
441 @code{#include <@var{prefix}/@var{header.h}>}.
444 @defvar renamed_include_HEADERS
445 Exports the header files under different name. The form of the items
446 in this whitespace separated list is: @var{real name}@code{->}@var{new
450 renamed_include_HEADERS = orte_config_omk_win32.h->orte_config.h
455 If this variable equals to @samp{y}, symbolic links to headers in
456 source directories are used in @file{_compiled} tree instead of
459 Normally, the header files are copied into @file{_compiled} directory
460 to be prepared for transfer into target location afterwards. Copying
461 ensures that resulting libraries are in correspondence with the header
462 files even if the header is changed by a developer but the library is
465 @c Another reason for having single include directory for the whole
466 @c project is tat every component knows where to find header files of
469 On the other side, the copying could make problems during
470 development. Most @acronym{IDE}s, allows you to jump directly to the
471 place, where an error is reported by the compiler. If the error is in
472 a header file, IDE opens you the copy of the header file. If you
473 correct the error there, after the next compilation, your header file
474 will be overwritten by the old version from your source tree.
476 This option is not typically used in @file{Makefile.omk}, but in the
477 top level configuration file @file{config.omk} or on command line.
480 @node Multiple Directories, Dependency Tracking, Libraries, OMK User's Manual
481 @section Multiple Directories
483 OMK is probably most useful in projects consisting of multiple
484 directories. For such projects, it is not easy to write from scratch
485 classic Makefiles that provides all the needed features.
487 You can instruct OMK to descend to a (sub)directory by setting the
488 @code{SUBDIRS} variable in @file{Makefile.omk}.
491 This variable contains a list of directories, in which compilation
492 must be also invoked. Usually, names of subdirectories are used, but
493 you can use any path specification here.
495 Compilation is invoked in these directories before it is invoked in
496 the current directory.
498 @c TODO: Write tests for this.
500 @defvar ALL_OMK_SUBDIRS
501 This variable is set by OMK and can be used as the value of
502 @code{SUBDIRS} variable. It contains a list of all direct
503 subdirectories, which contain @file{Makefile.omk}. This is especially
504 useful if you are combining several projects or components
505 together. In the root directory of your project, you just create
506 symbolic links the components from other projects and all the linked
507 directories automatically appears as the value of this variable.
510 SUBDIRS = $(ALL_OMK_SUBDIRS)
514 @node Dependency Tracking, Configuration and Conditional Compilation, Multiple Directories, OMK User's Manual
515 @section Dependency Tracking
517 OMK automatically handles tracking of dependencies of files in compiled
518 projects. It uses gcc's @option{-M@var{x}} options to do this for object
519 files. This way, whenever you change some header file, OMK recompiles
520 only those files, where the changed header was really included.
522 Dependencies are also maintained for libraries and binaries. To find the
523 dependencies, OMK parses linker map files, so a change to some library
524 causes recompilation of all programs using that library.
526 @node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, OMK User's Manual
527 @section Configuration and Conditional Compilation
529 In many projects, it is necessary to configure a compilation process. By
530 this configuring we mean, setting some parameters that influence the
531 output of compilation process. In GNU projects, @command{configure}
532 script is usually responsible for configuration. User provides some
533 parameters to @command{configure}, which is run before compilation, and
534 this script does all steps needed to configure the sources and
535 make-system in the desired way.
537 OMK has its own configuration mechanism, which is described in this
538 section. For future releases, we plan that this mechanism can make use
539 of GNU Autoconf, but currently there is no directly integrated support
542 In every directory you can specify some configuration parameters, which
543 can be modified by a user. Then, when @command{make default-config} is
544 run, all these parameters are found and together with their default
545 values are stored as makefile variables in
546 @file{config.omk-default}. This file is included during compilation, so
547 if you don't specify other values, these defaults are used. If you are
548 not satisfied with these defaults, you can override the values of
549 parameters in @file{config.omk}. This file is also included during
550 compilation and variables mentioned there takes precedence over those
551 specified in @file{config.omk-default}. Both @file{config.omk} and
552 @file{config.omk-default} have to be stored in the same directory as
553 @file{Makefile.rules}.
555 Besides overriding the default values of configuration parameters,
556 @file{config.omk} can also be used as a common place to store some
557 global settings that applies to the whole project, e.g. the compiler to
558 use or common compiler flags.
560 @subsection Specifying Configuration Parameters
562 To specify names and default values of configuration parameters use the
563 @code{default_CONFIG} variable in @file{Makefile.omk}.
565 @defvar default_CONFIG
566 This variable contains a list of configuration parameters and their
567 default values. The format of every item in this list is
568 @var{CONFIG_xxxx}=@var{value}. You can name the parameter as you want,
569 but it is good practice to start the name with @samp{CONFIG_} prefix.
571 OMK can automatically generate header files, with C preprocessor macro
572 definitions according to the OMK's configuration parameters. The
573 actual content of generated header files depends on the form of the
574 @var{value}. The possible forms are:
577 @item @samp{y}, @samp{n} or @samp{x}
578 This defines boolean parameters. If the value of the parameter is
579 @samp{y}, the @samp{#define CONFIG_@var{xxx} 1} is generated, if it is
580 @samp{n}, no @code{#define} is generated.
582 @samp{x} is a special value called @emph{recessive 'n'}. The meaning
583 is that this parameter influences the component in the current
584 directory (i.e. the corresponding @code{#define} will be included in
585 @code{LOCAL_CONFIG_H}; see @ref{LOCAL_CONFIG_H}) but the default value
586 is not specified here. If the default value is not specified anywhere,
587 the behavior is the same as if @samp{n} is specified.
589 Numeric parameters. The define looks like @samp{#define CONFIG_@var{xxx} @var{number}}
591 Text without quotes. The define looks like @samp{#define CONFIG_@var{xxx} @var{text}}
593 Text with quotes. The define looks like @samp{#define CONFIG_@var{xxx} "@var{text}"}
597 @noindent Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
599 @verbatiminclude ../tests/config/default/Makefile.omk
601 @noindent and @file{subdir/Makefile.omk} like:
603 @verbatiminclude ../tests/config/default/subdir/Makefile.omk
606 @noindent After running @command{make default-config}, the content of
607 @file{config.omk-default} will be:
609 @verbatiminclude ../tests/config/default/config.omk-correct
612 @subsection Using Configuration Parameters
614 Configuration parameters can be used in two ways:
617 as variables in @file{Makefile.omk} and
619 as C/C++ preprocessor macros in OMK generated header files.
622 @noindent For the first use, your @file{Makefile.omk} may contain something like:
624 SUBDIRS = arch/$(CONFIG_ARCH)
626 ifeq ($(CONFIG_DEBUG),y)
627 DEFS += -DUSE_SIMULATOR
631 @noindent For the second use, there are several variables that control
632 the generation of header files with configuration values. These
633 variables are described here:
635 @anchor{LOCAL_CONFIG_H}
636 @defvar LOCAL_CONFIG_H
637 The value of this variable is the name of a header file, which will
638 contain all configuration parameters declared in the current directory
639 by @code{default_CONFIG}. This header file is accessible only by files
640 in the current directory and it should be included like @code{#include
643 In @file{Makefile.omk}, the use of this variable can look like this:
646 LOCAL_CONFIG_H = myconfig.h
650 @defvar config_include_HEADERS
651 This variable is similar to @code{LOCAL_CONFIG_H}. One difference is
652 that the generated header file is accessible to all sub-projects in
653 all directories, not only to the files in the same directory (the
654 header is stored in @file{_compiled} tree). The second difference is
655 that you have to specify, which configuration parameters you want to
656 appear in the header file.
660 This variable determines the configuration parameters that should be
661 stored in a header file specified by
662 @code{config_include_HEADERS}. The @var{xxx} in the name of this
663 variable needs to be the same as the base name (without extension) of
667 @noindent Example of using @code{config_include_HEADERS}:
669 default_CONFIG = CONFIG_LINCAN=y CONFIG_LINCANRTL=n CONFIG_LINCANVME=n
670 config_include_HEADERS = global.h
671 global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL
674 @noindent Here, we include only two out of the three configuration
675 parameters defined in the current @file{Makefile.omk}. It is also
676 possible to include configuration parameters defined in a different
679 @subsection Common Variables
681 It is common practice to use @file{config.omk} to store project-wide
682 settings. Here is the list of variables, which are commonly set here
683 (but they can also be set elsewhere, e.g. in @file{Makefile.omk}).
685 You can easily ``reconfigure'' your project by changing the
686 @file{config.omk} file. It is useful to have several configurations
687 stored in different files and let @file{config.omk} be a symbolic link
688 to the desired configuration.
692 The name of C compiler.
694 Command line options for C compiler.
696 The name of C++ compiler.
698 Additional parameters (besides @code{CFLAGS}) to by passed to C++
702 @node Advanced OMK Features, Running OMK under Windows OS, Configuration and Conditional Compilation, OMK User's Manual
703 @section Advanced OMK Features
705 In this section we list several OMK features, which are more complicated
706 or rarely used so they were omitted in previous sections.
710 The @file{_compiled} directory can be shared between multiple projects
711 (by using symbolic links).
714 If you work on a bigger project, you usually don't need to rebuild the
715 whole project and call @command{make} only in a
716 subdirectory. Sometimes, it might be useful to rebuild the whole
717 project. You can either change working directory to the root of your
718 project and call @command{make} there or, as a shortcut, you can use
719 @code{W} variable (see @ref{W}) to compile everything directly from a
726 Searching for @file{Makefile.rules} works such way, that if you get
727 into sources directory over symbolic links, OMK is able to unwind your
728 steps back. This implies you can make links to component directories
729 on read-only media, copy @file{Makefile.rules}, @file{Makefile} and
730 top-level @file{Makefile.omk}, adjust @file{Makefile.omk} to contain
731 only required components and then call @command{make} in the top
732 directory or even in read-only directories after changing working
733 directory from your tree to readonly media.
739 If this variable equals to @samp{1}, the @b{whole} project is
740 (re)compiled, even if @command{make} is called from a subdirectory.
746 @node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Advanced OMK Features, OMK User's Manual
747 @section Running OMK under Windows OS
749 @node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, OMK User's Manual
750 @section Interfacing OMK to popular IDEs
754 KDevelop has support for custom build systems. To use KDevelop to
755 develop projects using OMK follow these steps. These steps are valid for
756 version 3.5.0 of KDevelop, but for previous versions it doesn't differ
761 Import project to KDevelop (from menu choose @emph{Project---Import
762 existing project}). Select the type of project to @emph{Generic C
763 Application (Custom Buildsystem)}.
769 Then answer to following dialogs as you want.
774 @image{kdevelop3} @image{kdevelop4}
778 If you are working only on some small part of the bigger project, you
779 usually don't want to recompile the whole project every time. In
780 @emph{Project---Project Options}, you can specify the subdirectory where to
787 If you want to switch between several configurations easily (see also
788 @ref{Configuration and Conditional Compilation}), in the same dialog
789 you can add @option{-e} to make options. This makes environment variables
790 have higher precedence than those in @file{config.omk-default}. Then,
791 you can define several environments with different
792 @code{CONFIG_@var{xxx}} variables and their values.
798 You can easily switch the configurations from @emph{Build---Make
808 @subsection Emacs, VIM, etc.
810 Since OMK compilation is started by executing @command{make} command,
811 many common editors can work easily with OMK.
813 Under Emacs, you can use @command{compile} or @command{recompile}
814 commands as you are used to do.
816 @node Troubleshooting, , Interfacing OMK to popular IDEs, OMK User's Manual
817 @section Troubleshooting
819 Renaming of some file => dependency problems.
821 Manual compilation ... V=1
823 @node Original README, OMK Development, OMK User's Manual, Top
824 @chapter Original README
826 Since this manual still doesn't cover all aspects of OMK, we include
827 here a @file{README.rules} file, which was written for the first version
830 @b{Important notice:} This make system uses features found in recent
831 versions of GNU Make program. If you encounter problems with package
832 building, check, that you use correct version of Make program. The
833 Make older than version 3.80, could not be used. Even Make version
834 3.80 has annoying bug which causes building fail with misleading
835 message "virtual memory exhausted". Please, upgrade at least to
836 version 3.81 of GNU Make.
838 There is list of features which we want to solve with our make system:
841 Central @file{Makefile.rules} for most of components of a bigger project.
843 FIXME (our CAN framework includes more libraries common with our other
844 projects, we need to separate some utility libraries etc.)
846 The rules in more spread Makefiles are way to the hell (update for
847 different kernel, RT-Linux etc would be nightmare in other case).
849 Make system should allow to freely move cross-dependant components in
850 directory structure without need to update users of moved component (I
851 hate somethink like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
852 example. If a component is renamed or version is added to then name,
853 all Makefiles in CAN will require update).
855 Make system should be able to compile mutually cross-dependant
856 libraries and should ensure, that change in one component sources or
857 headers would result in relink or rebuild in components linked against
858 that library or including modified header file.
860 Make system has to enable compilation out of OCERA full source tree
861 (we would lost many users of particular components in other case).
863 Compile should be able to do all above work without need to install
864 any files before successful finish of build.
866 Because we use some libraries for RT-Linux build and user-space build,
867 we need to solve how to compile from same sources to both targets.
869 The build system should allow to call make for particular source
870 subdirectory. Time of recursive make through all subdirectories is
873 Make system should enable to build out of sources tree (else clean or
874 working with CVS sandbox gets fussy and simultaneous multiple targets
877 It would be good, if there is a possibility to call make from
878 read-only media sources.
880 Make system should store results of build in some separate directory
881 structure to simple install and testing.
883 Makefiles in sources directories should be simple.
886 There is probably only one alternative fully supporting above requirements
887 and it is GNU Autoheader...Automake...Autoconf... system.
888 But it is complicated and requires big amount of support files.
889 It would be acceptable if it could be easily used for OCERA framework.
890 But there are important show stoppers for that system:
893 It would require deep revision of all OCERA CVS contents and agreement
894 on this would be problematic
896 This system is not well prepared for dual compilation for Linux and
897 RT-Linux sub-targets. It would mean many changes in default autoconf
898 setup to support this. Probably simplest way would be to rebuild GCC
899 tool chain for something like i586-elf-rtlinux. This would require
900 even more space for OCERA development.
903 The problem calls for some solution, which would have minimal impact
904 on other components and would be elegant and would be maintainable
905 and small, because our main goal is components development and not
906 make systems development.
908 There is result of our trial. It is OMK make system.
909 The @file{Makefile} and @file{Makefile.omk} files should be in all source
910 directories. Common @file{Makefile.rules} file is required in the toplevel
911 sources directory. Alternatively this file could be moved
912 to link tree pointing into readonly media or can be anywhere
913 else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
915 @c !!! tohle tam nejak zmizelo, mozna by to chtelo skontrolovat, ze to
916 @c sedi s aktualnim stavem
919 Syntax of Makefile.omk files is for usual cases compatible
920 to Automake's Makefile.am descriptions. There are specific targets
921 for RT-Linux and Linux kernel related stuff
923 Makefile.omk user defined variables
926 list of subdirectories intended for make from actual directory
928 list of the user-space libraries
929 @item shared_LIBRARIES
930 list of the user-space shared libraries
931 @item kernel_LIBRARIES
932 list of the kernel-space libraries
933 @item rtlinux_LIBRARIES
934 list of the RT-Linux kernel-space libraries
935 @item include_HEADERS
936 list of the user-space header files
937 @item nobase_include_HEADERS
938 headers copied even with directory part
940 list of the kernel-space header files
941 @item rtlinux_HEADERS
942 list of the RT-Linux kernel-space header files
944 list of the require binary programs
946 list of the development utility programs
948 list of the kernel side modules/applications
949 @item rtlinux_MODULES
950 list of RT-Linux the kernel side modules/applications
952 list of specific target sources
954 additional include directories and defines for user-space
955 @item kernel_INCLUDES
956 additional include directories and defines for kernel-space
957 @item rtlinux_INCLUDES
958 additional include directories and defines for RT-Linux
960 list of default config assignments CONFIG_XXX=y/n ...
963 The Makefile is same for all sources directories and is only 14 lines
964 long. It is there only for convenience reasons to enable call "make"
965 from local directory. It contains code which locates
966 @file{Makefile.rules} in actual or any parent directory. With standard
967 BASH environment it works such way, that if you get into sources
968 directory over symbolic links, it is able to unwind yours steps back
969 => you can make links to readonly media component directories, copy
970 @file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
971 Makefile.omk to contain only required components and then call make in
972 top or even directories after crossing from your tree to readonly
975 The system compiles all files out of source directories. The actual
976 version of system is adapted even for OCERA tree mode if
977 @code{OCERA_DIR} variable is defined in @file{Makefile.rules}
979 There are next predefined directory name components, which can be
983 @item BUILD_DIR_NAME = _build
984 prefix of directory, where temporary build files are stored
985 @item COMPILED_DIR_NAME = _compiled
986 prefix of directory, where final compilation results are stored
987 @item GROUP_DIR_NAME = yyy
988 this is used for separation of build sub-trees in OCERA environment
989 where more @file{Makefile.rules} is spread in the tree
992 Next directories are used:
995 @item KERN_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
996 directory to store intermediate files for kernel-space targets
997 @item USER_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
998 directory to store intermediate files for user-space targets
1000 @item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
1001 directory to store exported include files which should be installed later
1002 on user-space include path
1003 @item USER_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
1004 same for user-pace libraries
1005 @item USER_UTILS_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
1006 utilities for testing, which would not probably be installed
1007 @item USER_BIN_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
1008 binaries, which should go into directory on standard system PATH
1009 (/usr/local/bin, /usr/bin or $(prefix)/bin)
1011 @item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
1012 directory to store exported include files which should be installed later
1013 on kernel-space include path
1014 @item KERN_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
1015 same for kernel-pace libraries
1016 @item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
1017 builded modules for Linux kernel or RT-Linux system
1020 There is more recursive passes through directories to enable
1021 mutual dependant libraries and binaries to compile.
1022 Next passes are defined
1025 @item default-config
1026 generates @file{config.omk-default} or xxx-default (FIXME) configuration file
1028 checks and creates required build directories
1030 copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
1032 builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
1034 @item binary-pass and utils-pass
1035 links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
1036 object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
1037 @item kernel-lib-pass
1038 builds libraries for kernel space targets
1040 builds kernel modules
1043 The amount of passes is relatively high and consumes some time. But
1044 only other way to support all required features is to assemble one big
1045 toplevel Makefile, which would contain all components and targets
1048 Drawbacks of designed make system
1051 the system is not as fast as we would like
1053 it lacks Autoconf and configure extensive support for many systems
1054 from UNIX to DOS and WINDOWS
1056 it does not contain support for checking existence of target
1057 libraries and functionalities as GNU Autoconf
1059 it is heavily dependant on GNU MAKE program. But it would not be big
1060 problem, because even many commercial applications distribute GNU MAKE
1061 with them to be able to work in non-friendly systems
1063 the key drawback is dependence on recent MAKE version 3.80 and better
1064 and even version 3.80 of MAKE has important bug, which has been
1065 corrected in newer sources (FIXME)
1068 The last point is critical. I have not noticed it first, because
1069 I use Slackware-9.2 and it contains latest released version
1070 of MAKE (version 3.80).
1071 The problem appears when I have tried to build bigger libraries.
1072 There is bug in version 3.80, which results in misleading
1073 error "Virtual memory exhausted". It is known bug with ID 1517
1076 * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
1080 I have optimized some rules to not push memory to the edge,
1081 but there could be still issues with 3.80 version.
1083 I have downloaded latest MAKE CVS sources. The compilation required
1084 separate lookup and download for .po files and full Autoheader... cycle.
1085 I have put together package similar to release. Only ./configure --prefix=...
1086 and make is required. CVS sources contains version 3.81beta1.
1087 You can download prepared sources archive from
1088 @indicateurl{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
1089 Or you can get our local copy from
1090 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
1092 The archive contains even "make" binary build by me, which should work
1093 on other Linux distributions as well. Older version of MAKE (3.79.x
1094 released about year 2000) found on Mandrake and RedHat are not
1095 sufficient and do not support eval feature. I do not expect, that
1096 Debian would be more up-to-date or contain fixes to MAKE vm exhausted
1099 The local CTU archive with our CAN components prepared for inclusion
1100 into OCERA SF CVS could be found in my "can" directory
1102 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
1104 The code should build for user-space with new make on most of Linux distros
1105 when make is updated.
1107 If you want to test compile for RT-Linux targets, line
1110 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
1113 in @file{Makefile.rules} has to be activated and updated
1114 to point RT-Linux directory containing "rtl.mk".
1115 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
1116 (@file{can/utils/ulut/ul_rtlchk.c}).
1118 The next line, if enabled, controls compilation in OCERA project tree
1121 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
1124 The LinCAN driver has been updated to compile out of source directories.
1126 Please, check, if you could compile CAN package and help us with integration
1127 into OCERA SF CVS. Send your comments and objections.
1129 The OMK system has been adapted to support actual OCERA configuration process.
1130 I am not happy with ocera.mk mix of defines and poor two or three rules,
1131 but OMK is able to overcome that.
1133 The OMK system has integrated rules (default-config) to build default
1134 configuration file. The file is named @file{config.omk-default} for
1135 the stand-alone compilation. The name corresponds to OCERA config +
1136 "-default" if OCERA_DIR is defined. This file contains statements
1137 from all @code{default_CONFIG} lines in all @file{Makefile.omk}. The
1138 file should be used for building of own @file{config.omk} file, or as
1139 list for all options if Kconfig is used.
1141 @c @chapter OMK Reference
1143 @node OMK Development, Variable Index, Original README, Top
1144 @chapter OMK Development
1148 @node Variable Index, , OMK Development, Top
1149 @unnumbered Variable Index
1153 @c @node Concept Index, , Variable Index, Top
1154 @c @unnumbered Concept Index