From 5f62cff66916db54f3be0c9fbc6198253ef7b6f0 Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Sat, 13 Jan 2024 17:04:53 +0100
Subject: doc: Switch to tar-based installation

The tar-based installation is more difficult to explain but has the
advantage that the partition size is maximized from the beginning. This
is way easier than resizing the partition after the installation.
---
 doc/documentation.tex | 52 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 33 insertions(+), 19 deletions(-)

(limited to 'doc/documentation.tex')

diff --git a/doc/documentation.tex b/doc/documentation.tex
index aa45cf8..53452ee 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -96,16 +96,16 @@ The given chapter contains documentation about how to produce a
 Alpine Linux for the Raspberry Pi can be downloaded from the Alpine
 Linux\footnote{\href{https://alpinelinux.org/}{https://alpinelinux.org/}}
 download page. This section describes the installation procedure for the
-variant targeting the AArch64 architecture provided as a compressed image file.
-It can be downloaded and verified against a checksum with the \texttt{wget} and
-\texttt{sha256sum} utilities.
+variant targeting the AArch64 architecture provided as a compressed tar
+archive. It can be downloaded and verified against a checksum with the
+\texttt{wget} and \texttt{sha256sum} utilities.
 
 \begin{verbatim}
 wget https://dl-cdn.alpinelinux.org/alpine/v3.19/releases\
-    /aarch64/alpine-rpi-3.19.0-aarch64.img.gz
+    /aarch64/alpine-rpi-3.19.0-aarch64.tar.gz
 wget https://dl-cdn.alpinelinux.org/alpine/v3.19/releases\
-    /aarch64/alpine-rpi-3.19.0-aarch64.img.gz.sha256
-sha256sum -c alpine-rpi-3.19.0-aarch64.img.gz.sha256
+    /aarch64/alpine-rpi-3.19.0-aarch64.tar.gz.sha256
+sha256sum -c alpine-rpi-3.19.0-aarch64.tar.gz.sha256
 \end{verbatim}
 
 The image has to be flashed to a SD card which will be inserted into the
@@ -124,22 +124,36 @@ sda           8:0    1  59,5G  0 disk
 `-sda1        8:1    1  59,5G  0 part
 \end{verbatim}
 
-If the correct SD card file path is determined the downloaded image can be
-decompressed with \texttt{gzip} and flashed with \texttt{dd}. The \texttt{dd}
-call requires the privileges of the root user which might be temporarily
-accessed by prefixing \texttt{sudo}.
+The SD card has to be formatted with a single bootable FAT32 partition. This
+can be achieved with the command line program \texttt{parted}. First a
+\texttt{msdos} partition table has to be created followed by a partition taking
+the full size of the SD card. The boot flag of the partition is enabled and a
+FAT32 file system is created with \texttt{mkfs.vfat}. All of these operations
+require \texttt{root} privileges.
 
-\textbf{Warning}: \texttt{dd} will write the image to the specified block
-device. If that block device is the primary hard drive of the computer it will
-do that without further confirmation. This will make the operating system of
-the PC unusable.
+\textbf{Warning:} These operations might cause data loss if the wrong device is
+specified. It has to be asserted that not the wrong block device (e.g. the PC
+disk) is chosen.
 
-After flashing it is required to synchronize all write operations to the card
-with \texttt{sync}.
+\begin{verbatim}
+parted /dev/<name> mklabel msdos
+parted /dev/<name> mkpart primary fat32 0% 100%
+parted /dev/<name> toggle 1 boot
+mkfs.vfat /dev/<name>1
+\end{verbatim}
+
+After the file system is created the downloaded Alpine Linux tar archive has to
+be extracted to it. A temporary mount point can be created with
+\texttt{mktemp}. After mounting with \texttt{mount} the archive can be
+extracted with \texttt{tar}. Finally the file system is unmounted and it is
+waited for all buffered write operations to the SD card with \texttt{sync}.
+Also these command require \texttt{root} privileges.
 
 \begin{verbatim}
-gzip -d alpine-rpi-3.19.0-aarch64.img.gz
-dd if=alpine-rpi-3.19.0-aarch64.img of=<sd-card-path>
+mountpoint=$(mktemp -d)
+mount /dev/<name>1 "$mountpoint"
+tar -C "$mountpoint" -xf alpine-rpi-3.19.0-aarch64.tar.gz
+umount /dev/<name>1
 sync
 \end{verbatim}
 
@@ -154,7 +168,7 @@ After logging in with the username \texttt{root} and no password basic system
 configuration on Alpine Linux can be done interactively with
 \texttt{setup-alpine}. The Alpine Linux installation
 guide\footnote{\href{https://wiki.alpinelinux.org/wiki/Installation}{https://wiki.alpinelinux.org/wiki/Installation}}
-contains further details. When a diskless installation is choosen the
+contains further details. When a diskless installation is chosen the
 configuration changes have to be made persistent with the \texttt{lbu} command.
 Otherwise they will be lost on the next reboot.
 
-- 
cgit v1.2.3-70-g09d2

