Significantly refactor build-cd script, and add a man page woo

1 files changed, 161 insertions, 0 deletions

diff --git a/adelie-build-cd.8 b/adelie-build-cd.8
new file mode 100644
index 0000000..a56d019
--- /dev/null
+++ b/adelie-build-cd.8
@@ -0,0 +1,161 @@
+.Dd January 29, 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
+
+
+.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 "-p PHASE" -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.
+.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
+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 SIGNING_KEY
+If you specify
+.Fl f
+you may sign the created package index by pointing to your private key in
+.Ev SIGNING_KEY .
+.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.