parabolaiso/docs/README.build

INDEX
-----

* Build requirements
* Image types generated by mkparabolaiso.
* File format for aitab.
* Why the /isolinux and /parabola/boot/syslinux directories?
* Git branches and build configurations.
* Building Parabola GNU/Linux-libre live media.


*** Build requirements

** For mkparabolaiso script needs these packages (build host):
 + squashfs-tools          for mksquashfs
 + libisoburn              for xorriso
 + btrfs-progs             for mkfs.btrfs (optional)

** For configs/releng build.sh needs theses packages (build host):
 + dosfstools              for mkfs.vfat
 + lynx                    for fetching the latest installation guide

** For these hooks needs these packages (on target root-image)
* parabolaiso
 + (none)
* parabolaiso_loop_mnt
 + (none)
* parabolaiso_pxe_common
 + mkinitcpio-nfs-utils    for ipconfig
* parabolaiso_pxe_nbd
 + nbd                     for nbd-client
* parabolaiso_pxe_http
 + curl                    for curl
* parabolaiso_pxe_nfs
 + mkinitcpio-nfs-utils    for nfsmount
* parabolaiso_shutdown
 + (none)


*** Temporary filesystems generated by mkparabolaiso.

* work/x86_64/root-image/
  => # x86_64 chroot install target
* work/i686/root-image/
  => # i686 chroot install target
* work/root-image/
  => # transient per-arch hard copy of each work/<ARCH>/root-image/
  => # transient source for each per-arch ./work/root-image.fs
* work/root-image.fs
  => # transient source for per-arch root-image.fs.sfs
* work/mnt/root-image/
  => # mountpoint for packing work/root-image.fs
* work/iso/parabola/x86_64/root-image.fs.sfs or
  work/iso/parabola/x86_64/root-image.sfs
  => # r/o loopback filesystem for live x86_64 environment (see "Image types " section)
* work/iso/parabola/i686/root-image.fs.sfs or
  work/iso/parabola/i686/root-image.sfs
  => # r/o loopback filesystem for live i686 environment (see "Image types " section)


*** Image types generated by mkparabolaiso.

* image-name.sfs     SquashFS image with all files directly on it.
                     [read-only, no dm-snapshot is used]
* image-name.fs.sfs  SquashFS with only one file inside (image-name.fs),
                     which is an image of some type of filesystem
                     (ext4, ext3, ext2, xfs, btrfs), all files reside on it.
                     [read-write, via COW image with dm-snapshot]


*** File format for aitab.

The aitab file holds information about the filesystems images that must be
created by mkparabolaiso and mounted at initramfs stage from the parabolaiso hook.
It consists of some fields which define the behaviour of images.

# <img>         <mnt>                 <arch>   <sfs_comp>  <fs_type>  <fs_size>

<img>      Image name without extension (.fs .fs.sfs .sfs).
<mnt>      Mount point.
<arch>     Architecture { i686 | x86_64 | any }.
<sfs_comp> SquashFS compression type { gzip | lzo | xz }.
<fs_type>  Set the filesystem type of the image
           { ext4 | ext3 | ext2 | xfs | btrfs }.
           A special value of "none" denotes no usage of a filesystem.
           In that case all files are pushed directly to SquashFS filesystem.
<fs_size>  An absolute value of file system image size in MiB.
           (example: 100, 1000, 4096, etc)
           A relative value of file system free space [in percent].
           {1%..99%} (example 50%, 10%, 7%).
           This is an estimation, and calculated in a simple way.
           Space used + 10% (estimated for metadata overhead) + desired %


*** Why the /isolinux and /parabola/boot/syslinux directories?

The /isolinux directory holds files needed for the ISOLINUX boot loader
module of SYSLINUX. ISOLINUX can not find config files on
/parabola/boot/syslinux, like other boot loaders modules (SYSLINUX, PXELINUX).


*** Git branches and build configurations.

The parabolaiso git repo consists of several branches; only some of which are useful for building ISOs. Others exist only for merging with upstream. The build configurations on the 'master' branch are used to build the official release ISOs.

Note that the ISOs can built by an unprivileged user with sudo but all files under the configs/releng/root-image directory must be owned by root during the build process. The configs/releng/build.sh script manages this automatically; but it will cause problems when checking-out or switching branches if the git command is not also run as a superuser. To avoid a corrupted working tree, the entire contents of the configs/releng/root-image directory should be chown'ed to the unprivileged user before running any git command that would modify them.

  $ sudo chown -R user:group root-image/

