[z180-stamp.git] / mk / Readme.txt

################################################################################
#                  Non-recursive make build system                             #
#                  -------------------------------                             #
#     Copyright (C) 2012 Andrzej Ostruszka <andrzej.ostruszka@gmail.com>       #
#                                                                              #
#          URL: http://github.com/aostruszka/nonrec-make                       #
#          (or older: http://nonrec-make.googlecode.com/)                      #
#                                                                              #
# Permission is hereby granted, free of charge, to any person obtaining a copy #
# of this software and associated documentation files (the "Software"), to     #
# deal in the Software without restriction, including without limitation the   #
# rights to use, copy, modify, merge, publish, distribute, sublicense,         #
# and/or sell copies of the Software, and to permit persons to whom the        #
# Software is furnished to do so, subject to the following conditions:         #
#                                                                              #
# The above copyright notice and this permission notice shall be included in   #
# all copies or substantial portions of the Software.                          #
#                                                                              #
# Except as contained in this notice, the name(s) of the above copyright       #
# holders shall not be used in advertising or otherwise to promote the sale,   #
# use or other dealings in this Software without prior written authorization.  #
#                                                                              #
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR   #
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,     #
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  #
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER       #
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      #
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS #
# IN THE SOFTWARE.                                                             #
################################################################################

NOTE: This readme _might_ not be up to date.  For up to date information
see the above URL (and accompanying wiki pages).

This is my attempt to implement a non-recursive make build system.  For
the motivation Google for the paper "Recursive make consider harmful" by
Peter Miller.

I've seen couple of other proposals and decided to have something that
will be a blend of nice ideas I have seen plus some improvements.  If
you actually use this I'd like to hear from you :) - is it useful, does
it perform well, do you have any suggestions for the improvements ...
and so on.  This implementation is based on GNU make and its new
features introduced in 3.80.  But don't use that version - these
features had bugs in that version.  Use version 3.81 where everything
works OK.

Before you keep on reading though, just take a look at the structure of
the Rules.mk files (Rules.top has exactly the same structure as Rules.mk
- it just has another name to ease location of the top level project
directory from its subfolders).
I've got a feeling that it is much easier to understand how the system
looks from the user perspective just by looking at the example than
reading its explanation :D.

OK, now that you have a feeling how the Rules.mk look like let me walk
you through an example (ex1 in the repository).  Consider the project
that has some source files at the top directory and is depending on two
libraries in Dir_1 and Dir_2 and another one in Dir_3.  The libraries
themselves are partitioned between several subdirectories and Dir_2 has
some examples in a separate subfolder (do not pay attention to all *.c
files).

