.Dd August 13, 2017
.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 p Ar PHASE
.Op Fl s
.Op Fl v Ar VERSION


.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.  Specifically, x86 and x86_64
require
.Xr syslinux 1
to be installed.  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 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.
.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


.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
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.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
EXTRA_MIRROR=i525 LDARCH=i386 SIGNING_KEY=/etc/portage/adelie.key ./build-cd -a x86


.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


.Sh BUGS

There is no way to specify packages that should only be included on a full disc
or live disc.  All disc types have the same packages installed.