4.9 Building your system with calculate-assemble

Rationale

calculate-assemble is designed for building a bootable LiveCD image, to be installed on a hard disk or on a USB-Flash. We have used this utility, namely, to build Calculate Linux weekly stages.

Features

  • Supported architectures are i686 and x86_64.
  • Compilation profiles are Gentoo and Calculate profiles for the abovementioned architectures.
  • Parallel building of several distributions is supported.
  • A 32-bit distribution can be assembled on a 64-bit system.

Installation

The calculate-assemble package is part of Calculate Utilities 2 and requires calculate-install, calculate-builder, calculate-templates and calculate-lib packages.

You can install the latest version of calculate-assemble from the calculate overlay, included by default in all Calculate Linux distributions. If you are a Gentoo user, install the app-portage/layman package if you do not have it yet and enter:

layman -a calculate

You will then be able to install calculate-assemble with emerge, as usual.

Using calculate-assemble

Your new customized system will be built with the cl-assemble and cl-make tools, then you will need cl-image (which is part of sys-apps/calculate-builder) to create the ISO image.

Files required

To build your system, you have to be connected to the Internet and to have downloaded the following:

Required:
  • a stage3 Gentoo image, or a Calculate Linux ISO; an image you have built on your own will do as well. If you are going to build from a stage3, first create the directory /var/calculate/remote/stages and put the archive of a 32-bit or a 64-bit system in it. If you prefer to work with a Calculate Linux image, put the latter in the directory /var/calculate/remote/linux.
Optional:
  • the Portage tree archive. Create the /var/calculate/remote/snapshots directory and put the latest version of the Portage tree in it.

Before starting, you may want to read the help page for cl-assemble:

cl-assemble --help

Calculate will use about 15 GB of your hard disk to build your system. If you intend to create binary packages, they will also need disk space (approx. 5 GB). The image itself will need around 2 GB or more, depending on what you want.

It will be compiled on a separate hard disk partition. The final image and the binary packages are stored in the /var/calculate/remote directory; you should allot 2 GB or 7 GB of free disk space, respectively, in /var/calculate/remote, as well as some free 15 GB on your HDD.

Prepare for the building procedure

To prepare your system for what will follow, enter:

cl-assemble

Main options

  • -d <disk>, --disk <disk> specifies the partition alloted for building.
    Make sure the partition you specify does not contain any useful information. If needed, backup your data. All information on this partition will be lost!
  • --march <arch> specifies the architecture (i686 or x86_64)
    A list of compatible profiles will be created depending on the architecture.
  • -p <profile>, --profile specifies the system profile. To view the list of available profiles, use "list" as the argument for this option.
  • --source <source> specifies the source image. The accepted values are stage or <shortname>.
    Your source may be a stage3 Gentoo image or any Calculate Linux image. In this latter case, you should specify the short name of the distribution, e.g. --source=CDS.
  • --ver <ver> specifies the system's version.
    Integer or floating, period-separated. Using two periods in the system version is supported. If not specified, the build date (year, month, day) will be used for naming.
  • --name=<shortname></name></subname> speficies the distribution's name: short, full, suffix (e.g. CLD/Calculate Linux Desktop/KDE)

Additional options

  • --sync <rsync> modifies the Portage mirror according to rsync preferences. You can use a Git mirror since v2.2.25-r4.
  • --no-unmount prevents from unmounting the partition with the new system, if an error occurs. Since version 2.2.25-r4, calculate-assemble does not unmount partitions by default.
  • --unmount unmounts the partition if an error occurs.
  • --nobuildpkg prevents froms creating binary packages.

When the system is getting ready to be built, the partition you have chosen will be formatted and mounted into /mnt/<profile>. Formatting will be done with the same filesystem that was used previously, if supported by the utility.

The preparing procedure includes the following steps:

  • Formatting the partition (for rapid cleaning)
  • Unpacking the source image
  • Unpacking the Portage tree (if there should be an archived Portage tree stored in /var/calculate/remote/snapshots)
  • Setup with the assemble/prepare templates
  • Mounting /dev, /dev/shm, /dev/pts, /proc, /sys, /var/calculate/remote
  • Updating the Portage tree
  • Installing layman
  • Loading the calculate overlay
  • Setup with the assemble/setup templates
  • Enabling calculate-install for package configuration (performed if using one of Calculate profiles)
  • Installing portage
  • Fetching the kernel sources (from the calculate-sources package; if the "vmlinuz" USE flag is on, emerge will compile and install the kernel)
  • Installing v86d
  • Updating baselayout and installing openrc (performed if using one of Calculate profiles)
  • Installing man-db (performed if using one of Calculate profiles)
  • Executing etc-update
  • Creating the games group (35) (groups are created to lock the IDs)
  • Creating the plugdev group (440)
  • Creating the scanner group(441)
  • Unmounting the source image

