an approach to define various meanings of words 'prefix', 'root' and 'host'

gentoo-words-prefix-root-host.txt (text/plain), 4.78 KB, created by Michael Haubenwallner (RETIRED) on 2018-06-14 15:08:13 UTC

This is a try to shed some light on the various meanings of the words
'prefix' and 'root' in combination with the word 'host', eventually
expanded to various cross situations in Gentoo Linux and Gentoo Prefix.

Feel free to correct if my knowledge is wrong or incomplete.

There are different binary formats, each bound to one of the three 'host
triplet' values: CBUILD, CHOST and CTARGET.  Each 'host triplet' usually
is "arch-vendor-kernel", but also "arch-vendor-kernel-libc" may be used.

For each of these 'host triplets', the words 'prefix' and 'root' have
different meaning, and different variable names eventually.

I'm also using the term *right now* here: This refers to when a package
manager (read "emerge") is running and executing the ebuild phases.

Another term is the 'final merge destination': It is based on the top
level file system directory in the current runtime environment (which
may be a chroot as well), and is well known as ROOT="/" or ROOT="".


CBUILD:
Describes the runtime environment where 'build system' packages (bash,
python, portage and similar) *are* runnable *right now* - with their
package files available via the 'final merge destination'.

CBUILD specific 'prefix' value:
This is what the 'build system' packages *have* built in to load their
internal files from - *right now* via the 'final merge destination'.

CBUILD specific 'prefix' variable name for the ebuild environment:
EAPI <3: none (the empty string, without support for Prefix at all)
EAPI <7: EPREFIX (without support for cross prefix)
EAPI =7: BROOT
Portage internal: PORTAGE_OVERRIDE_EPREFIX, overriding portage's builtin
CBUILD specific 'prefix' value, to *behave* as being built for the BROOT
'prefix' value and loaded *right now* via the 'final merge destination',
while portage's internal files really are somewhere else.

CBUILD specific 'root' value:
This always is the 'final merge destination', to guarantee for the
'build system' packages to be runnable *right now*:
EAPI <7: "/"
EAPI =7: "" (the empty string)

CBUILD specific 'root' variable name for the ebuild environment:
Because of the constant value, there is no separate CBUILD specific
'root' variable name defined at all.


CHOST:
Describes a runtime environment where 'host system' packages *will be*
runnable in, when available via the 'final merge destination' there.

However, when these 'host system' packages *later on* are used to build
other packages, they are called a 'build system' again, probably with
another CHOST value - with the original CHOST value moved to CBUILD.

CHOST specific 'prefix' value:
This is what the 'host system' binaries *get* built in to load their
internal files from - *later on*, when the whole package is available
via the 'final merge destination' in a CHOST runtime environment.

CHOST specific 'prefix' variable name for the ebuild environment:
EAPI <3: none (the empty string, without support for Prefix at all)
EAPI <7: EPREFIX (without support for cross prefix)
EAPI =7: EPREFIX

CHOST specific 'root' value:
This is where the 'build system' package manager *does* merge the just
built (or unpacked from binpackage) 'host system' package files into.

CHOST specific 'root' variable names for the ebuild environment:
EAPI <7: ROOT, with "/" as the 'final merge destination'
EAPI =7: ROOT, with "" as the 'final merge destination'
EAPI =7 also defines SYSROOT: When different from ROOT, specifies an
additional readonly location for the toolchain (running in the CBUILD
runtime environment creating CHOST binaries *right now*), to search for
CHOST headers+libraries that are not necessary for running 'host system'
packages in a CHOST runtime environment.

When ROOT is the 'final merge destination', we should expect the CBUILD
runtime environment to provide a CHOST runtime environment as well, and
the 'build system' can run the 'host system' packages too *right now*,
even if the CHOST value differs from the CBUILD value.

When ROOT *is not* the 'final merge destination', the 'host system'
packages are dedicated to be visible via the 'final merge destination'
in some CHOST runtime environment *later on* eventually, and the 'build
system' should not run 'host system' packages via the CBUILD runtime
environment, even if the CHOST value is equal to the CBUILD value.


CTARGET:
Describes a runtime environment for binaries, which the toolchain that
is built *right now* will create binaries for, when running in some
CHOST runtime environment *later on*.

If the CTARGET value is different from CHOST while building a toolchain
package, the resulting toolchain package is called a cross toolchain.

There is no need for a CTARGET specific 'prefix' or 'root' value, because
the only need for CTARGET is to inform the toolchain about the binary
format it *will* have to deal with, once it is running via the 'final
merge destination' in a CHOST runtime environment.