* Dependency Tracking::
* Configuration and Conditional Compilation::
* Advanced OMK Features::
+* Properties of Specific Makefile.rules::
* Running OMK under Windows OS::
* Interfacing OMK to popular IDEs::
* Troubleshooting::
@c TODO: Pavel's note about qmake.
-The compilation process itself is comprised of several passes. Every
+@anchor{passes}
+The compilation process itself is comprised of several @emph{passes}. Every
pass traverses the whole directory structure@footnote{In future, we are
planning some optimization that allows OMK to traverse the directories
only once and thus decrease compilation time.} and does a particular
@command{make CFLAGS="-g -O0 -Wall"}
@end example
+If your project uses an alternative make-system (e.g. Automake or custom
+makefiles), it might be useful for you to use the command:
+@example
+@command{make omkize}
+@end example
+@noindent This will find all @file{Makefile.omk} files in all subdirectories
+and copies generic @file{Makefile} from the root directory to that
+subdirectories. This way you can easily switch your project to use OMK.
+
+
@anchor{V}
@defvar V
If this variable equals to @samp{1}, the whole command lines for all
-executed commands are displayed. Otherwise, only short messages are
+executed commands are displayed. When not set or zero, only short
+messages are printed. Value of @samp{2} displays the whole command lines
+as with @samp{1} and in addition directory navigation messages are
printed.
@end defvar
@end defvar
@defvar xxx_SOURCES
- For every program name @var{xxx} in @code{bin_PROGRAMS}, this variable
- contains a list of sources that are needed to compile the
- executable. OMK uses an extension of the filename to determine the
- compiler to compile this source.
+ For every program name @var{xxx} in @code{bin_PROGRAMS},
+ @code{test_PROGRAMS} or @code{utils_PROGRAMS}, this variable contains
+ a list of sources that are needed to compile the program. OMK uses an
+ extension of the filename to determine the compiler to compile this
+ source.
@end defvar
@defvar xxx_LIBS
In @file{Makefile.omk}, you specify several variables, which defines how
the libraries should be compiled. In the example below the library
-@samp{mylib} is created from two sources @file{funca.c} and
-@file{funcb.c}. Interface of this library is defined in
-@file{myfunc.h}. Therfore, we export this header for use by other
-programs.
+@samp{mylib} (full filename will be @file{libmylib.a}) is created from
+two sources @file{funca.c} and @file{funcb.c}. Interface of this library
+is defined in @file{myfunc.h}. Therfore, we export this header for use
+by other programs.
@example
@verbatiminclude ../tests/libraries/Makefile.omk
@noindent Variables for use with libraries are:
@defvar lib_LIBRARIES
- Specifies a list of statically linked libraries to be compiled.
+ Specifies a list of statically linked libraries to be compiled. OMK
+ automaticvally prepends @code{lib} prefix library names.
@end defvar
@defvar shared_LIBRARIES
@end example
@end defvar
-@defvar LN_INCLUDES
+@defvar LN_HEADERS
If this variable equals to @samp{y}, symbolic links to headers in
source directories are used in @file{_compiled} tree instead of
copies.
@node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, OMK User's Manual
@section Configuration and Conditional Compilation
-In many projects, it is necessary to configure a compilation process. By
+In many projects, it is necessary to configure the compilation process. By
this configuring we mean, setting some parameters that influence the
output of compilation process. In GNU projects, @command{configure}
script is usually responsible for configuration. User provides some
of GNU Autoconf, but currently there is no directly integrated support
for it.
-In every directory you can specify some configuration parameters, which
-can be modified by a user. Then, when @command{make default-config} is
-run, all these parameters are found and together with their default
-values are stored as makefile variables in
+There exist three different configuration files
+@file{config.omk-default}, @file{config.target} and
+@file{config.omk}. All of these have to be stored in the same directory
+as @file{Makefile.rules}. During compilation, these files are included
+in @file{Makefile.rules} in this order which means that variables
+assigned in the former files are overridden by those from later
+ones. All settings specified here apply to the whole compilation
+tree. Each file is intended for a different kind of configuration
+values:
+@table @file
+@item config.omk-default
+ Stores default configuration of compiled components. This file is
+ automatically generated (see below) and should not be edited by users.
+@item config.target
+ Stores default configuration for a project or target hardware. This
+ file is intended to be stored in a version control system and should
+ be modified only by the maintainer of the project.
+
+ For cross compiled projects, this file typically contains settings of
+ variables like @var{CC} and @var{CFLAGS}.
+@item config.omk
+ This is a file for end users, where any default settings set in the
+ above files can be overridden. This file should not be stored in
+ version control system. The project should compile without having this
+ file.
+@end table
+
+Besides variables defined in @file{config.target}, @file{Makefile.omk}
+in any subdirectory can specify some configuration parameters. When
+@command{make default-config} is run, all these parameters are found and
+together with their default values are stored as makefile variables in
@file{config.omk-default}. This file is included during compilation, so
if you don't specify other values, these defaults are used. If you are
not satisfied with these defaults, you can override the values of
-parameters in @file{config.omk}. This file is also included during
-compilation and variables mentioned there takes precedence over those
-specified in @file{config.omk-default}. Both @file{config.omk} and
-@file{config.omk-default} have to be stored in the same directory as
-@file{Makefile.rules}.
-
-Besides overriding the default values of configuration parameters,
-@file{config.omk} can also be used as a common place to store some
-global settings that applies to the whole project, e.g. the compiler to
-use or common compiler flags.
+parameters either locally for your build in @file{config.omk} or
+globally for all people working with the project in
+@file{config.target}.
@subsection Specifying Configuration Parameters
compiler.
@end vtable
-@node Advanced OMK Features, Running OMK under Windows OS, Configuration and Conditional Compilation, OMK User's Manual
+@node Advanced OMK Features, Properties of Specific Makefile.rules, Configuration and Conditional Compilation, OMK User's Manual
@section Advanced OMK Features
In this section we list several OMK features, which are more complicated
or rarely used so they were omitted in previous sections.
+@menu
+* Unsorted Advanced Features::
+* Adding Hooks to Passes::
+@end menu
+
+@node Unsorted Advanced Features, Adding Hooks to Passes, Advanced OMK Features, Advanced OMK Features
+@subsection Unsorted Advanced Features
+
@itemize
@item
The @file{_compiled} directory can be shared between multiple projects
(re)compiled, even if @command{make} is called from a subdirectory.
@end defvar
+@anchor{USE_LEAF_MAKEFILES}
+@defvar USE_LEAF_MAKEFILES
+If this variable equals to @samp{n} (default is unset), then OMK uses
+the leaf @file{Makefile} only when it is invoked by simple
+@command{make} command. Later, during recursive directory descent leaf
+@file{Makefile} is not used and @file{Makefile.rules} is included
+directly.
+
+This feature is useful if you are integrating some non-OMK project into
+your project. You only add @file{Makefile.omk} files to the other
+project and don't need to modify project's original Makefiles.
+
+This variable can be set either globally in a @file{config.*} file or
+locally in some @file{Makefile.omk}. In the latter case, it influences
+only subdirectories of the directory containing @file{Makefile.omk}.
+@end defvar
+
+@anchor{SOURCES_DIR}
+@defvar{SOURCES_DIR}
+This variable is set internally by OMK and its value is the absolute
+path to the directory with compiled sources. It can be used if you need
+to refer to sources files in some custom constructs in
+@file{Makefile.omk}.
+@example
+@verbatim
+include_HEADERS = $(notdir $(wildcard $(SOURCES_DIR)/*.h))
+@end verbatim
+@end example
+@end defvar
+
+@defvar{srcdir}
+The same as @ref{SOURCES_DIR}. Provided for Automake compatibility.
+@end defvar
+
+@defvar{MAKERULES_DIR}
+This variable is set internally by OMK and its value is the absolute
+path to the directory containing @file{Makefile.rules} currently used
+during compilation.
+@end defvar
+
+@defvar{OMK_RULES_TYPE}
+Identification the type of @file{Makefile.rules} used for
+compilation. Values are like @samp{linux}, @samp{rtems}, @samp{sysless},
+... This variable is automatically generated during creation of
+@file{Makefile.rules} and can be used in configuration files (see
+@ref{Configuration and Conditional Compilation}) or in
+@file{Makefile.omk} to tweak compilation for specific targets.
+@end defvar
+
+@node Adding Hooks to Passes, , Unsorted Advanced Features, Advanced OMK Features
+@subsection Adding Hooks to Passes
+
+Sometimes it is necessary to run some special commands as a part of
+compilation. Typical example might be a tool which generates source
+files on the fly. OMK supports calling additional commands during
+compilation by so called @emph{pass hooks}. A pass hook is an ordinary
+make target which is invoked as part of compilation during a particular
+pass (see @ref{passes}). Pass hooks can be defined by assigning their
+names to @code{xxx_HOOKS} variable.
+
+@defvar{xxx_HOOKS}
+Specifies one or more hooks (make targets) which are invoked during pass
+@var{xxx}. The working directory of commands or this target is under the
+@file{_build} tree.
+
+In the example bellow header file @file{generated_header.h} is created
+during @samp{include-pass} by @file{convert_data} program. The program
+takes @file{data_file.txt} in the source directory as the input and
+creates the header file in the in the correct directory under the
+@file{_build} tree.
+
+@example
+include-pass_HOOKS = generated_header.h
+
+generated_header.h: $(SOURCES_DIR)/data_file.txt
+ convert_data < $^ > $@@
+@end example
+@end defvar
+
+@node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, OMK User's Manual
+@section Properties of Specific Makefile.rules
+
+In previous sections, general properties of @file{Makefile.rules} were
+documented. This section contains documentation to features found only
+in some particular @file{Makefile.rules}.
+
+@menu
+* Linux::
+* System-Less::
+* RTEMS::
+@end menu
+
+@node Linux, System-Less, Properties of Specific Makefile.rules, Properties of Specific Makefile.rules
+@subsection Linux
+
+This @file{Makefile.rules} is used not only for Linux as the name
+sugest, but also for other Unices and even for Windows.
+
+@defvar BUILD_OS
+ The name of the operating system (OS) where make was invoked.
+@end defvar
+
+@defvar TARGET_OS
+ Should specify the name of OS where the resulting binary should be
+ used. If not specified manually, it equals to BUILD_OS.
+@end defvar
+
+@defvar QT_SUBDIRS
+ Lists subdirectories with QT project (.pro) file. OMK will generate
+ there @file{Makefile} by calling @command{qmake} with correct
+ parameters to interface QT application to the rest of the compilation
+ tree. Then @command{make} is called there to compile QT
+ application. Variable @samp{QTDIR} must be set to the directory with
+ QT instalation (e.g. /usr/share/qt4 on Debian).
+@end defvar
+@node System-Less, RTEMS, Linux, Properties of Specific Makefile.rules
+@subsection System-Less
+
+@node RTEMS, , System-Less, Properties of Specific Makefile.rules
+@subsection RTEMS
+
-@node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Advanced OMK Features, OMK User's Manual
+@node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Properties of Specific Makefile.rules, OMK User's Manual
@section Running OMK under Windows OS
@node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, OMK User's Manual
@node Troubleshooting, , Interfacing OMK to popular IDEs, OMK User's Manual
@section Troubleshooting
-Renaming of some file => dependency problems.
+@itemize
+@item
+ If you rename some file or directory and then you can't compile your
+ project, call @command{make clean} in the directory with errors. The
+ reason for this behavior is that OMK remembers dependencies of every
+ file. After renaming something, the original name is still stored in
+ dependencies, but make doesn't know how to create this non-existent
+ source.
-Manual compilation ... V=1
+@item
+ Sometimes, you may want to compile one file the same way as OMK does
+ it, but run the compilation manually from command line. For example,
+ you want to debug some preprocessor macros and you only want to
+ produce preprocessed source instead of object file.
+
+ To compile something manually, you can run OMK with @command{make
+ V=2}. This will print all commands executed together with directory
+ navigation messages. Find the command you want to execute manually in
+ the output. To run it, you need to change the working directory to the
+ correct one in the @file{_build} tree. The correct directory can be
+ found in make output on the line @samp{Entering directory} preceding
+ the desired command.
+@end itemize
@node Original README, OMK Development, OMK User's Manual, Top
@chapter Original README
projects / omk / sssa.git / blobdiff