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.

(Older boostrap instructions can be found [wiki:BoostrappingOld here].)

== The Quick Bootstrap Procedure ==

If you just like to bootstrap a supported platform/architecture for some reason, there is an automated shortcut for doing it. In the root you'll find a GNU makefile 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.gmk 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.



== Troubleshooting ==

 * 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.
 * If sed bootstrapping fails with build errors in the {{{intl}}} subdir and the above trick doesn't work, just remove {{{intl}}} and {{{po}}} directories from the SUBDIRS list in {{{src/sed/Makefile.am}}}.
 * 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.
 * On FreeBSD you might have to override the autoreconf and tell autoreconf what aclocal and automake is called.
{{{
ACLOCAL=aclocal19 AUTOMAKE=automake19 ./kBuild/env.sh gmake -f bootstrap.gmk AUTORECONF=autoreconf259
}}}