Bootstrapping kBuild isn't something anyone but porters, maintainers and perhaps package people will ever have to do. kBuild users on supported platforms will never have to concern themselves with it unless working under a no-binary policy or similar.

Bootstrapping is only strictly required
 1. when porting kBuild to a new OS/architecture, or 
 1. if compatibility with older tools is broken during development on the trunk.


== The Quick Bootstrap Procedure ==

If you just like to bootstrap a supported platform/architecture for some reason, this is a automated shortcut for doing it. There is a GNU make compatible makefile in the root called source:trunk/bootstrap.gmk. Read the ASSUMPTIONS found at the top of the file very carefully before executing it. Then do this:
  1. {{{kBuild/env.sh make -f bootstrap.kmk SRCDIR=`pwd`}}}
  1. {{{kBuild/bin/x.y/}}} is not (re-)populated and you can use env.sh + kmk.
  1. If you want to make 100% sure, do {{{kBuild/env.sh kmk rebuild PATH_INS=`pwd`}}}.


== The Real Bootstrap Procedure ==

 1. Modify kBuild/env.sh to accept the uname output.
    A kBuild BUILD_TARGET / BUILD_PLATFORM OS name must be decided upon at this point. If the architecture and/or processor is new to kBuild, new (unique) names need to be found here as well.
 1. Modify kBuild/header.kmk to accept and correctly configure the platform / target OS.
 1. Run kBuild/env.sh to configure the kBuild environment.
 1. Port and bootstrap kmk.[[BR]]
    The bootstrap kmk build is made using the GNU automake/autoconf setup of GNU make. Which means that the initial port of the kmk code has to be done in that environment. Since porting isn't a common day thing, nor is bootstrapping this is just something we have to live with.
     1. The source is derived from the GNU make CVS and not a GNU make tarball. This means all the auto-stuff has to be created first. Run this from the src/gmake directory:
{{{
autoreconf -i
}}}
        If you have a broken automake/autoconf installation you may want try do each autoreconf step manually:
{{{
aclocal -I config
autoconf
autoheader
automake --add-missing --copy --no-force
}}}
        For solving problems check out the autoreconf manual page and README.cvs.
     1. Create a subdirectory {{{obj}}} for to do the build within. This avoids confusion later and simplifies cleanup. Enter the directory.
     1. Run configure:
{{{
../configure
}}}
     1. Build it:
{{{
make
}}}
        Don't expect it to build on the first try on a new platform. Fix build errors and repeat until success or you give up in frustration...
     1. Copy (or symlink) the resulting {{{kmk}}} to {{{kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/}}}. You may have to create this directory first.
     1. The kmk bootstrapping is now done (unless of course, bugs in the port needs addressing).
 1. Copy or symlink a bournshell compatible shell (ash is preferred) to {{{kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/kmk_ash}}}. {{{/bin/sh}}} or {{{/bin/bash}}} is usually a good choice.
 1. Configure/Port and build the kmk, ash, sed, and kDep* (all found in source) using the bootstrap kmk. It's recommended to take one directory at a time and start with kmk since that's almost done now. The job that's required for each directory is roughly this:
     1. Check if anything special is required in Makefile.kmk for your OS.
     1. If it's a autoconf based tool run configure to (re)generate the config.h for your OS.[[BR]]
        These are usually cached as {{{config.h.$(BUILD_TARGET)}}} files.[[BR]]
        Note. You might wish to check if it builds and checks out cleanly in the autoconf/automake framework.
        ''Applies to sed and kmk/gmake.''
     1. Try build:
{{{
kmk
}}}
        Address build errors (and warnings) until it builds successfully.
     1. If it's a autoconf/automake based tool and it got a testharness/suite, it is recommended to test the binary you've just built in it.
        ''Applies to sed and to some degree kmk/gmake.''
     1. Copy the resulting binary/binaries to {{{kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/}}}.
     1. Move on to the next tool.
 1. When everything builds and you've copied the new binaries to the kBuild/bin/x.y location, it's time to rebuild everything using the new binaries.
     1. Remove the {{{out/}}} directory found in the root of the kBuild tree.
     1. Run {{{kmk}}} from the root.
     1. Replace binaries in {{{kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/}}} with the new ones from {{{out/$BUILD_TARGET.$BUILD_TARGET_ARCH/$BUILD_TYPE/kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/}}}.
     1. It doesn't hurt to repeat this sequence once more.
 1. Create patches and submit to bird along with a release build of the tools binaries.



== Trouble Shooting ==

 * On Solaris cp doesn't like being called kmk_cp. So, when building src/gmake for the first time, it might be necessary to add {{{CP=/bin/cp}}} to the make command line.
 * The sed and GNU make configure scripts might not like the system sed. Try find a GNU sed binary or bootstrap it yourself. Copy you sed program to kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/ (without any prefix) and it'll be used instead of the system sed.
 * Use a real YACC when compiling ash. GNU bison will not work (yyerrstatus undeclared error). You can add YACC=/path/to/real/yacc to the kmk command line if it's not in the PATH.

== The OLD Bootstrap Procedure (before r95x) ==

 1. Modify env.sh to accept the uname output.
 1. Modify header.kmk to accept and correctly configure the platform / target OS.
 1. Run kBuild/env.sh to configure the kBuild environment.
 1. Copy unix like tools from you system to kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/. kBuild requires all ash (bash is recommended), cat, cp, echo, install, ln, mkdir, mv, rm, rmdir and (gnu) sed. The kBuild copies must be prefixed with {{{kmk_}}}. These tools will be replaced later in the bootstrapping.
 1. Configure and build GNU sed:
    1. Go to the src/sed directory.
    1. Run aclocal, autoconf and automake in src/sed if needed.
    1. Create and enter src/sed/obj.
    1. Run ../configure --disable-nls.
    1. Run make
    1. Copy config.h to src/sed/config.h.$BUILD_TARGET (or similar, see Makefile.kmk). 
    1. Copy sed/sed[.exe] to kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/kmk_sed[.exe].
 1. Configure and build plain GNU Make:
    1. Run aclocal, autoconf and automake in src/gmake if needed.
    1. Create and enter src/gmake/obj.
    1. Run ../configure --disable-nls.
    1. Run make
    1. Copy config.h to src/gmake/config.h.$BUILD_TARGET (or similar, see Makefile.kmk). Append empty string #defines for LOCALEDIR, LIBDIR, INCLUDEDIR and ALIASPATH (see config.h.linux).
    1. We've now got our own make binary which will be used further down.
 1. Build src/gmake using the GNU Make we just made:
    1. Go to the src/gmake directory.
    1. obj/make -f Makefile.kmk
    1. When it breaks fix the compiler / linker error and redo the previous step.
    1. Copy out/$BUILD_TARGET.$BUILD_TARGET_ARCH/release/kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/ to kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/.
 1. Rebuild everything using kmk (which should now be in the path):
    1. Run kBuild/env.sh (or continue in the shell from the previous step).
    1. Go to the root.
    1. kmk BUILD_TYPE=release rebuild
    1. Fix build breaks and repeat the previous step.
    1. Copy out/$BUILD_TARGET.$BUILD_TARGET_ARCH/release/kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/ to kBuild/bin/$BUILD_TARGET.$BUILD_TARGET_ARCH/.
 1. Add and commit the changes (including the binaries).

Note! On GNU/Linux make sure you have a real yacc install. GNU bison is not sufficiently compatible with yacc to make src/ash (from NetBSD) happy.