1 files changed, 179 insertions, 0 deletions
diff --git a/doc/NOTES b/doc/NOTES
new file mode 100644
index 0000000..733033d
--- /dev/null
+++ b/doc/NOTES
@@ -0,0 +1,179 @@
+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.