1 \input texinfo @c -*-texinfo-*-
3 @setfilename omk-manual
4 @documentencoding UTF-8
5 @settitle OMK: Ocera Make System
9 Manual for Ocera Make System (OMK) version
12 Copyright @copyright{} 2007, 2008, 2009, 2010, 2011, 2013 Michal Sojka, Pavel Pisa
16 @title Ocera Make System Manual
18 @vskip 0pt plus 1filll
25 @node Top, Overview, (dir), (dir)
26 @top Ocera Make System
40 @node Overview, User's Manual, Top, Top
44 OMK is an advanced make system written entirely in GNU make. Compiling
45 software using OMK requires only GNU Make and standard UNIX
46 utilities (@command{sh}, @command{sed}, @command{cmp}, ...)
47 installed. OMK aims to be developer friendly; to use OMK, you do not
48 need to understand (sometimes) cryptic syntax of Makefiles.
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, Overview
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
118 @node Quick Start, History, Why to Use OMK?, Overview
121 If you get some sources, which are distributed with OMK, usually the
122 following commands are sufficient to compile the whole project.
131 @noindent To use OMK in your own project, follow these steps:
135 The newest version of OMK can be found at @uref{http://rtime.felk.cvut.cz/omk/}.
137 Take appropriate @file{Makefile.rules} (see @ref{Properties of Specific Makefile.rules}), put it together with leaf @file{Makefile}
138 to the root directory of your project.
140 Create @file{Makefile.omk} files in all directories you want to
141 compile something. Please refer to @ref{User's Manual} to learn
142 what to write in @file{Makefile.omk} files.
144 Run @command{make omkize} in the root directory.
147 @noindent Your project is now ready to compile.
150 @node History, , Quick Start, Overview
153 OMK was originally written by Pavel Píša as a solution to have one
154 common make system for OCERA project, where we needed to compile
155 user-space programs, Linux kernel modules and RT Linux modules in one
156 package. Although this system was not accepted for the whole OCERA
157 project. Several individual developers (mostly from Czech Technical
158 University) liked it and started to use it.
160 As a number of projects using OMK grew it was necessary to modularize
161 the make system to support more ``targets''. Michal Sojka took care
162 about the process of modularization.
164 @node User's Manual, Original README, Overview, Top
165 @chapter User's Manual
170 * Compiling Programs::
171 * Compiling Libraries::
173 * Recursing into Subdirectories::
174 * Dependency Tracking::
175 * Configuration and Conditional Compilation::
176 * Advanced OMK Features::
177 * Properties of Specific Makefile.rules::
178 * Running OMK under Windows OS::
179 * Interfacing OMK to popular IDEs::
183 @node Basic Concepts, Invoking OMK, User's Manual, User's Manual
184 @section Basic Concepts
186 The main concept of OMK is very simple. In the heart of OMK are two
187 files @file{Makefile.rules} and @file{Makefile.omk}. The former one
188 resides in project root directory and contains all compilation rules
189 needed for compilation of the particular project. There are different
190 @file{Makefile.rules} for different platforms (Unix, RTEMS, system-less,
191 ...). @file{Makefile.omk} is stored in every (sub)directory and
192 describes what should @command{make} perform in that directory (e.g.
193 compile a program from several source files). It uses declarative syntax
194 (assign values to variables) similar to Automake files
195 @file{Makefile.am}. The content of @file{Makefile.omk} is described in
196 the following sections.
198 Since @command{make} searches by default for a @file{Makefile} and not
199 for @file{Makefile.rules} or @file{Makefile.omk}, there
200 must@footnote{When USE_LEAF_MAKEFILES is set to @samp{n}, this
201 @file{Makefile} can be omitted in subdirectories.
202 @xref{USE_LEAF_MAKEFILES}.} be a small generic @file{Makefile} in every
203 directory, whose task is only to find @file{Makefile.rules} in the
204 actual or any parent directory and include it. This search is performed
205 only once at the beginning of compilation.
207 @c TODO: Pavel's note about qmake.
210 The compilation process itself is comprised of several @emph{passes}. Every
211 pass traverses the whole directory structure@footnote{In future, we are
212 planning some optimization that allows OMK to traverse the directories
213 only once and thus decrease compilation time.} and does a particular
214 task in every directory of the project. Typically, these passes are:
216 @anchor{include-pass}
218 This pass takes all include files marked for ``export'' and copies
219 (or links) them to the @file{include} directory under
220 @file{_compiled} directory. @xref{Header Files}.
222 Also, during this pass, automatically generated header file are
223 generated according to the current
224 configuration. @xref{Configuration and Conditional Compilation}.
226 During this pass, all include files are in place, so all libraries
229 Finally, programs can be compiled and linked against libraries
230 created in the previous pass.
233 The results of compilation are stored under the @file{_compiled}
234 directory. This directory is structured as a classical Unix file-system
235 (it contains directories like @file{bin}, @file{lib} and @file{include})
236 and can be directly copied to the target device or to some directory on
237 a host computer (e.g. @file{/usr/local}).
239 Besides @file{_compiled} directory, there in a @file{_build}
240 directory. Under this directory are stored some temporary files and
241 intermediate compilation products (object files, dependency files etc.).
243 In the next section, we provide an overview of methods, how to invoke
244 OMK from command line. Section @ref{Interfacing OMK to popular IDEs}
245 covers running of OMK from popular IDEs.
247 Sections @ref{Compiling Programs} through @ref{Configuration and
248 Conditional Compilation} deals with the content of
249 @file{Makefile.omk}. Its syntax in usual cases compatible to GNU
250 Automake's @file{Makefile.am} syntax. Also, the scheme for naming
251 variables was inspired by Automake so most OMK variables have the name
252 like @samp{@var{target}_@var{TYPE}}.
254 @node Invoking OMK, Compiling Programs, Basic Concepts, User's Manual
255 @section Invoking OMK
257 Before using OMK for the first time, you have to call:
259 @command{make default-config}
261 @noindent See @ref{Configuration and Conditional Compilation} for
262 details. If you forget to do this, OMK will notice you.
264 To compile the whole project or only some subtree of the project, call
268 @noindent in the appropriate directory.
270 To clean files in @file{_build} directory but not in @file{_compiled}
276 To clean the compilation completely, you can either remove
277 @file{_compiled} and @file{_build} directories manually, or call
279 @command{make distclean}
281 @noindent which does the same. This command removes these directories
282 even if you call it from a subdirectory.
284 To debug compilation problems, you can use @code{V} variable (see
290 You can also set values of some other variables on command line for
291 temporary change something. The example below compiles the code
292 temporarily with debugging information:
294 @command{make CFLAGS="-g -O0 -Wall"}
297 If your project uses an alternative make-system (e.g. Automake or custom
298 makefiles), it might be useful for you to use the command:
300 @command{make omkize}
302 @noindent This will find all @file{Makefile.omk} files in all subdirectories
303 and copies generic @file{Makefile} from the root directory to that
304 subdirectories. This way you can easily switch your project to use OMK.
310 If this variable equals to @samp{1}, the whole command lines for all
311 executed commands are displayed. When not set or zero, only short
312 messages are printed. Value of @samp{2} displays the whole command lines
313 as with @samp{1} and in addition directory navigation messages are
317 @node Compiling Programs, Compiling Libraries, Invoking OMK, User's Manual
318 @section Compiling Programs
320 To tell OMK to compile a program, you need to set some variables in
321 @file{Makefile.omk} (usually) in the directory where program sources are
324 In the example bellow program @command{test} will be compiled from
325 source @file{test.c}.
328 @verbatiminclude tests/programs/compile-a-single-source-c-program/Makefile.omk
331 @noindent The variables are:
333 @anchor{bin_PROGRAMS}
335 Contains a list of names (whitespace separated) of programs to be
336 compiled in this directory.
339 @anchor{test_PROGRAMS}
340 @defvar test_PROGRAMS
341 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
342 stored in @file{bin-tests} directory instead of @file{bin}. This
343 variable is intended for various test programs not to be mixed with
347 @defvar utils_PROGRAMS
348 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
349 stored in @file{bin-utils} directory instead of @file{bin}. This
350 variable is intended for various development utilities not to be mixed
351 with the final product.
355 For every program name @var{xxx} in @code{bin_PROGRAMS},
356 @code{test_PROGRAMS} or @code{utils_PROGRAMS}, this variable contains
357 a list of sources that are needed to compile the program. OMK uses an
358 extension of the filename to determine the compiler to compile this
363 This variable contains a list of libraries the program @var{xxx} will
372 CFLAGS specific for the compiler program. If this variable is set, its
373 value efectively overrides the value of OMK_CFLAGS variable.
377 CXXFLAGS specific for the compiler program. If this variable is set, its
378 value efectively overrides the value of OMK_CXXFLAGS variable.
382 CPPFLAGS specific for the compiler program. If this variable is set, its
383 value efectively overrides the value of OMK_CPPFLAGS variable.
386 @defvar xxx_GEN_SOURCES
387 Program sources generated (by other rules) in the build directory. See
388 the following example.
389 @verbatiminclude tests/programs/generated-sources/Makefile.omk
393 @defvar lib_LOADLIBES
394 This variable contains a list of libraries which needs to be linked to
395 to all programs or shared libraries in this directory.
399 This variable contains a list linker switches to load additional
400 libraries. You usually specify here -L and -l switches.
402 Note: The value of this variable is not used used by OMK for any purpose
403 other than linker invocation. Therefore dependency handling of shared
404 libraries does not work if the library is specified in LOADLIBES
405 instead of lib_LOADLIBES.
408 @node Compiling Libraries, Compiler Flags, Compiling Programs, User's Manual
409 @section Compiling Libraries
412 With OMK, you can easily create statically or dynamically linked
413 libraries. The way of creating libraries is very similar to how programs
414 are created. @xref{Compiling Programs}.
416 In @file{Makefile.omk}, you specify several variables, which defines how
417 the libraries should be compiled. In the example below the library
418 @samp{mylib} (full filename will be @file{libmylib.a}) is created from
419 two sources @file{funca.c} and @file{funcb.c}. Interface of this library
420 is defined in @file{myfunc.h}. Therefore, we export this header for use
424 @verbatiminclude tests/libraries/static-library/Makefile.omk
427 @noindent Variables for use with libraries are:
429 @defvar lib_LIBRARIES
430 Specifies a list of statically linked libraries to be compiled. OMK
431 automatically prepends @code{lib} prefix library names.
434 @defvar shared_LIBRARIES
435 Specifies a list of dynamically linked libraries to be compiled.
439 For every library name @var{xxx} in @code{lib_LIBRARIES} or
440 @code{shared_LIBRARIES}, this variable contains a list of sources that
441 are needed to compile the library. OMK uses an extension of the
442 filename to determine the compiler to compile this source.
449 @node Header Files, , Compiling Libraries, Compiling Libraries
450 @subsection Header Files
452 C and C++ libraries are not very useful without header files. OMK
453 provides several variables that control operations with header files.
455 During compilation, header files are copied (or linked by symbolic
456 links) from source directories to the @file{_compiled} tree (see
457 @ref{include-pass}). Libraries and programs are then compiled against
458 these copies. The following variables control which headers are copied
459 and what is their destination file name.
461 @anchor{include_HEADERS}
462 @defvar include_HEADERS
463 Specifies the list of header files to be exported for use by other
464 libraries/programs. The files are exported directly to the
465 @file{include} directory even if the file is located in a subdirectory
466 (like @file{sci_regs.h} in the example below)
469 include_HEADERS = regs.h periph/sci_regs.h
473 @defvar nobase_include_HEADERS
474 Similar to @ref{include_HEADERS}, but the directory prefix is always
475 kept. To include the file exported by this variable, use
476 @code{#include <@var{prefix}/@var{header.h}>}.
479 @defvar renamed_include_HEADERS
480 Exports the header files under different name. The form of the items
481 in this whitespace separated list is: @var{real name}@code{->}@var{new
485 renamed_include_HEADERS = orte_config_omk_win32.h->orte_config.h
490 If this variable equals to @samp{y}, symbolic links to headers in
491 source directories are used in @file{_compiled} tree instead of
494 Normally, the header files are copied into @file{_compiled} directory
495 to be prepared for transfer into target location afterwards. Copying
496 ensures that resulting libraries are in correspondence with the header
497 files even if the header is changed by a developer but the library is
500 @c Another reason for having single include directory for the whole
501 @c project is tat every component knows where to find header files of
504 On the other side, the copying could make problems during
505 development. Most @acronym{IDE}s, allows you to jump directly to the
506 place, where an error is reported by the compiler. If the error is in
507 a header file, IDE opens you the copy of the header file. If you
508 correct the error there, after the next compilation, your header file
509 will be overwritten by the old version from your source tree.
511 This option is not typically used in @file{Makefile.omk}, but in the
512 top level configuration file @file{config.omk} or on command line.
515 @node Compiler Flags, Recursing into Subdirectories, Compiling Libraries, User's Manual
516 @section Compiler Flags
518 OMK follows the same philosophy for flag variables as does Automake. The
519 variables with OMK_ prefix (e.g. OMK_CPPFLAGS) are supposed to be used by
520 the package developer and variable without that prefix (e.g. CPPFLAGS)
521 are reserved for the user. The following
524 Preprocessor switches.
533 Directives passed to the C or C++ compiler with additional directories
534 to be searched for header files. In most cases you need to specify an
535 absolute path. To specify a directory relative to the source
536 directory, you can use the @code{$(SOURCES_DIR)} variable, which
537 refers to the directory, where @file{Makefile.omk} is located. This
538 variable applies to all compilations invoked in the current directory.
541 INCLUDES = -I$(SOURCES_DIR)/my_include_dir
546 Directives passed to the C or C++ compiler with preprocessor macro
547 definitions. This variable applies to all compilations invoked in the
555 @c FIXME: INCLUDES variable should not be set by rtlinux rules.
557 @node Recursing into Subdirectories, Dependency Tracking, Compiler Flags, User's Manual
558 @section Recursing into Subdirectories
560 OMK is probably most useful in projects consisting of multiple
561 directories. For such projects, it is not easy to write from scratch
562 classic Makefiles that provides all the needed features.
564 You can instruct OMK to descend to a (sub)directory by setting the
565 @code{SUBDIRS} variable in @file{Makefile.omk}.
569 This variable contains a list of directories, in which compilation
570 must be also invoked. Usually, names of subdirectories are used, but
571 you can use any path specification here.
573 Compilation is invoked in these directories before it is invoked in
574 the current directory.
576 See also @ref{AUTOMATIC_SUBDIRS}.
578 @c TODO: Write tests for this.
580 @anchor{ALL_OMK_SUBDIRS}
581 @defvar ALL_OMK_SUBDIRS
582 This variable is set by OMK and can be used as the value of
583 @code{SUBDIRS} variable. It contains a list of all direct
584 subdirectories, which contain @file{Makefile.omk}. This is especially
585 useful if you are combining several projects or components
586 together. In the root directory of your project, you just create
587 symbolic links the components from other projects and all the linked
588 directories automatically appears as the value of this variable.
591 SUBDIRS = $(ALL_OMK_SUBDIRS)
595 @anchor{AUTOMATIC_SUBDIRS}
596 @defvar AUTOMATIC_SUBDIRS
597 If this variable is set to @samp{y} and @code{SUBDIRS} is not assigned
598 in @file{Makefile.omk}, then @code{SUBDIRS} is assigned a default
599 value @code{$(ALL_OMK_SUBDIRS)}.
602 @node Dependency Tracking, Configuration and Conditional Compilation, Recursing into Subdirectories, User's Manual
603 @section Dependency Tracking
605 OMK automatically tracks dependencies of files in the project.
606 Dependencies of object files are produced with gcc's @option{-M@var{x}}
607 options. This means that whenever a header file is changed, OMK
608 recompiles only those files, which included that file.
610 Dependencies are also maintained for libraries and binaries. To find the
611 dependencies, OMK parses linker map files, so a change to some library
612 causes relinking of all programs using that library.
614 @node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, User's Manual
615 @section Configuration and Conditional Compilation
617 In many projects, it is necessary to configure the compilation process. By
618 this configuring we mean, setting some parameters that influence the
619 output of compilation process. In GNU projects, @command{configure}
620 script is usually responsible for configuration. User provides some
621 parameters to @command{configure}, which is run before compilation, and
622 this script does all steps needed to configure the sources and
623 make-system in the desired way.
625 OMK has its own configuration mechanism, which is described in this
626 section. For future releases, we plan that this mechanism can make use
627 of GNU Autoconf, but currently there is no directly integrated support
630 There exist three different configuration files
631 @file{config.omk-default}, @file{config.target} and
632 @file{config.omk}. All of these have to be stored in the same directory
633 as @file{Makefile.rules}. During compilation, these files are included
634 in @file{Makefile.rules} in this order which means that variables
635 assigned in the former files are overridden by those from later
636 ones. All settings specified here apply to the whole compilation
637 tree. Each file is intended for a different kind of configuration
640 @item config.omk-default
641 Stores default configuration of compiled components. This file is
642 automatically generated (see below) and should not be edited by users.
644 Stores default configuration for a project or target hardware. This
645 file is intended to be stored in a version control system and should
646 be modified only by the maintainer of the project.
648 For cross compiled projects, this file typically contains settings of
649 variables like @var{CC} and @var{CFLAGS}.
651 This is a file for end users, where any default settings set in the
652 above files can be overridden. This file should not be stored in
653 version control system. The project should compile without having this
657 Besides variables defined in @file{config.target}, @file{Makefile.omk}
658 in any subdirectory can specify some configuration parameters. When
659 @command{make default-config} is run, all these parameters are found and
660 together with their default values are stored as makefile variables in
661 @file{config.omk-default}. This file is included during compilation, so
662 if you don't specify other values, these defaults are used. If you are
663 not satisfied with these defaults, you can override the values of
664 parameters either locally for your build in @file{config.omk} or
665 globally for all people working with the project in
666 @file{config.target}.
669 * Specifying Configuration Parameters::
670 * Using Configuration Parameters::
674 @node Specifying Configuration Parameters, Using Configuration Parameters, Configuration and Conditional Compilation, Configuration and Conditional Compilation
675 @subsection Specifying Configuration Parameters
677 To specify names and default values of configuration parameters use the
678 @code{default_CONFIG} variable in @file{Makefile.omk}.
680 @defvar default_CONFIG
681 This variable contains a list of configuration parameters and their
682 default values. The format of every item in this list is
683 @var{CONFIG_xxxx}=@var{value}. You can name the parameter as you want,
684 but it is good practice to start the name with @samp{CONFIG_} prefix.
686 OMK can automatically generate header files, with C preprocessor macro
687 definitions according to the OMK's configuration parameters. The
688 actual content of generated header files depends on the form of the
689 @var{value}. The possible forms are:
692 @item @samp{y}, @samp{n} or @samp{x}
693 This defines boolean parameters. If the value of the parameter is
694 @samp{y}, the @samp{#define CONFIG_@var{xxx} 1} is generated, if it is
695 @samp{n}, no @code{#define} is generated.
697 @samp{x} is a special value called @emph{recessive 'n'}. The meaning
698 is that this parameter influences the component in the current
699 directory (i.e. the corresponding @code{#define} will be included in
700 @code{LOCAL_CONFIG_H}; see @ref{LOCAL_CONFIG_H}) but the default value
701 is not specified here. If the default value is not specified anywhere,
702 the behavior is the same as if @samp{n} is specified.
704 Numeric parameters. The define looks like @samp{#define CONFIG_@var{xxx} @var{number}}
706 Text without quotes. The define looks like @samp{#define CONFIG_@var{xxx} @var{text}}
708 Text with quotes. The define looks like @samp{#define CONFIG_@var{xxx} "@var{text}"}
712 @noindent Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
714 @verbatiminclude tests/default-config/Makefile.omk
716 @noindent and @file{subdir/Makefile.omk} like:
718 @verbatiminclude tests/default-config/subdir/Makefile.omk
721 @noindent After running @command{make default-config}, the content of
722 @file{config.omk-default} will be:
724 @verbatiminclude tests/default-config/config.omk-correct
727 @node Using Configuration Parameters, Common Variables, Specifying Configuration Parameters, Configuration and Conditional Compilation
728 @subsection Using Configuration Parameters
730 Configuration parameters can be used in two ways:
733 as variables in @file{Makefile.omk} and
735 as C/C++ preprocessor macros in OMK generated header files.
738 @noindent For the first use, your @file{Makefile.omk} may contain something like:
740 SUBDIRS = arch/$(CONFIG_ARCH)
742 ifeq ($(CONFIG_DEBUG),y)
743 DEFS += -DUSE_SIMULATOR
747 @noindent For the second use, there are several variables that control
748 the generation of header files with configuration values. These
749 variables are described here:
751 @anchor{LOCAL_CONFIG_H}
752 @defvar LOCAL_CONFIG_H
753 The value of this variable is the name of a header file, which will
754 contain all configuration parameters declared in the current directory
755 by @code{default_CONFIG}. This header file is accessible only by files
756 in the current directory and it should be included like @code{#include
759 In @file{Makefile.omk}, the use of this variable can look like this:
762 LOCAL_CONFIG_H = myconfig.h
766 @defvar config_include_HEADERS
767 This variable is similar to @code{LOCAL_CONFIG_H}. One difference is
768 that the generated header file is accessible to all sub-projects in
769 all directories, not only to the files in the same directory (the
770 header is stored in @file{_compiled} tree). The second difference is
771 that you have to specify, which configuration parameters you want to
772 appear in the header file.
776 This variable determines the configuration parameters that should be
777 stored in a header file specified by
778 @code{config_include_HEADERS}. The @var{xxx} in the name of this
779 variable needs to be the same as the base name (without extension) of
783 @noindent Example of using @code{config_include_HEADERS}:
785 default_CONFIG = CONFIG_LINCAN=y CONFIG_LINCANRTL=n CONFIG_LINCANVME=n
786 config_include_HEADERS = global.h
787 global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL
790 @noindent Here, we include only two out of the three configuration
791 parameters defined in the current @file{Makefile.omk}. It is also
792 possible to include configuration parameters defined in a different
795 @node Common Variables, , Using Configuration Parameters, Configuration and Conditional Compilation
796 @subsection Common Variables
798 It is common practice to use @file{config.target} or @file{config.omk}
799 to store project-wide settings. Here is the list of variables, which are
800 commonly set here (but they can also be set elsewhere, e.g. in
801 @file{Makefile.omk}).
803 You can easily ``reconfigure'' your project by changing the
804 @file{config.omk} file. It is useful to have several configurations
805 stored in different files and let @file{config.omk} be a symbolic link
806 to the desired configuration.
810 The name of C compiler.
812 Command line options for C compiler.
814 The name of C++ compiler.
816 Additional parameters (besides @code{CFLAGS}) to by passed to C++
820 @node Advanced OMK Features, Properties of Specific Makefile.rules, Configuration and Conditional Compilation, User's Manual
821 @section Advanced OMK Features
823 In this section we list several OMK features, which are more complicated
824 or rarely used so they were omitted in previous sections.
827 * Organization of the Source Tree::
828 * Additional Variables::
829 * Adding Hooks to Passes::
830 * Integration of Wvtest Framework::
833 @node Organization of the Source Tree, Additional Variables, Advanced OMK Features, Advanced OMK Features
834 @subsection Organization of the Source Tree
838 The @file{_compiled} directory can be shared between multiple projects
839 (by using symbolic links).
842 If you work on a bigger project, you usually don't need to rebuild the
843 whole project and call @command{make} only in a
844 subdirectory. Sometimes, it might be useful to rebuild the whole
845 project. You can either change working directory to the root of your
846 project and call @command{make} there or, as a shortcut, you can use
847 @code{W} variable (see @ref{W}) to compile everything directly from a
854 Searching for @file{Makefile.rules} works such way, that if you get
855 into sources directory over symbolic links, OMK is able to unwind your
856 steps back. This implies you can make links to component directories
857 on read-only media, copy @file{Makefile.rules}, @file{Makefile} and
858 top-level @file{Makefile.omk}, adjust @file{Makefile.omk} to contain
859 only required components and then call @command{make} in the top
860 directory or even in read-only directories after changing working
861 directory from your tree to the readonly media.
867 If this variable equals to @samp{1}, the @b{whole} project is
868 (re)compiled, even if @command{make} is called from a subdirectory.
871 @node Additional Variables, Adding Hooks to Passes, Organization of the Source Tree, Advanced OMK Features
872 @subsection Additional Variables
874 @anchor{USE_LEAF_MAKEFILES}
875 @defvar USE_LEAF_MAKEFILES
876 If this variable equals to @samp{n} (default is unset), then OMK uses
877 the leaf @file{Makefile} only when it is invoked by simple
878 @command{make} command. Later, during recursive directory descent leaf
879 @file{Makefile} is not used and @file{Makefile.rules} is included
882 This feature is useful if you are integrating some non-OMK project into
883 your project. You only add @file{Makefile.omk} files to the non-OMK
884 project and don't need to modify project's original Makefiles.
886 This variable can be set either globally in a @file{config.*} file or
887 locally in some @file{Makefile.omk}. In the latter case, it influences
888 only subdirectories of the directory containing @file{Makefile.omk}.
893 This variable is set internally by OMK and its value is the absolute
894 path to the directory with compiled sources. It can be used if you need
895 to refer to sources files in some custom constructs in
899 include_HEADERS = $(notdir $(wildcard $(SOURCES_DIR)/*.h))
905 The same as @ref{SOURCES_DIR}. Provided for Automake compatibility.
908 @defvar{MAKERULES_DIR}
909 This variable is set internally by OMK and its value is the absolute
910 path to the directory containing @file{Makefile.rules} currently used
914 @defvar{OMK_RULES_TYPE}
915 Identification the type of @file{Makefile.rules} used for
916 compilation. Values are like @samp{linux}, @samp{rtems}, @samp{sysless},
917 ... This variable is automatically generated during creation of
918 @file{Makefile.rules} and can be used in configuration files (see
919 @ref{Configuration and Conditional Compilation}) or in
920 @file{Makefile.omk} to tweak compilation for specific targets.
923 @node Adding Hooks to Passes, Integration of Wvtest Framework, Additional Variables, Advanced OMK Features
924 @subsection Adding Hooks to Passes
926 Sometimes it is necessary to run some special commands as a part of
927 compilation. Typical example might be a tool which generates source
928 files on the fly. OMK supports calling additional commands during
929 compilation by so called @emph{pass hooks}. A pass hook is an ordinary
930 make target which is invoked as part of compilation during a particular
931 pass (see @ref{passes}). Pass hooks can be defined by assigning their
932 names to @code{xxx_HOOKS} variable.
935 Specifies one or more hooks (make targets) which are invoked during pass
936 @var{xxx}. The working directory of commands or this target is under the
939 In the example bellow header file @file{generated_header.h} is created
940 during @samp{include-pass} by @file{convert_data} program. The program
941 takes @file{data_file.txt} in the source directory as the input and
942 creates the header file in the in the correct directory under the
946 include-pass_HOOKS = generated_header.h
948 generated_header.h: $(SOURCES_DIR)/data_file.txt
949 convert_data < $^ > $@@
953 @node Integration of Wvtest Framework, , Adding Hooks to Passes, Advanced OMK Features
954 @subsection Integration of Wvtest Framework
956 OMK has integrated support for
957 @uref{https://github.com/apenwarr/wvtest,Wvtest unit testing framework}.
958 It is a very minimalistic framework whose integration with OMK does not
959 impose almost any particular policy of writing the tests. Wvtest tests
960 are specified by the following two variables:
962 @defvar wvtest_PROGRAMS
963 This variable has the same meaning as @ref{test_PROGRAMS} with two
964 exceptions: (1) the program is automatically linked with the library
965 specified by @code{WVTEST_LIBRARY} variable and (2) the program is
966 automatically executed by @command{make wvtest} (see below).
969 @defvar wvtest_SCRIPTS
970 Defines the name of a script (e.g. shell script) which is executed by
971 @command{make wvtest}. Write the scripts so, that they can be run from
972 arbitrary directory, i.e. in the case of shell scripts ensure that the
973 @file{wvtest.sh} library is sourced like this:
975 @code{. $(dirname $0)/wvtest.sh}
979 @defvar WVTEST_LIBRARY
980 Specifies the name of the library that is automatically linked with
981 @code{wvtest_PROGRAMS}. The default is @file{wvtest}.
984 There is also an OMK pass called @code{wvtest-pass} which consecutively
985 runs all @code{wvtest_PROGRAMS} and @code{wvtest_SCRIPTS} in the
986 traversed subdirectories of the current directory. Every program or
987 script is executed in a temporary directory under @file{_build}
988 directory with @code{PATH} variable modified to include
989 @file{_compiled/bin} as the first component and @code{LD_LIBRARY_PATH}
990 modified to include @file{_compiled/lib} as the first component. This
991 allows the tests to run the @code{bin_PROGRAMS} without explicitly
992 specifying their full path and to use shared libraries without the path
995 When make is invoked as @command{make wvtest} it runs @command{make
996 wvtest-pass} under the control of @file{wvtestrun} script, which must be
997 present in the same directory as @file{Makefile.rules}. This script
998 suppresses the normal output of passed tests and prints only their
999 summary. For failed tests, the full output is shown. Additionally, when
1000 the output is written to a terminal, the status of each test is
1001 displayed in color for easy inspection.
1003 @node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, User's Manual
1004 @section Properties of Specific Makefile.rules
1006 In previous sections, general properties of @file{Makefile.rules} were
1007 documented. This section contains documentation to features found only
1008 in some particular @file{Makefile.rules}.
1016 @node Linux, System-Less, Properties of Specific Makefile.rules, Properties of Specific Makefile.rules
1019 This @file{Makefile.rules} is used not only for Linux as the name
1020 suggests, but also for other Unices and even for Windows.
1023 The name of the operating system (OS) where make was invoked.
1027 Should specify the name of OS where the resulting binary should be
1028 used. If not specified manually, it equals to BUILD_OS.
1032 Lists subdirectories with QT project (.pro) file. OMK will generate
1033 there @file{Makefile} by calling @command{qmake} with correct
1034 parameters to interface QT application to the rest of the compilation
1035 tree. Then @command{make} is called there to compile QT
1036 application. Variable @samp{QTDIR} must be set to the directory with
1037 QT installation (e.g. /usr/share/qt4 on Debian).
1041 Lists the names of the files (persumably scripts) to be copied to
1042 @file{_compiled/bin}.
1047 @node System-Less, RTEMS, Linux, Properties of Specific Makefile.rules
1048 @subsection System-Less
1050 This @file{Makefile.rules} is designed for compilation of code for
1051 (small) micro-controllers without operating systems. See
1052 @uref{http://rtime.felk.cvut.cz/hw/index.php/System-Less_Framework} for
1053 more information about our framework, which uses this rules.
1055 @node RTEMS, , System-Less, Properties of Specific Makefile.rules
1061 @node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Properties of Specific Makefile.rules, User's Manual
1062 @section Running OMK under Windows OS
1064 It is possible to use OMK under Windows OS with MinGW (see
1065 @uref{http://www.mingw.org/}). Unfortunately, the compilation speed is
1066 much lower than on UNIX systems.
1068 TODO: Is it necessary to install anything special?
1070 @node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, User's Manual
1071 @section Interfacing OMK to popular IDEs
1079 @node KDevelop, Eclipse/CDT, Interfacing OMK to popular IDEs, Interfacing OMK to popular IDEs
1080 @subsection KDevelop
1082 KDevelop has support for custom build systems. To use KDevelop to
1083 develop projects using OMK follow these steps. These steps are valid for
1084 version 3.5.0 of KDevelop, but for previous versions it doesn't differ
1089 Import project to KDevelop (from menu choose @emph{Project---Import
1090 existing project}). Select the type of project to @emph{Generic C
1091 Application (Custom Buildsystem)}.
1097 Then answer to following dialogs as you want.
1102 @image{kdevelop3} @image{kdevelop4}
1106 If you are working only on some small part of the bigger project, you
1107 usually don't want to recompile the whole project every time. In
1108 @emph{Project---Project Options}, you can specify the subdirectory where to
1115 If you want to switch between several configurations easily (see also
1116 @ref{Configuration and Conditional Compilation}), in the same dialog
1117 you can add @option{-e} to make options. This makes environment variables
1118 have higher precedence than those in @file{config.omk-default}. Then,
1119 you can define several environments with different
1120 @code{CONFIG_@var{xxx}} variables and their values.
1126 You can easily switch the configurations from @emph{Build---Make
1133 @node Eclipse/CDT, Emacs/Vim/etc., KDevelop, Interfacing OMK to popular IDEs
1134 @subsection Eclipse/CDT
1136 @node Emacs/Vim/etc., , Eclipse/CDT, Interfacing OMK to popular IDEs
1137 @subsection Emacs, VIM, etc.
1139 Since OMK compilation is started by executing @command{make} command,
1140 many common editors can work easily with OMK.
1142 Under Emacs, you can use @command{compile} or @command{recompile}
1143 commands as you are used to do.
1145 @node Troubleshooting, , Interfacing OMK to popular IDEs, User's Manual
1146 @section Troubleshooting & Knows Bugs
1150 If you rename some file or directory and then you can't compile your
1151 project, call @command{make clean} in the directory with errors. The
1152 reason for this behavior is that OMK remembers dependencies of every
1153 file. After renaming something, the original name is still stored in
1154 dependencies, but make doesn't know how to create this non-existent
1158 Sometimes, you may want to compile one file the same way as OMK does
1159 it, but run the compilation manually from command line. For example,
1160 you want to debug some preprocessor macros and you only want to
1161 produce preprocessed source instead of an object file.
1163 To compile something manually, you can run OMK by @command{make
1164 V=2}. This will print all commands executed together with directory
1165 navigation messages. Find the command you want to execute manually in
1166 the output. To run it, you need to change the working directory to the
1167 correct one in the @file{_build} tree. The correct directory can be
1168 found in make output on the line @samp{Entering directory} preceding
1169 the desired command.
1172 Currently, C++ sources are supposed to have @file{.cc} or @file{.cxx}
1173 extensions. The @file{.cpp} extension is not supported (yet).
1176 Removing of library source file does not cause the library to be
1177 rebuild. You need to manually delete the library or run @command{make
1178 distclean} before you run @command{make}.
1181 @node Original README, Development, User's Manual, Top
1182 @chapter Original README
1184 Since this manual still doesn't cover all aspects of OMK, we include
1185 here a @file{README.rules} file, which was written for the first version
1188 @b{Important notice:} This make system uses features found in recent
1189 versions of GNU Make program. If you encounter problems with package
1190 building, check, that you use correct version of Make program. The
1191 Make older than version 3.80, could not be used. Even Make version
1192 3.80 has annoying bug which causes building fail with misleading
1193 message "virtual memory exhausted". Please, upgrade at least to
1194 version 3.81 of GNU Make.
1196 There is list of features which we want to solve with our make system:
1199 Central @file{Makefile.rules} for most of components of a bigger project.
1201 FIXME (our CAN framework includes more libraries common with our other
1202 projects, we need to separate some utility libraries etc.)
1204 The rules in more spread Makefiles are way to the hell (update for
1205 different kernel, RT-Linux etc would be nightmare in other case).
1207 Make system should allow to freely move cross-dependant components in
1208 directory structure without need to update users of moved component (I
1209 hate something like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
1210 example. If a component is renamed or version is added to then name,
1211 all Makefiles in CAN will require update).
1213 Make system should be able to compile mutually cross-dependant
1214 libraries and should ensure, that change in one component sources or
1215 headers would result in relink or rebuild in components linked against
1216 that library or including modified header file.
1218 Make system has to enable compilation out of OCERA full source tree
1219 (we would lost many users of particular components in other case).
1221 Compile should be able to do all above work without need to install
1222 any files before successful finish of build.
1224 Because we use some libraries for RT-Linux build and user-space build,
1225 we need to solve how to compile from same sources to both targets.
1227 The build system should allow to call make for particular source
1228 subdirectory. Time of recursive make through all subdirectories is
1231 Make system should enable to build out of sources tree (else clean or
1232 working with CVS sandbox gets fussy and simultaneous multiple targets
1235 It would be good, if there is a possibility to call make from
1236 read-only media sources.
1238 Make system should store results of build in some separate directory
1239 structure to simple install and testing.
1241 Makefiles in sources directories should be simple.
1244 There is probably only one alternative fully supporting above requirements
1245 and it is GNU Autoheader...Automake...Autoconf... system.
1246 But it is complicated and requires big amount of support files.
1247 It would be acceptable if it could be easily used for OCERA framework.
1248 But there are important show stoppers for that system:
1251 It would require deep revision of all OCERA CVS contents and agreement
1252 on this would be problematic
1254 This system is not well prepared for dual compilation for Linux and
1255 RT-Linux sub-targets. It would mean many changes in default autoconf
1256 setup to support this. Probably simplest way would be to rebuild GCC
1257 tool chain for something like i586-elf-rtlinux. This would require
1258 even more space for OCERA development.
1261 The problem calls for some solution, which would have minimal impact
1262 on other components and would be elegant and would be maintainable
1263 and small, because our main goal is components development and not
1264 make systems development.
1266 There is result of our trial. It is OMK make system.
1267 The @file{Makefile} and @file{Makefile.omk} files should be in all source
1268 directories. Common @file{Makefile.rules} file is required in the toplevel
1269 sources directory. Alternatively this file could be moved
1270 to link tree pointing into readonly media or can be anywhere
1271 else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
1273 @c !!! tohle tam nejak zmizelo, mozna by to chtelo zkontrolovat, ze to
1274 @c sedi s aktualnim stavem
1277 Syntax of Makefile.omk files is for usual cases compatible
1278 to Automake's Makefile.am descriptions. There are specific targets
1279 for RT-Linux and Linux kernel related stuff
1281 Makefile.omk user defined variables
1284 list of subdirectories intended for make from actual directory
1286 list of the user-space libraries
1287 @item shared_LIBRARIES
1288 list of the user-space shared libraries
1289 @item kernel_LIBRARIES
1290 list of the kernel-space libraries
1291 @item rtlinux_LIBRARIES
1292 list of the RT-Linux kernel-space libraries
1293 @item include_HEADERS
1294 list of the user-space header files
1295 @item nobase_include_HEADERS
1296 headers copied even with directory part
1297 @item kernel_HEADERS
1298 list of the kernel-space header files
1299 @item rtlinux_HEADERS
1300 list of the RT-Linux kernel-space header files
1302 list of the require binary programs
1303 @item utils_PROGRAMS
1304 list of the development utility programs
1305 @item kernel_MODULES
1306 list of the kernel side modules/applications
1307 @item rtlinux_MODULES
1308 list of RT-Linux the kernel side modules/applications
1310 list of specific target sources
1312 additional include directories and defines for user-space
1313 @item kernel_INCLUDES
1314 additional include directories and defines for kernel-space
1315 @item rtlinux_INCLUDES
1316 additional include directories and defines for RT-Linux
1317 @item default_CONFIG
1318 list of default config assignments CONFIG_XXX=y/n ...
1321 The Makefile is same for all sources directories and is only 14 lines
1322 long. It is there only for convenience reasons to enable call "make"
1323 from local directory. It contains code which locates
1324 @file{Makefile.rules} in actual or any parent directory. With standard
1325 BASH environment it works such way, that if you get into sources
1326 directory over symbolic links, it is able to unwind yours steps back
1327 => you can make links to readonly media component directories, copy
1328 @file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
1329 Makefile.omk to contain only required components and then call make in
1330 top or even directories after crossing from your tree to readonly
1333 The system compiles all files out of source directories. The actual
1334 version of system is adapted even for OCERA tree mode if
1335 @code{OCERA_DIR} variable is defined in @file{Makefile.rules}
1337 There are next predefined directory name components, which can be
1341 @item BUILD_DIR_NAME = _build
1342 prefix of directory, where temporary build files are stored
1343 @item COMPILED_DIR_NAME = _compiled
1344 prefix of directory, where final compilation results are stored
1345 @item GROUP_DIR_NAME = yyy
1346 this is used for separation of build sub-trees in OCERA environment
1347 where more @file{Makefile.rules} is spread in the tree
1350 Next directories are used:
1353 @item KERN_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
1354 directory to store intermediate files for kernel-space targets
1355 @item USER_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
1356 directory to store intermediate files for user-space targets
1358 @item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
1359 directory to store exported include files which should be installed later
1360 on user-space include path
1361 @item USER_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
1362 same for user-pace libraries
1363 @item USER_UTILS_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
1364 utilities for testing, which would not probably be installed
1365 @item USER_BIN_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
1366 binaries, which should go into directory on standard system PATH
1367 (/usr/local/bin, /usr/bin or $(prefix)/bin)
1369 @item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
1370 directory to store exported include files which should be installed later
1371 on kernel-space include path
1372 @item KERN_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
1373 same for kernel-pace libraries
1374 @item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
1375 builded modules for Linux kernel or RT-Linux system
1378 There is more recursive passes through directories to enable
1379 mutual dependant libraries and binaries to compile.
1380 Next passes are defined
1383 @item default-config
1384 generates @file{config.omk-default} or xxx-default (FIXME) configuration file
1386 checks and creates required build directories
1388 copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
1390 builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
1392 @item binary-pass and utils-pass
1393 links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
1394 object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
1395 @item kernel-lib-pass
1396 builds libraries for kernel space targets
1398 builds kernel modules
1401 The amount of passes is relatively high and consumes some time. But
1402 only other way to support all required features is to assemble one big
1403 toplevel Makefile, which would contain all components and targets
1406 Drawbacks of designed make system
1409 the system is not as fast as we would like
1411 it lacks Autoconf and configure extensive support for many systems
1412 from UNIX to DOS and WINDOWS
1414 it does not contain support for checking existence of target
1415 libraries and functionalities as GNU Autoconf
1417 it is heavily dependant on GNU MAKE program. But it would not be big
1418 problem, because even many commercial applications distribute GNU MAKE
1419 with them to be able to work in non-friendly systems
1421 the key drawback is dependence on recent MAKE version 3.80 and better
1422 and even version 3.80 of MAKE has important bug, which has been
1423 corrected in newer sources (FIXME)
1426 The last point is critical. I have not noticed it first, because
1427 I use Slackware-9.2 and it contains latest released version
1428 of MAKE (version 3.80).
1429 The problem appears when I have tried to build bigger libraries.
1430 There is bug in version 3.80, which results in misleading
1431 error "Virtual memory exhausted". It is known bug with ID 1517
1434 * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
1438 I have optimized some rules to not push memory to the edge,
1439 but there could be still issues with 3.80 version.
1441 I have downloaded latest MAKE CVS sources. The compilation required
1442 separate lookup and download for .po files and full Autoheader... cycle.
1443 I have put together package similar to release. Only ./configure --prefix=...
1444 and make is required. CVS sources contains version 3.81beta1.
1445 You can download prepared sources archive from
1446 @uref{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
1447 Or you can get our local copy from
1448 @uref{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
1450 The archive contains even "make" binary build by me, which should work
1451 on other Linux distributions as well. Older version of MAKE (3.79.x
1452 released about year 2000) found on Mandrake and RedHat are not
1453 sufficient and do not support eval feature. I do not expect, that
1454 Debian would be more up-to-date or contain fixes to MAKE vm exhausted
1457 The local CTU archive with our CAN components prepared for inclusion
1458 into OCERA SF CVS could be found in my "can" directory
1460 @uref{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
1462 The code should build for user-space with new make on most of Linux distros
1463 when make is updated.
1465 If you want to test compile for RT-Linux targets, line
1468 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
1471 in @file{Makefile.rules} has to be activated and updated
1472 to point RT-Linux directory containing "rtl.mk".
1473 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
1474 (@file{can/utils/ulut/ul_rtlchk.c}).
1476 The next line, if enabled, controls compilation in OCERA project tree
1479 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
1482 The LinCAN driver has been updated to compile out of source directories.
1484 Please, check, if you could compile CAN package and help us with integration
1485 into OCERA SF CVS. Send your comments and objections.
1487 The OMK system has been adapted to support actual OCERA configuration process.
1488 I am not happy with ocera.mk mix of defines and poor two or three rules,
1489 but OMK is able to overcome that.
1491 The OMK system has integrated rules (default-config) to build default
1492 configuration file. The file is named @file{config.omk-default} for
1493 the stand-alone compilation. The name corresponds to OCERA config +
1494 "-default" if OCERA_DIR is defined. This file contains statements
1495 from all @code{default_CONFIG} lines in all @file{Makefile.omk}. The
1496 file should be used for building of own @file{config.omk} file, or as
1497 list for all options if Kconfig is used.
1499 @c @chapter OMK Reference
1501 @node Development, Variable Index, Original README, Top
1502 @chapter Development
1504 This section is far from complete. Its purpose is to document internals
1505 of @file{Makefile.rules} as well as other things needed only by people
1506 who hack OMK itself.
1510 A pass is created by instantiation of @code{omk_pass_template} with
1511 @var{pass-name} as one of arguments. This defines several targets which
1515 @item @var{pass-name}
1516 Target used to invoke the individual pass either from command line or
1517 from inside of @file{Makefile.rules}.
1519 @item @var{pass-name}-submakes
1520 Invoked recursively from @var{pass-name}. The reason for this is the
1523 @item @var{pass-name}-this-dir
1524 This target calls make recursively once again with @var{pass-name}-local
1525 target, which does the real-work. Make's working directory is set to the
1526 corresponding directory in @file{_build} tree and the -local
1528 @item @var{pass-name}-@var{dirname}-subdir
1529 This target is responsible for recursive invocation of @command{make} in
1530 subdirectories specified in @code{@ref{SUBDIRS}} variable.
1533 @node Variable Index, , Development, Top
1534 @unnumbered Variable Index
1538 @c @node Concept Index, , Variable Index, Top
1539 @c @unnumbered Concept Index