** Branches not intended for building ISOs.

* helper/rebrand - Branch to aid rebranding. Branch master of archiso.git plus Parabola rebranding of filenames and file contents. It is used as an intermediate step to merge Archiso, to aid git detecting file renames.

* rebrand/releng - Rebranding branch. helper/rebrand leaving only the directory of releng inside configs/, renamed to profile/. It is possible to create equivalent branches for other ISO variants.

* rebrand/baseline - Rebranding branch. Same concept as rebrand/releng.

* release - Contains snapshots of releases, with commits showing updates of each profile. It should be updated only by make dist.

* release-branches - Snapshots of last commits (HEAD) of each specified profile branch. Same concept as the branch release. It should be updated only by make dist-branches. Using it is not strictly necessary. It does not exist in the public Parabola repository parabolaiso.git.

** Branches for building ISOs.

* baseline - Profile branch "baseline". master is separated from baseline to its own branch. This is now different from Archiso, and enables merging the releng profile in other profiles that use releng as a base.

* master - Profile branch a.k.a "releng". Branch rebrand/releng with Parabola customizations. The files outside configs/ which are common to all variants are packaged from this branch.

NOTE: This distinction is in the process of being deprecated or reverted. In the future, there will be only one 'releng' profile; which is capable of building any of the variant editions via command-line options to a single ./build.sh script on the master branch. See README.package_lists and the '-E' ./build.sh option below for more information.

** Package Lists

See README.package_lists for information regarding the package lists files schema.


*** Building Parabola GNU/Linux-libre Live ISOs.

First decide if you want to build one of the standard releases,
or if you plan to do development on parabolaiso itself.

* To build the standard releases, install parabolaiso via pacman.
  # pacman -S parabolaiso
  # cd /usr/share/parabolaiso/configs/releng

* Or, for parabolaiso development, clone parabolaiso from git.
  # pacman -R parabolaiso
  # pacman -S parabolaiso-data git
  # git clone git://git.parabola.nu/packages/parabolaiso.git
  # cd parabolaiso/configs/releng

* For parabolaiso development, there are some extra dependencies.
  * For 'baseline' ISOs
  # pacman -S squashfs-tools libisoburn rsync --needed

  * For 'releng' derrived ISOs
  # pacman -S squashfs-tools libisoburn dosfstools --needed

* In either case, if you are a Parabola dev, and are making a release ISO,
  you can install the following packages, in order to make a complete release,
  ready to publish, with all metadata files (torrent, checksums, etc)
  # pacman -S mktorrent rhash --needed

* Build one or more ISOs.
  # ./build.sh                                   # dual-architecture SystemD/CLI
  # ./build.sh -T i686                           # 32-bit x86 target SystemD/CLI
  # ./build.sh -T x86_64                         # 64-bit x86 target SystemD/CLI
  # ./build.sh -E OpenRC/CLI  -O                 # OpenRC/CLI for offline install
  # ./build.sh -E OpenRC/LXDE -O                 # OpenRC/LXDE for offline install
  # ./build.sh -E SystemD/LXDE                   # SystemD/LXDE for net-install
  # ./build.sh -E SystemD/MATE -S                # SystemD/MATE with speech and braille
  # ./build.sh -V "`date +%Y.%m.%d.%H.%M`-alpha" # development filename

NOTE: The commands above are only some examples. Run `build.sh -h` for the complete options.
NOTE: This script needs to be run on an x86_64 ArchLinux derrivative
NOTE: Specifying a single architecture with the -T option builds in half of the time
      and results in the ISO being about half of the size as the dual-architecture ISO.
      If the -T option is omitted, the default value of 'dual' will be assumed.
NOTE: Omitting the -O option results in the ISO being about half of the size yet again;
      but will require an internet connection to install the target system.
NOTE: The argument to the -E option must consist of an init/wm pair separated by a '/' slash,
      and must correspond to one each of the 'VALID_INITS' and 'VALID_GUIS'
      as defined in the 'build.sh' script. If the -E option is omitted,
      the default value of 'SystemD/CLI' will be assumed.
      This will determine which package lists will be used. Although the package lists
      files are named in lowercase, this argument may contain captial letters.
      It will be printed verbatim in the titles of the boot menu and the MOTD.
NOTE: The rebuild.sh script can be handly during development. Among other things,
      it can delete the work directory while retaining the chroot package caches
      (the 'wipe' option); which will speed up repeated clean re-builds.