showpiece/showpiece-pi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Update README.md (#755)

Browse Source 
Remove references to 'Raspbian', and instead refer to 'Raspberry Pi OS'.

Additionally, a first pass of editing for conciseness.

Replace bookworm instructions with bullseye
This commit is contained in:
Tom Dewey 2024-02-19 14:32:58 +00:00 committed by GitHub
parent c20ce09fac
commit 69037ce9fe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 41 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
README.md
View File

@ -1,14 +1,18 @@
# pi-gen # pi-gen
Tool used to create Raspberry Pi OS images. (Previously known as Raspbian). Tool used to create Raspberry Pi OS images, and custom images based on Raspberry Pi OS,
which was in turn derived from the Raspbian project.
**Note**: Raspberry Pi OS 32 bit images are based primarily on Raspbian, while
Raspberry Pi OS 64 bit images are based primarily on Debian.
## Dependencies ## Dependencies
pi-gen runs on Debian-based operating systems. Currently it is only supported on pi-gen runs on Debian-based operating systems released after 2017, and we
either Debian Buster or Ubuntu Xenial and is known to have issues building on always advise you use the latest OS for security reasons.
earlier releases of these systems. On other Linux distributions it may be possible
to use the Docker build described below. On other Linux distributions it may be possible to use the Docker build described
below.
To install the required dependencies for `pi-gen` you should run: To install the required dependencies for `pi-gen` you should run:
@ -50,17 +54,16 @@ The following environment variables are supported:
* `IMG_NAME` **required** (Default: unset) * `IMG_NAME` **required** (Default: unset)
The name of the image to build with the current stage directories. Setting The name of the image to build with the current stage directories. Use this
`IMG_NAME=Raspbian` is logical for an unmodified RPi-Distro/pi-gen build, variable to set the root name of your OS, eg `IMG_NAME=Frobulator`.
but you should use something else for a customized version. Export files Export files in stages may add suffixes to `IMG_NAME`.
in stages may add suffixes to `IMG_NAME`.
* `PI_GEN_RELEASE` (Default: `Raspberry Pi reference`) * `PI_GEN_RELEASE` (Default: `Raspberry Pi reference`)
The release name to use in `/etc/issue.txt`. The default should only be used The release name to use in `/etc/issue.txt`. The default should only be used
for official Raspberry Pi builds. for official Raspberry Pi builds.
* `USE_QCOW2` **EXPERIMENTAL** (Default: `0` ) * `USE_QCOW2` **EXPERIMENTAL** (Default: `0` )
Instead of using traditional way of building the rootfs of every stage in Instead of using traditional way of building the rootfs of every stage in
single subdirectories and copying over the previous one to the next one, single subdirectories and copying over the previous one to the next one,
@ -73,14 +76,12 @@ The following environment variables are supported:
* `BASE_QCOW2_SIZE` (Default: 12G) * `BASE_QCOW2_SIZE` (Default: 12G)
Size of the virtual qcow2 disk. Size of the virtual qcow2 disk.
Note: it will not actually use that much of space at once but defines the Note: This is a maximum size - not a guaranteed allocation size. You may need
maximum size of the virtual disk. If you change the build process by adding to increase the default size if you are building a particularly full image, containing
a lot of bigger packages or additional build stages, it can be necessary to many packages or pre-built artefacts.
increase the value because the virtual disk can run out of space like a normal
hard drive would.
**CAUTION:** Although the qcow2 build mechanism will run fine inside Docker, it can happen **CAUTION:** Although the qcow2 build mechanism will run inside Docker, there is a known issue
that the network block device is not disconnected correctly after the Docker process has where the network block device is not disconnected correctly after the Docker process has
ended abnormally. In that case see [Disconnect an image if something went wrong](#Disconnect-an-image-if-something-went-wrong) ended abnormally. In that case see [Disconnect an image if something went wrong](#Disconnect-an-image-if-something-went-wrong)
* `RELEASE` (Default: bookworm) * `RELEASE` (Default: bookworm)
@ -89,7 +90,7 @@ The following environment variables are supported:
Debian release. However, since different releases will have different sets of Debian release. However, since different releases will have different sets of
packages available, you'll need to either modify your stages accordingly, or packages available, you'll need to either modify your stages accordingly, or
checkout the appropriate branch. For example, if you'd like to build a checkout the appropriate branch. For example, if you'd like to build a
`buster` image, you should do so from the `buster` branch. `bullseye` image, you should do so from the `bullseye` branch.
* `APT_PROXY` (Default: unset) * `APT_PROXY` (Default: unset)
@ -231,10 +232,10 @@ The following environment variables are supported:
If set, then instead of working through the numeric stages in order, this list will be followed. For example setting to `"stage0 stage1 mystage stage2"` will run the contents of `mystage` before stage2. Note that quotes are needed around the list. An absolute or relative path can be given for stages outside the pi-gen directory. If set, then instead of working through the numeric stages in order, this list will be followed. For example setting to `"stage0 stage1 mystage stage2"` will run the contents of `mystage` before stage2. Note that quotes are needed around the list. An absolute or relative path can be given for stages outside the pi-gen directory.
A simple example for building Raspbian: A simple example for building Raspberry Pi OS:
```bash ```bash
IMG_NAME='Raspbian' IMG_NAME='raspios'
``` ```
The config file can also be specified on the command line as an argument the `build.sh` or `build-docker.sh` scripts. The config file can also be specified on the command line as an argument the `build.sh` or `build-docker.sh` scripts.
@ -249,17 +250,17 @@ This is parsed after `config` so can be used to override values set there.
The following process is followed to build images: The following process is followed to build images:
* Loop through all of the stage directories in alphanumeric order * Interate through all of the stage directories in alphanumeric order
* Move on to the next directory if this stage directory contains a file called * Bypass a stage directory if it contains a file called
"SKIP" "SKIP"
* Run the script ```prerun.sh``` which is generally just used to copy the build * Run the script ```prerun.sh``` which is generally just used to copy the build
directory between stages. directory between stages.
* In each stage directory loop through each subdirectory and then run each of the * In each stage directory iterate through each subdirectory and then run each of the
install scripts it contains, again in alphanumeric order. These need to be named install scripts it contains, again in alphanumeric order. **These need to be named
with a two digit padded number at the beginning. with a two digit padded number at the beginning.**
There are a number of different files and directories which can be used to There are a number of different files and directories which can be used to
control different parts of the build process: control different parts of the build process:
@ -294,7 +295,7 @@ It is recommended to examine build.sh for finer details.
Docker can be used to perform the build inside a container. This partially isolates Docker can be used to perform the build inside a container. This partially isolates
the build from the host system, and allows using the script on non-debian based the build from the host system, and allows using the script on non-debian based
systems (e.g. Fedora Linux). The isolate is not complete due to the need to use systems (e.g. Fedora Linux). The isolation is not complete due to the need to use
some kernel level services for arm emulation (binfmt) and loop devices (losetup). some kernel level services for arm emulation (binfmt) and loop devices (losetup).
To build: To build:
@ -307,7 +308,7 @@ vi config # Edit your config file. See above.
If everything goes well, your finished image will be in the `deploy/` folder. If everything goes well, your finished image will be in the `deploy/` folder.
You can then remove the build container with `docker rm -v pigen_work` You can then remove the build container with `docker rm -v pigen_work`
If something breaks along the line, you can edit the corresponding scripts, and If you encounter errors during the build, you can edit the corresponding scripts, and
continue: continue:
```bash ```bash
@ -351,43 +352,36 @@ maintenance and allows for more easy customization.
`debootstrap`, which creates a minimal filesystem suitable for use as a `debootstrap`, which creates a minimal filesystem suitable for use as a
base.tgz on Debian systems. This stage also configures apt settings and base.tgz on Debian systems. This stage also configures apt settings and
installs `raspberrypi-bootloader` which is missed by debootstrap. The installs `raspberrypi-bootloader` which is missed by debootstrap. The
minimal core is installed but not configured, and the system will not quite minimal core is installed but not configured. As a result, this stage will not boot.
boot yet.
- **Stage 1** - truly minimal system. This stage makes the system bootable by - **Stage 1** - truly minimal system. This stage makes the system bootable by
installing system files like `/etc/fstab`, configures the bootloader, makes installing system files like `/etc/fstab`, configures the bootloader, makes
the network operable, and installs packages like raspi-config. At this the network operable, and installs packages like raspi-config. At this
stage the system should boot to a local console from which you have the stage the system should boot to a local console from which you have the
means to perform basic tasks needed to configure and install the system. means to perform basic tasks needed to configure and install the system.
This is as minimal as a system can possibly get, and its arguably not
really usable yet in a traditional sense yet. Still, if you want minimal,
this is minimal and the rest you could reasonably do yourself as sysadmin.
- **Stage 2** - lite system. This stage produces the Raspbian-Lite image. It - **Stage 2** - lite system. This stage produces the Raspberry Pi OS Lite image.
installs some optimized memory functions, sets timezone and charmap Stage 2 installs some optimized memory functions, sets timezone and charmap
defaults, installs fake-hwclock and ntp, wireless LAN and bluetooth support, defaults, installs fake-hwclock and ntp, wireless LAN and bluetooth support,
dphys-swapfile, and other basics for managing the hardware. It also dphys-swapfile, and other basics for managing the hardware. It also
creates necessary groups and gives the pi user access to sudo and the creates necessary groups and gives the pi user access to sudo and the
standard console hardware permission groups. standard console hardware permission groups.
There are a few tools that may not make a whole lot of sense here for Note: Raspberry Pi OS Lite contains a number of tools for development,
development purposes on a minimal system such as basic Python and Lua including `Python`, `Lua` and the `build-essential` package. If you are
packages as well as the `build-essential` package. They are lumped right creating an image to deploy in products, be sure to remove extraneous development
in with more essential packages presently, though they need not be with tools before deployment.
pi-gen. These are understandable for Raspbian's target audience, but if
you were looking for something between truly minimal and Raspbian-Lite,
here's where you start trimming.
- **Stage 3** - desktop system. Here's where you get the full desktop system - **Stage 3** - desktop system. Here's where you get the full desktop system
with X11 and LXDE, web browsers, git for development, Raspbian custom UI with X11 and LXDE, web browsers, git for development, Raspberry Pi OS custom UI
enhancements, etc. This is a base desktop system, with some development enhancements, etc. This is a base desktop system, with some development
tools installed. tools installed.
- **Stage 4** - Normal Raspbian image. System meant to fit on a 4GB card. This is the - **Stage 4** - Normal Raspberry Pi OS image. System meant to fit on a 4GB card.
stage that installs most things that make Raspbian friendly to new This is the stage that installs most things that make Raspberry Pi OS friendly
users like system documentation. to new users - e.g. system documentation.
- **Stage 5** - The Raspbian Full image. More development - **Stage 5** - The Raspberry Pi OS Full image. More development
tools, an email client, learning tools like Scratch, specialized packages tools, an email client, learning tools like Scratch, specialized packages
like sonic-pi, office productivity, etc. like sonic-pi, office productivity, etc.
@ -402,7 +396,7 @@ to `./stage2` (if building a minimal system).
```bash ```bash
# Example for building a lite system # Example for building a lite system
echo "IMG_NAME='Raspbian'" > config echo "IMG_NAME='raspios'" > config
touch ./stage3/SKIP ./stage4/SKIP ./stage5/SKIP touch ./stage3/SKIP ./stage4/SKIP ./stage5/SKIP
touch ./stage4/SKIP_IMAGES ./stage5/SKIP_IMAGES touch ./stage4/SKIP_IMAGES ./stage5/SKIP_IMAGES
sudo ./build.sh # or ./build-docker.sh sudo ./build.sh # or ./build-docker.sh