ex1/
  Makefile
  Rules.top <- Just a symlink to Rules.mk to mark where the top level is
  Rules.mk
  main.c
  top_a.c
  top_b.c
  cli.c
  cli_dep.c
  mk/* <- This is where the mk files from this build system are
  Dir_1/
    Makefile
    Rules.mk
    dir_1_file1.c
    dir_1_file2.c
    dir_1_file3.c
    Dir_1a/
      Makefile
      Rules.mk
      dir_1a_file1.c
      dir_1a_file2.c
      dir_1a_file3.c
    Dir_1b/
      Makefile
      Rules.mk
      src/
        dir_1b_file1.c
        dir_1b_file2.c
  Dir_2/
    Makefile
    Rules.mk
    dir_2_file1.c
    dir_2_file2.c
    Dir_2a/
      Makefile
      Rules.mk
      dir_2a_file1.c
      dir_2a_file2.c
      dir_2a_file3.c
    Dir_2b/
      Makefile
      Rules.mk
      dir_2b_file1.c
      dir_2b_file2.c
      dir_2b_file3.c
    Dir_ex/
      Makefile
      Rules.mk
      ex.c
  Dir_3/
    Makefile
    Rules.mk
    dir_3_file1.c
    dir_3_file2.c

There's one top level make file (Rules.top) which eventually includes
all the makefiles.  In addition in each directory there is Makefile
(which can be a link to the one in the top level directory) which
searches for the Rules.top includes it with the default goal
changed to rebuild only targets for the current directory.  This allows
you to run make from each subdirectory and update only part of the
targets (in contrary to other implementation which usually require
you to run it at the top level and make full build each time).

This build system was designed to have very simple structure of the
"user makefiles".  The user just has to set the Rules.mk files in each
directory and some general configuration options.  All the "magic" is
hidden in header.mk, footer.mk and skel.mk which don't have to be
modified [1].

The structure of the Rules.mk is following (this is from top level
Rules.top which has the same format as Rules.mk - and in fact it is
suggested that it should be a symlink to normal Rules.mk file since it
will allow for this project to act as a subproject of some super project
treating your whole project tree as a subdirectory[2]):

-8<---Rules.top---------------
1:  TARGETS = app.exe cli.exe
2:  SUBDIRS = Dir_1 Dir_2
3:
4:  app.exe_DEPS = top_a.o top_b.o main.o $(SUBDIRS_TGTS)
5:  app.exe_LIBS = -lm
6:  # Let's use DEFAULT_MAKECMD for app.exe
7:
8:  cli.exe_DEPS = cli.o cli_dep.o
9:  cli.exe_CMD = $(LINK.c) $^ $(LDLIBS) -o $@
-8<---------------------------

Line 1 - this directory has two targets that should be built.
Line 2 - this directory has two subdirectories that should be scanned
Line 4 - app.exe depends on ... (SUBDIRS_TGTS is a variable that
         contains all the targets from the subdirectories mentioned at
         line 4)
Line 5 - app.exe should be linked with math library
Line 6 - app.exe will be built with default "rule"
Line 8 - cli.exe depends on ... and
Line 9 - use the following command to build it

You can specify the targets for current directory in two ways:
1. Give them in TARGETS.  Each target can have it's own *_DEPS, *_LIBS
  and *_CMD which give the dependencies, additional libs needed and
  a command to run which will update the target.  They are explained
  a bit below.
2. The targets are simply objects - or in more general files that
  match patterns in AUTO_TGTS, and have appropriate rules in 'skeleton'.
  In that case you can list them in OBJS or SRCS like e.g. in Rules.mk
  from Dir_1a

-8<---Dir_2/Dir_2a/Rules.mk---
1: SRCS := dir_2a_file1.c dir_2a_file2.c dir_2a_file3.c
-8<---------------------------

There are "reserved" variables that you should not modify.  Most notably:
- $(d) is the directory of the current Rules.mk [see note 2]
- $(TOP) is the top level directory of the project tree
- $(MK) is the directory where the included *.mk makefiles are
For the full list you have to take a look at the makefiles in mk
directory (e.g. in the skel.mk there are macros 'include_subdir_rules',
'save_vars', 'tgt_rule' and 'skeleton' which you should not change [1]).

Going back to the Rules.mk.  Normally wildcards in variable assignments
are not expanded in make but this make system detects wildcards in SRCS
and expands them (both in directory of the Rules.mk and its SRCS_VPATH
subdirectories - see below what SRCS_VPATH is used for).  Thus you can
simply say in Rules.mk:

SRCS := *.c

If you have directory with large number of files where simple glob is
what you want to use in SRCS but there are some files that you'd like to
exclude just list them in SRCS_EXCLUDES :) - this is a list of makefile
patterns e.g.

SRCS_EXCLUDES := extra% test%

Of course you can use the built in make wildcards but you should do that
as follows:

SRCS := $(notdir $(wildcard $(d)/*.c))

Keep in mind that the directory where make is invoked is usually different
from where given Rules.mk is located.

When supplying the value for *_DEPS you can refer to the object from the
same directory with no directory prefix.  To be specific all
dependencies that are not absolute paths will be treated as ones from
the $(OBJDIR) subdirectory of current directory (OBJDIR and OBJPATH are
"discussed" below).  You can use SUBDIRS_TGTS variable which will list
all targets in subdirectories.  You can also name them explicitly like
$(TARGETS_$(d)/subdir) and so on - see e.g. the Rules.mk in Dir_2
directory where Dir_ex is mentioned as a subdirectory but is excluded
from the *_DEPS (this allows you to create folders that "inherit" all
the setting from the project build system but are not meant to be a part
of the project itself - like examples).  For instance:

dir1_lib.a_DEPS = dir_1_file1.o dir_1_file2.o dir_1_file3.o $(SUBDIRS_TGTS)

tells that dir1_lib.a (which will be created in Dir_1/$(OBJDIR)) depends
on several object files from the same directory and the targets from all
subdirectories.

One last thing about the TARGETS/OBJS.  By default source files for the
objects are searched in the directory where Rules.mk is, but if you want
to have source files in a subdirectory (say 'src') you can do that via
SRCS_VPATH variable (see skel.mk).  E.g.:

SRCS_VPATH := src1 src2

will cause make to first look at the directory where Rules.mk is present
and then in its src1 and src2 subdirectories.

*_LIBS are appended to the LDLIBS variable when updating the target.
This variable is used by several make built in rules but if you create
your own rule or MAKECMD.* (see next paragraph) you can refer to it (see
the function 'save_vars').

When *_CMD is not present and the target does not match any pattern in
AUTO_TGTS then either MAKECMD.suff (where .suff is the suffix of the
target) or DEFAULT_MAKECMD is used - take a look into skel.mk.

If you want to setup special flags for compilation you can do that via
"directory specific variables".  As an example here's what I did for
compilation of C files.  There's a built in rule in make which uses
COMPILE.c variable for making %.o out of %.c so I added $(DIR_CFLAGS) to
its default value and DIR_CFLAGS is defined in skel.mk as:

DIR_INCLUDES = $(addprefix -I,$(INCLUDES_$(<D)))
DIR_CFLAGS = $(CFLAGS_$(<D)) $(DIR_INCLUDES)

So it extracts the directory part of the first prerequisite in the rule
(that is %.c file - check the section 'automatic variables' in make
manual for the meaning of $(<) and $(<D)) and refer to variables named
CFLAGS_the_directory_part and INCLUDES_the_directory_part.
Thus if you wanted to add special includes for files in Dir_1/Dir_1b you
could add:

INCLUDES_$(d) := $(TOP)/some/special/include_dir

into its Rules.mk and all files in this directory will be compiled with
-I$(TOP)/some...  switch.  The same goes for CFLAGS and CXXFLAGS.

The same goes for the linker flags - quoting from skel.mk:

LDFLAGS = $(addprefix -L,$(LIBDIRS_$(subst /$(OBJDIR),,$(@D))))
LDLIBS = $(LIBS_$(@))

The above means that if targets in given directory need to be linked
with special -L switches you can provide them via LIBDIRS_$(d)
variables.  If there are some global -L switches just append them in
skel.mk.  The second line above shows how *_LIBS variable that you can
give for specific target gets added to the LDLIBS (there's 'save_vars'
in between if you're curious :)).

You can of course use target specific variables that GNU make supports
so you have more control (if you don't know what target specific
variables are take a look into manual).  Say you want to compile
dir_1b_file2.c with an additional flag but all other files in
Dir_1/Dir_1b directory should not have this flag turned on.  All you
need to do is to add this line into Rules.mk in Dir_1b directory.

$(OBJPATH)/dir_1b_file2.o : CFLAGS += -ansi

OBJPATH is a variable that contains the full directory where the
resulting object file will be placed.  While we are at this, by default
all targets are compiled into OBJDIR (defined in skel.mk as 'obj')
subdirectory of the directory where Rules.mk is present.  You can use
this OBJDIR variable (and perhaps some conditional statements) to setup
the output path according to your current compilation mode.  E.g.
obj/debug for objects with debugging information or obj/ppc_7xx for
cross compilation to the given Power PC family and so on.  There's
predefined (in config* files) HOST_ARCH variable that you can use for
this (e.g. set OBJDIR := obj/$(HOST_ARCH) in skel.mk).

Finally let me explain what targets are defined and the way you can run
them from command line.  By default (that is if you have not modified
anything :)) there are several targets that are "global".  It is 'all',
'clean_all' and 'dist_clean'.  If you specify them in the command line
they will respectively rebuild whole tree, clean everything and clean
everything together with the removal of OBJDIRs - no matter from which
directory you started make.  BTW if there's something that you want to
clean up and it's not in the OBJDIR - e.g. you've got file lexer.l out
of which lexer.c and lexer.h is generated and you want them to be
removed - you can specify this in the variable CLEAN (this is relative
to the directory where Rules.mk is).
In addition to those each dir has "it's own" targets.  These are:

1) dir_<directory_path>
   which builds all targets in given directory plus its dependencies
2) tree_<directory_path>
   which builds all targets in subtree starting at directory given
3) clean_<directory_path>
   which removes all "products" from the $(OBJDIR) subdirectory of
   current directory
4) clean_tree_<directory_path>
   which does clean_<directory_path> and the same for each its
   subdirectory

For your convenience there are couple "aliases" defined (see Makefile).
When no target is given on command line it defaults to dir_$(pwd).
If you give 'clean' as a target that will result in execution of target
clean_$(pwd) and the same for 'clean_tree'.  E.g. say you're in Dir_1.
Then:

* 'make' (same as 'make dir_$(pwd)')
   builds all targets in the Dir_1 which in our example is
   Dir_1/obj/dir1_lib.a - of course any of its dependencies that are not
   up to date are updated also.  This rule has one exception - if your
   Rules.mk has no targets and only SUBDIRS (e.g. you have grouped
   several subdirectories in one directory) then simple 'make' in this
   directory - instead of doing nothing - will build targets of all its
   subdirectories.
* 'make tree' (same as 'make tree_$(pwd)')
   rebuilds everything in given subtree
* 'make clean' (same as 'make clean_$(pwd)')
   removes everything from Dir_1/obj/
* 'make clean_tree (same as 'make clean_tree_$(pwd)')
   cleans Dir_1/obj and Dir_1/Dir_1[abc]/obj

You can obviously provide the path by yourself - it does not have to
be $(pwd) - and as usual you can build particular object files too e.g.
'make $(pwd)/obj/dir_1_file1.o'

And that would be it.  Gee, so much writing for something that is rather
simple to use - go ahead and take a look again at these Rules.mk in
various directories.  Setting up you project should be simple by now :).

Have fun!

                                        Andrzej Ostruszka

[1] Unless this build system does not do what you wanted :-P.  In that
case you probably need to spiff it up.  So you'll need to
digest it first and note [3] is my hand at it :).

[2] There is one limitation that you should be aware.
Prior to commit 070f681 you should not have in your project two "target
specific" LIBS, LDFLAGS or CMD variables (that is those that are used
during second phase of make execution) that have the same names!  For
example in one part of your tree you're generating target abc which has
it's abc_CMD and in the other part another target that has the same name
and also it's own command.  In such case the last assignment to abc_CMD
will hold and it will be used for both targets.  The same goes for LIBS
and LDFLAGS.

And this also applied to situation when you would like to use two
subprojects in one larger project.  There should be no clash between
variables from these subprojects.

Starting with commit 070f681 you can have in your (sub)projects two
LIBS, LDFLAGS or CMD variables.  However there is a catch here! Since
these variables are not mandatory (you don't have to provide them for
each target) in order to differentiate between case where abc_CMD was
actually given for this instance of abc target from the situation where
abc_CMD is still visible from previous instance of abc target those
abc_(LIBS|LDFLAGS|CMD) variables are cleared once their value is
used/remembered (see save_vars macro in skel.mk). That means referring
to these variables outside Rules.mk where they were assigned will not
work (and even in the same Rules.mk they will work only in case of
simply expanded variables - not recursive). If you have such need I'd
advice to introduce your own variable and use this variable in all
places, e.g.:

MATH_LIBS := -lgsl -lgslcblas -lm
...
TARGETS := abc

abc_DEPS = ...
abc_LIBS = $(MATH_LIBS)
...

[3] You should know that make works in two phases - first it scans the
makefiles and then it begins their execution (see discussion of
'immediate' and 'deferred' in section 'Reading Makefiles' of make
manual).  This implies that the $(d) variable is not valid during
execution of the commands used for target updates.  If you need to refer
to the directory of the target or prerequisite you should rely on
automatic variables (@, <, ...) and built in functions (dir, notdir,
...).

Every Rules.mk (or Rules.top) need to be included in cooperation with
header.mk and footer.mk.  This is now done automatically but in older
versions this was not so and user had to include them manually.
The main purpose of header is to clear all variables that you can use
inside Rules.mk so that values set in one rules file does not propagate
to other.  In addition at the top level it sets the $(d) variable (which
stands for the directory where the currently included Rules.mk is) and
includes the skel.mk so the top level Rules.top can have exactly the
same structure as other Rules.mk.

The skel.mk is a skeleton which defines variables used by make.  In
addition it includes:
- config.mk - this is a file with the "configuration" for your project
- def_rules.mk - where to put general rules (e.g. pattern rules).  E.g.
  if you want to add a rule that builds %.o out of %.m4 (by running m4
  preprocessor before passing the contents of file to CC) just put it in
  here.

skel.mk also defines some functions like save_vars and tgt_rule
which are called in the footer.mk.  Take a look into make manual for the
way the functions are defined and called if you're not familiar with it.

include_subdir_rules: This is where I keep track of directory of
        currently included makefile and include the Rules.mk from the
        subdirectories.  This function is called in footer.mk in foreach
        loop with a subdirectory name as an argument.

save_vars: This one is very simple it just saves the target specific
        variables under their "full path" variables.  E.g.
        dir1_lib.a_DEPS will get saved as DEPS_$(TOP)/Dir_1/obj/dir1_lib.a
        This has two purposes.  First it allows you to have targets with
        the same names in different directories (not that I recommend
        this :)) and allows for easier definition of tgt_rules :-P

tgt_rule: This is where the rule for given target is created.  First
        I convert all relative dependencies to the absolute ones then
        I include all dependency files (by default they are created as
        side effects during compilation - if your compiler does not
        allow you to do that just make simple shell script that will do
        this).  I also append appropriate libs and then issue the rule
        for this target.  By using the short circuiting 'or' command
        I give priority to the CMD over MAKECMD.suffix which itself has
        priority over DEFAULT_MAKECMD.

skeleton: This is just a skeleton for compilation of files in given
        directory.  If you want to add some rule here then also add
        appropriate pattern to the AUTO_TGTS that will filter out these
        targets and prevent generation of the specific rules via
        tgt_rule function.

The footer.mk is where Rules.mk gets translated into the proper
makefile.  There's not much to explain, just take a look in there.
First I memorize the targets for given directory (either from OBJS/SRCS
or from TARGETS) with appropriate directory prefix.  If there's need to
save the target specific *_(CMD|DEP|LIB) I do it.  Then I include all
the Rules.mk from the subdirectories.  Then I define the targets for
given directory either explicitly (like clean_all or clean_$(d)) or by
evaluation of the 'skeleton' mentioned above or by iterating through all
targets which do not match AUTO_TGTS and evaluating what tgt_rule
function for this target has returned.

In case you want to play with these settings make sure you understand
how make works, what are it's phases, when and how the variables are
expanded and so on.  It will save you a lot of time :).

Best regards
Andrzej