Categories: Install
Author: Matt Housh
Herein is the process used to build the CRUX installation ISO image.
Whether you're just curious about the process or want to customize the image in some way, this document details how to build it.
This process should be usable on pretty much any modern x86-64 Linux system, though it's recommended that you use CRUX as it will be the easiest option. Everything in the process is possible on a non-CRUX system but will require you to figure out the proper names of packages needed to satisfy dependencies, install the CRUX package utilities (pkgutils, prt-utils), etc.
A minimal CRUX virtual machine or chroot on a non-CRUX system is a good option. In fact I would recommend this as you're less likely to run into any .footprint mismatches or the like that might arise from an ISO package finding an optional dependency that alters its .footprint during the build, breaking the bootstrap process.
In this build system you'll need the following software installed to complete the build:
If you're not using CRUX, you'll need the C/C++ compilers as well as make, autotools, etc. - with CRUX these will already be installed.
More packages will be required to build the entire set of packages on the ISO, as you'll see later.
First you'll need to get the ISO source from git. It can be viewed via gitweb here.
Clone the ISO tree from git to your preferred local location, for example /usr/src/iso:
# git clone -b 3.5 git://crux.nu/system/iso.git /usr/src/iso
You'll also need copies of the core, opt, and xorg ports trees. If you're using CRUX you can simply copy them from your local system into the ISO tree like so:
# ports -u
# rsync -a /usr/ports/{core,opt,xorg} /usr/src/iso/ports/
If not using CRUX, clone them via git as with the iso tree:
# git clone git://crux.nu/ports/core.git /usr/src/iso/ports/core # git clone git://crux.nu/ports/opt.git /usr/src/iso/ports/opt # git clone git://crux.nu/ports/xorg.git /usr/src/iso/ports/xorg
NOTE: The rest of this document assumes you're working in /usr/src/iso (or wherever you cloned the ISO source tree).
# cd /usr/src/iso
Any time you update or customize ports in the ISO's ports subdir it's a good idea to run prtwash (from CRUX's prt-utils) on the tree to clean up old packages, source tarballs, and obsolete files:
# prtwash ports/*/*
If this is the first time you're building the ISO you'll need to satisfy the dependencies for all the packages the ISO includes as they're compiled during the bootstrap process. This is simple (though time-consuming) in CRUX as the ISO tree already contains a full list of the packages provided:
# make -B packages.all # prt-get depinst $(cat packages.all)
This can take a long time if you don't have many of the required packages installed. On a non-CRUX system you'll be required to install the same dependencies but it's up to you to find them in your chosen distribution's package manager.
The ISO includes plain text versions of the Handbook and Release Notes. These are fetched with links like so:
# (cd doc/handbook; ./get_wiki_handbook; ./get_wiki_release_notes)
When all requirements and dependencies are satisfied, the packages provided on the ISO are bootstrapped like so:
# make bootstrap
This takes a long time as all packages are built if they don't already exist in the ports subdir, then rebuilt twice in a chroot environment (similar to a 3-stage gcc build). If this process fails for some reason (like a missed dependency), check the log.stageX files created in the ISO tree where X is the stage: 0, 1, or 2.
NOTE: If you're just building a CRUX ISO to make a change to the kernel or boot environment but you're NOT changing any packages, you can skip this step after it has completed once. There's no benefit to bootstrapping a new set of packages if no changes to packages have been made.
Once the long bootstrap process has finished, the last step is to create the ISO itself. The iso target in the Makefile takes care of this:
# make iso
If all went well this will produce crux-3.5.iso and crux-3.5.md5 files.