Project:Prefix/Manual Bootstrap
This document is probably out of date, use as hints for bootstrapping only!
How to bootstrap Gentoo Prefix on a UNIX-like system.
Bootstrapping
Introduction
Bootstrapping on a UNIX-like system can range from being fairly simple to just a downright disaster. Systems that typically belong to the "simple" group, are Mac OS X, FreeBSD and recent distributions of Linux not being SuSE or Ubuntu. The "disaster" systems are NetBSD, OpenBSD and Ubuntu: they are NOT supported. Somewhere in the middle is Solaris 10, with OpenIndiana being a shift towards the "simple" group.
Don't let yourself be scared away immediately by this. For instance, a bootstrap on Solaris 10 may be quite flawless, because many went ahead of you, and ironed out a smooth path.
In general, when bootstrapping, make sure you have a clean and lean environment. Exclude any software providing repositories such as Blastwave, Fink, MacPorts, Homebrew, ports, etc. by default, e.g. make sure your shell doesn't automatically load any environment variables that setup those repositories. Think of PATH, CFFLAGS, CFLAGS, LDFLAGS, PKG_CONFIG_PATH and the always harmful LD_LIBRARY_PATH variables. This is important, because Prefix tends to be very sensitive about this. After all, it's whole purpose is to provide all of those tools by itself without external help!
If you happen to run into trouble, don't despair (immediately). Feel free to ask in the #gentoo-prefix (webchat) IRC channel, or the gentoo-alt@gentoo.org mailing list.
Gentoo Prefix does NOT require root-privileges. It unnecessary to use a superuser account to bootstrap a Prefix installation. In fact, we highly discourage bootstrapping as the root-user!
Bootstrapping
As prerequisite, you have to have a working compiler, e.g. gcc and make installed. Without a compiler, linker, and all that is required by those to compile a program such as system headers and libraries, any Prefix bootstrap will fail almost immediately.
OS X/Mac OS
On Mac OS X systems, the compiler, linker, system headers, and libraries are provided by Xcode, or the Xcode command line tools, available through the AppStore and ADC respectively.
OpenIndiana
On OpenIndiana, you need the a compiler, system header,s and more installed using pkg. Perform the following two commands as super user:
root #pkg set-publisher -p http://pkg.openindiana.org/sfe/
root #pkg install sfe/developer/gcc developer/library/lint system/headerThe compiler and many useful other utilities will be available in the /usr/gnu/bin directory.}}
Solaris
On Solaris systems many useful utilities such as wget and gcc are located in the /usr/sfw/bin directory.
The first step is to choose a path to install into. We refer to this path as "Prefix path", stored in the EPREFIX variable. Some suggestion for the Prefix path is $HOME/gentoo. Whatever is chosen, make sure it is set in the environment before proceeding:
user $export EPREFIX="${HOME}/gentoo"tcsh users can use setenv EPREFIX "$HOME/gentoo" instead.
Next, add the following paths to the soon-to-be Prefix's PATH variable. $EPREFIX/bin, $EPREFIX/usr/bin, $EPREFIX/tmp/bin and $EPREFIX/tmp/usr/bin. Adding these paths makes sure that they will be available later on in the process.
user $export PATH="${EPREFIX}/usr/bin:${EPREFIX}/bin:${EPREFIX}/tmp/usr/bin:${EPREFIX}/tmp/bin:/usr/bin:/bin"On Solaris, add the following paths to find the GNU compiler, linker, make and some other tools: /usr/sfw/bin, /usr/sfw/<arch>-sun-solaris<version>/bin. Use
export PATH="$PATH:/usr/sfw/bin:/usr/sfw/i386-sun-solaris2.10/bin" for x86-based Solaris 10. Similar for sparc-based Solaris 10, use sparc-sun-solaris2.10 instead. Solaris 11 users have to replace the 2.10 by 2.11.Most notably on Mac OS X and Solaris systems, both 32-bit and 64-bit modes are possible. These are so-called multilib systems. Those that know what this means, and do not like the default chosen by the bootstrap script set the CHOST environment variable to an alternate preference. Solaris/OpenSolaris/OpenIndiana systems always default to 32-bit, so if you want to end up with a 64-bits native Prefix installation, then set the CHOST variable accordingly to either
x86_64-pc-solaris2.10 or sparcv9-sun-solaris2.10 for Solaris 10, use 2.11 for versions later, including OpenIndiana. Mac OS X Intel-based systems before Lion (10.7) always default to 32-bits. From Lion and on, the default is 64-bits. Those desiring a 64-bit native Prefix on pre-Lion systems should set the CHOST value to x86_64-apple-darwin9 for Leopard, or x86_64-apple-darwin10 for Snow Leopard. Those wanting to end up with a 32-bits native Prefix installation on Lion, set the CHOST value to i686-apple-darwin11.Now the PATH is set, start with downloading the bootstrap-prefix.sh script. This script require the bash shall in order to operate effectively. Systems lacking bash (typically BSD) will need to bootstrap bash. This can be performed using the bootstrap-bash.sh script. wget or curl can be used to obtain this script if they are available. Downloading them with a web-browser is also fine:
user $chmod 755 bootstrap-bash.sh; ./bootstrap-bash.sh ${EPREFIX}/tmpAfter getting bash, be sure to rehash afterward: using hash -r (sh) or rehash (csh) commands.
Stage 1
The Gentoo ebuild repository installed by default is a known to be good snapshot. This can, however, for various reasons not be good enough, in which case the latest snapshot available can be used instead. Only use this when you have problems with the known to be good snapshot. If you want to use the latest snapshot when bootstrapping can run the following export statement in the environment before proceeding:
user $export LATEST_TREE_YES=1From the directory where the bootstrap script was stored execute the following commands:
user $chmod 755 bootstrap-prefix.sh
user $${EPREFIX}/bootstrap-prefix.sh ${EPREFIX} stage1
The stage1 should have installed some basic packages necessary to run Portage, without Portage's help. When the stage1 has finished compiling successfully, Portage can be installed into the EPREFIX location.
Stage 2
user $${EPREFIX}/bootstrap-prefix.sh ${EPREFIX} stage2Running the above command will continue emerging some of the core toolchain packages that make sure we compile and link everything taking the Prefix into account. Next to that this step emerges the full set of applications and that Portage needs and removes the tools installed by stage1. It finishes things by getting an up-to-date tree (removing any hacks stage2 applied to the activated profile) and emerging everything in the @system set.
user $${EPREFIX}/bootstrap-prefix.sh ${EPREFIX} stage3Because we installed some new applications, most notably Portage, we will instruct bash to reconsider all paths we have:
user $hash -rtcsh users can use the rehash command.
Now is a good time to set the preferences for the Prefix. This includes customization such as general USE flags, CFLAGS, and MAKEOPTS in ${EPREFIX}/etc/portage/make.conf. Be conservative with CFLAGS! The stage3 function already set some moderate defaults.
Adding CPU-specific tuning flags to CFLAGS can be considered. If CPU in the system is unknown skip this note. Intel-based Mac OS X users (e.g. MacBook, CoreDuo) should at least have
-march=prescott here to avoid compilation errors due to SSE instructions not being enabled. Core2Duo users can use -march=core2. Mac OS X PPC users can use their CPU's alias to enable CPU specific tuning, e.g. -mcpu=G5 -mtune=G5. For other systems, you might simply want to use -march=<your-cpu>. Google the right value, or just forget about this setting. Note that setting a wrong value breaks things.Since we have everything in place for a self-catered rebuild, we can start the final stage to install the Prefix system. This final stage recompiles everything in the system, but now all packages can be compiled with tools from the Prefix, instead of those from the host system.
root #emerge --ask -e @systemAfter @system has emerged successfully, your Prefix will be set up properly, and you can emerge the whichever tools you choose from the Prefix tree.
Using the Prefix
To use your bootstrapped Prefix environment, you best start a shell from the Prefix, such that your path and other environment variables are set correctly. To facilitate in this, a small helper script can be created by the bootstrap script.
$ cd $EPREFIX/usr/portage/scripts
$ ./bootstrap-prefix.sh $EPREFIX startscript
After running this, a script startprefix will be present in EPREFIX. You can freely move the script to e.g. your homedir for convenience. Running the script will drop you into a Prefix shell, where for example emerge is directly at your disposal.
Enjoy Prefix!
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Fabian Groffen (grobian)
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.