======================================================================
MkLib-C - Makefile library for C/C++ compilation
----------------------------------------------------------------------

This package contains generic makefiles for use in C/C++ projects.  It
also supports:
  - Flex and Bison
  - Source code generated by any executable script


========================
Requirements
------------------------

GNU Make (>= 3.80).

GCC.  You might be able to adapt the files to use a different
   compiler, but it isn't trivial to do so.

A Unix-ish OS (tested: Linux, Cygwin).


========================
Usage
------------------------

You should keep this directory in a central location.  Projects that
use MkLib-C will use the GNU Make "include" directive to make use of
the generic makefiles.

For example, if you have code that builds into an executable, the
minimal Makefile would look like this:

   PROGRAM_NAME = goose
   SRC_DIR = Source
   OUT_DIR = Build

   MKLIB_C_PATH = /home/yoda/Software/MkLib-C/Include
   include $(MKLIB_C_PATH)/Executable.mk

All the ".c", ".cpp", ".l" and ".y" files in the "Source/" directory
(and all subdirectories) will be considered part of the project's
source files.

All the build output will be placed in the "Build/" directory.  The
executable name will be "goose" (or "goose.exe" on Cygwin).

There are lots of ways to configure the build.  Some of the more
common ones are:

-----
Select Compilation Units - Wildcard Matching

You can add/remove compilation units based on shell-style wildcard
expressions.  If the variable uses "%" as the wildcard character, it
can only be used once per entry (i.e. you cannot do "%.old.%")

   FILTER_UNITS = %.cpp %.l Happy.c
      # Only use the source files that match the given expressions.
      # This variable uses "%" as the wildcard.

   DEL_UNITS = %.old.cpp
      # Remove any files from the compilation list that match the
      # given pattern.

   ADD_UNITS = MyFile.c *.new.c
      # Finally, add the given files to the compilation list.  This
      # variable uses "*" as the wildcard.

-----
Select Compilation Units - Unit Lists

If you want to be more explicit about the list of files, you can
create "unit list" files to tell the makefile what to compile.

For example, create a file called "units-main" in the "Source/"
directory.  That file should contain a list of compilation units,
one on each line.  Just write the name of the compilation unit (ex:
"GooseMan") and not the name of the source file (ex: GooseMan.cpp or
GooseMan.y).

In your main makefile, add the variable:

   UNIT_SELECT = main plugin

This will tell the MkLib-C to compile all the units listed in all the
"units-main" and "units-plugin" files it can find (it will search the
"SRC_DIR" directory recursively).

In unit list files, blank lines will be ignored.  You can also use the
"#" character to create an inline comment, which will also be ignored.
The unit list files should specify paths relative to where they
themselves are located.

-----
Compiler Options:

You can use "CFLAGS" to pass options to the compiler and "LDFLAGS" to
pass options to the linker.  If you prefer, you can also use the more
specific variables: OPTIMIZE, DEBUG and ARCH, DEFINE.  Those variables
are all just appended onto the compiler invocation command.

The "INC_DIRS" variable should be a list of directories to add to the
include path.  Do not add the "-I" prefix, it will be added
automatically.

The "C_COMPILER", "CPP_COMPILER" and "LINKER" variables, by default,
are set to set to "gcc", "g++" and "g++".  There's a lot of
GCC-specific stuff going on, so you probably won't be able to
substitute entirely different tools, but you can probably use
different versions of GCC (a cross compiler, for example).

-----
Show Shell Commands:

Normally, the makefiles do not display the shell commands as they are
executed.  To change that, set the "SHOW" variable.

   SHOW = yes
   SHOW = y
      # This will show the "major" commands.
   SHOW = all
   SHOW = a
      # This will show all commands.

This variable can be set at the command line while executing "make":

   > make SHOW=y

-----
Path to MkLib-C

If you're going to be compiling in different environments (or giving
the source package to other people), it is bad idea to hard-code the
path to MkLib-C.

An alternative would be to have the main makefile include another
"configuration file" to set the path (and other site-specific
variables).  The configuration file should NOT be distributed with
your program.

   PROGRAM_NAME = goose
   SRC_DIR = Source
   OUT_DIR = Build

   # Load settings from "Config.mk"
   -include Config.mk
   MKLIB_C_PATH ?= $(error Set the "MKLIB_C_PATH" variable in "Config.mk")

   include $(MKLIB_C_PATH)/Executable.mk

You may also want to run a sanity check to make sure that the file
"$(MKLIB_C_PATH)/Common.mk" really exists.