BUILD SYSTEM IN GENERAL AND MK-CONFIGURE IN PARTICULAR IS A COMPLEX
SYSTEM. THIS FILE CONTAINS UNORDERED NOTES ABOUT HOW TO USE
MK-CONFIGURE EFFICIENTLY. I HOPE THESE NOTES WILL BE VALUABLE ADDON TO
MK-CONFIGURE(7) REFERENCE AND HELP USERS UNDERSTAND MK-CONFIGURE.
TAKE A NOTE THAT THESE NOTES ARE UNSORTED.

***

For building projects with /usr prefix, run the following.

   export PREFIX=/usr SYSCONFDIR=/etc VARDIR=/var
   mkcmake all
   mkcmake install

Packagers may use the following for creating a package using
unprivileged user.

   mkdir /tmp/destdir
   mkcmake install DESTDIR=/tmp/destdir

***

mk-configure supports out-of-tree builds. Most of functionality is
supported by bmake. Examples are below.

1)
   mkdir /tmp/xxxproj-obj
   mkcmake MAKEOBJDIR=/tmp/xxxproj-obj

In this case all objects and temporary files are created in
/tmp/xxxproj-obj.  Obviously, this may work if different subprojects
doesn't produce files with the same name. This features is supported
directly by bmake.

2)
   mkdir /tmp/xxxproj-obj
   mkcmake MAKEOBJDIRPREFIX=/tmp/xxxproj-obj

Here all objects and temporary files are saved to
${MAKEOBJDIRPREFIX}${.CURDIR} directory. This features is also
supported by bmake.

3)
   mkdir /tmp/xxxproj-obj
   env MKRELOBJDIR=yes MAKEOBJDIR=/tmp/xxxproj-obj mkcmake

Unlike example 2) subdirectories under /tmp/xxxproj-obj for temporary
files won't contain ${SRCTOP}. The variable MKRELOBJDIR is provided by mk-c.

***

Even if you project is trivial, that is consists of single executable
or library, I'd recommend to use mkc.subprj.mk in the top-level Makefile.
In provides better flexibility and easier work for packagers.

***

It's very important to understand what is a recursive target.
See variable TARGETS.

***

The variable TARGETS is a way to extend mk-c functionality.
See examples/hello_TARGETS.

***

Look at examples/hello_superfs/Makefile.inc.
There you'll find a cool mk-configure's feature.

***

If you want to override values for MKC_CHECK_* checks, run mkcmake
with additional parameters, like this

   mkcmake all HAVE_HEADER.stdio_h=1 HAVE_HEADER.stdlib_h=1

See mkc.configure.mk section in mk-configure.7 for details.

***

There are several ways of passing additional information from
top-level project to subprojects:
  - environment variables via .export and .export-env bmake directives.
  - EXPORT_VARNAMES and NOEXPORT_VARNAMES variables from mkc.subprj.mk.
  - Makefile.common and Makefile.inc files.

***

For prettifying mkcmake output, one can use

  export SHRTOUT=yes
  mkcmake all

***

If your top-level Makefile looks like this

  Makefile:
    SUBPRJ = libA:progA libB:progB
    .include <mkc.subprj.mk>

one can use

  mkcmake all-progB

for building progB subproject without probA and libA. In this case libB
will also be built as it is a dependency. The same for

  mkcmake install-progB
  mkcmake test-progB
  ...

and others. "all", "install", "test" and others are listed in variable
TARGETS.

***

In traditional BSD mk files bsd.subdir.mk is allowed in any
subdirectory. The same is true for mk-configure. However, for better
flexibility it is recomended to have mkc.subprj.mk in the top-level
Makefile and specify the whole dependency graph of subpojects in
it. This allows, for example, building and testing any subproject
separately by running one command from top-level directory,
i.e. "mkcmake all-sub/sub/project". In this case all required
dependencies (and nothing else) will be built recursively. For running
mkcmake in subproject's directory, set the variable SRCTOP.

***

SUBPRJ variable (mkc.subprj.mk) may contain subprojects, not
associated with any subdirectory. Such subprojects may be used as "the
name of subprojects collection". I call them "virtual
subprojects". If, for example, you're developing traditional UNIX
tools, you may have such projects as POSIX_tools BSD_tools,
bin_tools, sbin_tools etc.

***

Subprojects from SUBDIR (mkc.subdir.mk) and SUBPRJ (mkc.subprj.mk) may
have slashes inside.

***

NODEPS variable may be used for stripping unnecessary
dependencies. This is especially useful for target "test". In the
following example "mkcmake test" tests only programs but not libraries
(recursively). That is, it runs targets "test-tools/prog1",
"test-tools/prog2", "test-tools/prog3" and "test-tools/prog4"
but "test-libs/foo" and others.

Example:
   SUBPRJ  = libs/foo:tools/prog1
   SUBPRJ += libs/bar:tools/prog2
   SUBPRJ += libs/foo:tools/prog3 libs/bar:tools/prog3
   SUBPRJ += libs/qux:tools/prog4

   NODEPS +=       test-libs/*:test test-libs/*:test-tools/*

   .include <mkc.subprj.mk>

***

Makefile.common and Makefile.inc included implicitely by subprojects
may be used for common code. For examples, in these files one can do
something like this.

  VERSION        = 1.2.3
  INTEXTS_REPLS += version ${VERSION}

for replacing @version@ with real version.

***

If your project consists of libraries and executables, use
mkc.subprj.mk and its LIBDEPS variable. Even if you prefer shared
libraries, users will be able to link them statically with a help
STATICLIBS variable specified in environment. For this to work you
have to use += for STATICLIBS in Makefiles.

***

Some projects may provide some special variables for configuring.
You can see them by running the following command.

  mkcmake help

mk-configure itself provides some things to configure.