Checking dependencies

Once the system is ready to be built, you should check the dependencies and correct them if needed, by unmasking the packages you will need. To do so, execute:

cl-make -D <-p profile>

Note that here and later on, you can specify the short name of the distribution profile. For instance, for "calculate/desktop/CLD/amd64" you may put "CLD", "CLD/amd64", "desktop/amd64" or "amd64$". The latter contains a "$" which stands for the profile name's end. If you are building only one distribution at a time, the profile name can be omitted.

Build your system

To build the system, enter:

cl-make -m <-p profile>

All required packages and their source codes will be put in the /var/calculate/remote/distfiles directory. If you have not set the --nobuildpkg option, binary packages will be archived in /var/calculate/remote/assemble/<profile>/packages.

Update the new system

Using the cl-make utility is not limited to the building procedure, but also allows you to update the system image. To do so, first prepare your system with cl-assemble as described above; the system image must be specified in the --source option.

Then update your newly built system by entering:

cl-make -u <-p profile>

Update includes the following steps:

  • Setup with the assemble/prepare and assemble/setup templates
  • Updating the Portage tree
  • Executing emerge -u perl
  • Executing perl-cleaner all (if needed)
  • Executing emerge --noreplace calculate-meta
  • Executing emerge -D --newuse world
  • Executing emerge -uD world
  • Executing emerge --depclean
  • Executing module-rebuild -X rebuild (if needed)
  • Executing revdep-rebuild -i (if needed)
  • Executing prelink -afmR (if needed)
  • Merging nvidia-drivers
  • Cleaning the binary repository (if needed)
  • Executing eix-update

You can update your system manually, without updating the Portage tree. You might want to do so if the Portage tree was already updated manually, or if you used chroot to modify something related to package merging. In this case, execute:

cl-make -U <-p profile>

Remember, you can always get access to the system with chroot; just type:

chroot /mnt/<profile>

Example:

chroot /mnt/calculate-desktop-CLD-amd64-developer

All slashes "/" in the name of the <profile> directory will be replaced with dashes "-".

If you are building a 32-bit distribution on a 64-bit system, note that you have to run chroot as shown below to access it:

linux32 chroot /mnt/<profile>

For instance:

linux32 chroot /mnt/calculate-desktop-CLD-x86-developer

Create a bootable image

To create a bootable ISO image after building or updating your system, type:

cl-image -p <profile> iso

The distribution will be saved in the directory /var/calculate/remote/assemble/<profile>/linux/. Beside the ISO image, a file containing the checksums and yet another one, containing the list of programs, will be created.

Break the build procedure

If you want to stop building the system and unmount all partitions that were used for that, execute:

cl-make -p <profile> --break

Settings

At build time, all settings of your new system(s) are recorded in /etc/calculate/assemble.env. Please delete this file if you had to reboot your computer unexpectedly; remove the empty directorie(s) within /mnt/<profile> as well, if needed.

To make building easier, the templates have internal variables; you can assign them values in the calculate.env file located either in /etc/calculate/, /var/calculate/ or /var/calculate/remote/. You can do this in the [assemble] section in calculate.env that you will have to create first.
The available variables are:
  • cl_assemble_sync stands for the RSYNC server for synchronization;
  • cl_assemble_branch stands for the repository branch wherer the Portage tree and the overlay are stocked (master, by default);
  • cl_assemble_available_dev stands for the available disk partitions that can be used by calculate-assemble.

Examples:

[assemble]
cl_assemble_sync = 192.168.0.2/gentoo-portage
cl_assemble_available_dev = /dev/sda5,/dev/sda6,/dev/sda7

[assemble]
cl_assemble_sync = git://git.calculate.ru/dev/portage.git
cl_assemble_branch = develop
cl_assemble_available_dev = /dev/sda5,/dev/sda6,/dev/sda7
Note:
  • You can set up and use a local rsync or Git server.
  • One or more comma-separated partitions can be specified in the cl_assemble_available_dev variable. In this case, Calculate will choose randomly among the available partitions.
Thank you!