From e8fec75255693a1517f7671eb9f4e288c11c4eba Mon Sep 17 00:00:00 2001
From: Michal Sojka <sojkam1@fel.cvut.cz>
Date: Tue, 12 Nov 2013 10:51:36 +0100
Subject: [PATCH] Document AM_*FLAGS and relation to *FLAGS

---
 doc/omk-manual.texinfo | 75 ++++++++++++++++++++++++++----------------
 1 file changed, 46 insertions(+), 29 deletions(-)

diff --git a/doc/omk-manual.texinfo b/doc/omk-manual.texinfo
index c7f6494..93604ef 100644
--- a/doc/omk-manual.texinfo
+++ b/doc/omk-manual.texinfo
@@ -169,6 +169,7 @@ about the process of modularization.
 * Invoking OMK::
 * Compiling Programs::
 * Compiling Libraries::
+* Compiler Flags::
 * Recursing into Subdirectories::
 * Dependency Tracking::
 * Configuration and Conditional Compilation::
@@ -320,7 +321,7 @@ To tell OMK to compile a program, you need to set some variables in
 @file{Makefile.omk} (usually) in the directory where program sources are
 located.
 
-In the example bellow a program @command{test} will be compiled from
+In the example bellow program @command{test} will be compiled from
 source @file{test.c}.
 
 @example
@@ -382,33 +383,7 @@ source @file{test.c}.
   instead of lib_LOADLIBES.
 @end defvar
 
-@defvar INCLUDES
-  Directives passed to the C or C++ compiler with additional directories
-  to be searched for header files. In most cases you need to specify an
-  absolute path. To specify a directory relative to the source
-  directory, you can use the @code{$(SOURCES_DIR)} variable, which
-  refers to the directory, where @file{Makefile.omk} is located. This
-  variable applies to all compilations invoked in the current directory.
-
-  @example
-  INCLUDES = -I$(SOURCES_DIR)/my_include_dir
-  @end example
-@end defvar
-
-@defvar DEFS
-  Directives passed to the C or C++ compiler with preprocessor macro
-  definitions. This variable applies to all compilations invoked in the
-  current directory.
-
-  @example
-  DEFS = -DDEBUG=1
-  @end example
-@end defvar
-
-
-@c FIXME: INCLUDES variable should not be set by rtlinux rules.
-
-@node Compiling Libraries, Recursing into Subdirectories, Compiling Programs, User's Manual
+@node Compiling Libraries, Compiler Flags, Compiling Programs, User's Manual
 @section Compiling Libraries
 
 
@@ -515,7 +490,49 @@ and what is their destination file name.
   top level configuration file @file{config.omk} or on command line.
 @end defvar
 
-@node Recursing into Subdirectories, Dependency Tracking, Compiling Libraries, User's Manual
+@node  Compiler Flags, Recursing into Subdirectories, Compiling Libraries, User's Manual
+@section Compiler Flags
+
+OMK follows the same philosophy for flag variables as does Automake. The
+variables with AM_ prefix (e.g. AM_CPPFLAGS) are supposed to be used by
+the package developer and variable without that prefix (e.g. CPPFLAGS)
+are reserved for the user. The following
+
+@defvar AM_CPPFLAGS
+Preprocessor switches.
+@end defvar
+
+@defvar AM_CFLAGS
+C compiler switches.
+@end defvar
+
+
+@defvar INCLUDES
+  Directives passed to the C or C++ compiler with additional directories
+  to be searched for header files. In most cases you need to specify an
+  absolute path. To specify a directory relative to the source
+  directory, you can use the @code{$(SOURCES_DIR)} variable, which
+  refers to the directory, where @file{Makefile.omk} is located. This
+  variable applies to all compilations invoked in the current directory.
+
+  @example
+  INCLUDES = -I$(SOURCES_DIR)/my_include_dir
+  @end example
+@end defvar
+
+@defvar DEFS
+  Directives passed to the C or C++ compiler with preprocessor macro
+  definitions. This variable applies to all compilations invoked in the
+  current directory.
+
+  @example
+  DEFS = -DDEBUG=1
+  @end example
+@end defvar
+
+@c FIXME: INCLUDES variable should not be set by rtlinux rules.
+
+@node Recursing into Subdirectories, Dependency Tracking, Compiler Flags, User's Manual
 @section Recursing into Subdirectories
 
 OMK is probably most useful in projects consisting of multiple
-- 
2.39.2