[FAQ] Prerequisites for a successful buildworld/buildkernel

[I thought I would publish this once again, as I regularly have
to answer these questions.]  ;)

The below talks about the prerequisites for a successful build
(world and kernel).

On Tue, Mar 23, 2004 at 11:02:56PM -0800, Kris Kennaway wrote:
> On Wed, Mar 24, 2004 at 08:58:15AM +0200, Ruslan Ermilov wrote:
> > On Tue, Mar 23, 2004 at 05:23:16PM -0800, Kris Kennaway wrote:
> > > This guy doesn't seem to have a full /usr/include (e.g. it's missing
> > > db.h), but he claims to have done a buildworld before buildkernel,
> > > which fails due to the missing db.h.  Shouldn't buildkernel be using
> > > the internal set of headers prepared by buildworld, instead of relying
> > > on the outdated host environment?
> > > 
> > Yes, src/sys/ is self-sufficient, except for some tools used during
> > buildkernel, aicasm is one of them.
> 
> ...which was the content of my question.  So, upgrades (buildworld
> then buildkernel) apparently don't work if you don't have /usr/include
> installed to begin with.
> 
Of course not.  For a successful buildworld (and buildkernel),
it is required to have a complete and non-broken build system,
as we still build lot of tools using the host toolchain.

Under "host toolchain" we mean what's installed now: compiler,
binutils, headers in /usr/include, libraries in /usr/lib (and
/lib in 5.x), yacc(1), lex(1), install(1), etc.

Tools that are built using the host toolchain are:

- bootstrap-tools, those that have known backward compatibility
  issues.  For example, when a new option is added to install(1)
  and we start using it in src/ makefiles, we need to upgrade
  install(1) so that we can use it during installworld and
  installkernel.  The reason why it should be built using host
  toolchain should be obvious:

  - we're going to _run_ the new install(1) binary under the
    currently running kernel, which may not contain all new
    syscalls that may be in the new libc.

  - we may be building for a different target architecture.

- cross-tools, those that have a notion of TARGET_ARCH, and
  produce different output for different target architectures;
  the most known of them are C compiler and binutils.  We
  configure them to run on the current machine, using the
  currently running kernel and libraries (host toolchain),
  but produce output understood by a target machine, possibly
  of a different hardware architecture.

- build-tools.  These are special small helper applications
  that are built and used only during buildworld/buildkernel.
  For example, "mkinit" for bin/sh and "aicasm" for the
  Adaptec SCSI drivers.

Once we get that far, we build the rest with MACHINE_ARCH set
to TARGET_ARCH.  We use these newly built *-tools to complete
the target toolchain: build/install headers, then libraries,
to a temporary location (WORLDTMP) known to cross-tools.  Now
that we have a complete target toolchain, we use it to build
the rest of the world/kernel.

(The build(7) manpage badly needs to mumble something about
the prerequisites for a successful buildworld/buildkernel.)


Cheers,
-- 
Ruslan Ermilov
FreeBSD committer
ru_at_FreeBSD.org