.Dd February 02, 2020
.Dt ADELIE-BUILD-CD 8 SMM
.Os "Adélie Linux"
.Sh NAME
.Nm adelie-build-cd
.Nd create an Adélie Linux live CD image or install media
.Sh SYNOPSIS
.Nm
.Op Fl a Ar ARCH
.Op Fl f
.Op Fl k Ar KIND
.Op Fl p Ar PHASE
.Op Fl s
.Op Fl v Ar VERSION
.Op Fl -cache Ar CACHE
.Op Fl -no-cache
.Sh DESCRIPTION
.Nm
creates a live CD image or installer CD image for Adélie Linux using
.Xr apk 8
and
.Xr mkisofs 8 .
.Bl -tag -width "-v VERSION" -offset indent -compact
.It Fl a Ar ARCH
You may specify any architecture available in the Adélie repository for
.Ar ARCH ;
however, some architectures may require you to have additional utilities
present on your system to be made bootable.  This defaults to the currently
running system's architecture as reported by
.Xr uname 1 .
.It Fl f
Specifies that a full installation image should be created, including a
.Pa packages/
directory containing .apk files that can be used for an offline install.  If
this flag is not specified, a live image will be created instead.
.It Fl k Ar KIND
Specifies the 'kind' of image creation to make.  This defaults to the 'live'
kind.  Kinds are similar to a Fedora 'spin'; see the
.Sy Kinds
section.
.It Fl p Ar PHASE
Specifies the phase of image creation to make as specified in the
.Sy Phases
section.
.It Fl s
If you specify
.Fl f
and
.Fl s ,
the created package index will be signed using the same key configured in
.Xr abuild.conf 5 .
This requires the
.Xr abuild 1
suite of utilities to be available.
.It Fl v Ar VERSION
Specifies the version of Adélie Linux to use for the created ISO.
.It Fl -cache Ar CACHE
Specifies the location of the cache directory to use, to speed up
.Xr apk 8
runs. Defaults to the system cache in
.Pa /etc/apk/cache
for the same architecture, or none. This directory must exist, or it is ignored.
.It Fl -no-cache
Do not use any cache directory for this
.Xr apk 8
run; pull all packages from the repository.
.El
.Ss Phases
The
.Nm
utility defines the following phases for
.Fl p ,
which can be run independently, or can be run in order by specifying the special
.Sy all
phase.
.Bl -tag -width "install" -offset indent -compact
.It clean
Erase all temporary files.  Typically required for predictable build results.
.It install
Install packages to the squash root.  If
.Fl f
is specified, additionally create the package root and copy .apk files to it.
.It initrd
Generate the initrd contents in the initrd root, and create the initrd file
from it.
.It iso
Run
.Xr mksquashfs 1
on the squash root, copy the kernel to the CD root, run any
architecture-specific scripts necessary to make the CD bootable, and then run
.Xr mkisofs 8
to create the .ISO file.
.It all_but_iso
Run all of the above phases, except iso, in the above order.
.It all
Run all of the above phases in the above order.  This is the default if
.Fl p
is not specified.
.El
.Ss Kinds
Kinds are a specific set of packages and optional startup scripts that define
a specific 'kind' of CD image.  Official Kinds include Horizon, KDE Live, and
MATE Live.  You can specify your own by creating a
.Pa packages/kind/$KIND
file containing the names of packages you wish (one per line).  Additionally,
you may optionally create a
.Pa services/kind/$KIND
file containing the names of services to start up in the default runlevel (one
per line).
.Sh ENVIRONMENT
.Bl -tag -width "EXTRA_MIRROR" -offset indent -compact
.It Ev Sy LDARCH
If the musl ld library file is different from the apk arch (such as ppc vs
ld-musl-powerpc.so.1), you may specify the name of the ld architecture as
.Ev LDARCH .
.It Ev Sy EXTRA_MIRROR
For architectures that have subarchitectures (such as x86 with i486 and i525),
you may specify the extra mirror directory to use as
.Ev EXTRA_MIRROR .
.It Ev Sy MY_URL
Use a custom URL for downloading.  This does not change the URLs written to
/etc/apk/repositories on the generated image.
.Pp
For instance, a speedy way to generate a testing ISO on a builder would be to
specify MY_URL=/srv/packages.
.El
.Sh FILES
.Bl -ohang -width "iso-params-$ARCH" -offset indent -compact
.It Pa iso-params-$ARCH
A list of additional parameters to provide to
.Xr mkisofs 8
when generating the ISO image for the specified architecture.  This is used to
specify the correct layout for bootable discs on that architecture.
.Pp
.It Pa packages/arch/$ARCH
A list of architecture-specific packages to install on the created media, in
addition to the default packages installed on every architecture.  This is
typically used for bootloaders and firmware manipulation packages.  It can also
be used to provide further debugging tools (such as
.Xr gdb 1
or
.Xr strace 1
and so on) on architectures that are still experimental.
.Pp
.It Pa post/arch/$ARCH.sh
If this file exists and is executable, it will be run just before
.Xr mkisofs 8
to do any final preparation to the disc root before creating the image.
.El
.Sh EXAMPLES
adelie-build-cd -a x86_64
.Pp
LDARCH=powerpc adelie-build-cd -a ppc
.Pp
LDARCH=i386 SIGNING_KEY=/etc/portage/adelie.key ./adelie-build-cd -a pmmx
.Sh SEE ALSO
.Xr mksquashfs 1 ,
.Xr apk 8 ,
.Xr mkisofs 8 .
.Sh HISTORY
The
.Nm
command first appeared during the 1.0 ALPHA1 phase.  It is written in portable
.St -p1003.2a-92
shell language.  Any deviation from the standard should be considered a bug.
.Sh AUTHORS
.An A. Wilcox
.Aq awilfox@adelielinux.org