diff --git a/pages/dev/_meta.json b/pages/dev/_meta.json index 5739f99..70b95d1 100644 --- a/pages/dev/_meta.json +++ b/pages/dev/_meta.json @@ -4,5 +4,6 @@ "pacstall-101": "Pacscript 101", "hotfix-101": "Creating Hotfixes", "ubxi": "UBXI", + "os": "Image Builder", "wiki": "Wiki Page Tips" } diff --git a/pages/dev/os/GitHub-Workflow.png b/pages/dev/os/GitHub-Workflow.png new file mode 100644 index 0000000..d3f08b6 Binary files /dev/null and b/pages/dev/os/GitHub-Workflow.png differ diff --git a/pages/dev/os/_meta.json b/pages/dev/os/_meta.json new file mode 100644 index 0000000..5871881 --- /dev/null +++ b/pages/dev/os/_meta.json @@ -0,0 +1,6 @@ +{ + "intro": "Introduction", + "github-actions": "Building using GitHub Actions", + "repo-structure": "Repository Structure", + "build-system": "Tools Used" +} diff --git a/pages/dev/os/build-system.mdx b/pages/dev/os/build-system.mdx new file mode 100644 index 0000000..5a065a3 --- /dev/null +++ b/pages/dev/os/build-system.mdx @@ -0,0 +1,49 @@ +--- +title: How Images are built +description: Tools used +--- + +import { Callout } from 'nextra/components' + +## Tools (Build System) Utilized + +Inside the `rhino-linux/os` repository is where the production-ready images of RL are made. +This was originally forked from [Vanilla-OS's ISO builder](https://github.com/Vanilla-OS/live-iso) which is forked from [Ubuntu Cinnamon's ISO builder](https://github.com/ubuntucinnamon/iso-builder-devel). +Images are built from scratch thanks to the Debian's [`live-build`](https://salsa.debian.org/live-team/live-build) tool in an automated fashion thanks to shell scripts. + +Different branches target different devices such as: +`Main` generic target, +`rpi` with Raspberry Pi code, +and `pinetab` and `pinephone` targeting those respectively. + +### GitHub Actions + +While it is possible for manual building of each different architecture (e.g. `x86_64`) or type (e.g. `pinetab`), +this is time consuming, so the team can schedule a [GitHub Workflow that builds all images](./github-actions) in a efficient and repeatable manner. + +### Installer + +RL primarily uses Calamares, a multi-distribution modular installer. Except for Raspberry Pi and Pine devices where it is unnecessary. +Compared to Ubuntu's Calamares does not have a dependency on Snap and has the advantage of [being customized](./calamares) with our branding. + +### Bootloader + +For generic targets, GRUB and isolinux is used, u-Boot for Raspberry Pi targets, and Extlinux to install SYSLINUX to Pinephone and pinetab. +* GRUB: `etc/config/boatloaders/grub-pc` & https://github.com/rhino-linux/grub/tree/main (branding) +* Isolinux: `etc/config/boatloaders/isolinux` +* U-Boot: `scripts/setup-system-boot.sh` +* Extlinux: `etc/config/boatloaders/extlinux` + + + **Note:** Some bootloaders may be in other branches, but are unused. + + + +### Package Management + +For most things, APT is used, packages installed are under `etc/config/package-lists.calamares`: +* `desktop.list.chroot_install` (unavailable on Raspberry Pi & Pine devices): Packages installed by Calamares onto system +* `desktop.list.chroot_live` (unavailable on Raspberry Pi & Pine devices): Packages only in the live environment +* `pool.list.binary`: Packages on the disk image + +Pacstall packages are installed under `etc/config/hooks/live/099-install-custom-apps.chroot`. diff --git a/pages/dev/os/github-actions.mdx b/pages/dev/os/github-actions.mdx new file mode 100644 index 0000000..9c4aa33 --- /dev/null +++ b/pages/dev/os/github-actions.mdx @@ -0,0 +1,16 @@ +--- +title: Using GitHub Actions +description: How to build using GitHub Actions +--- + +import { Callout } from 'nextra/components' + + + **Notice:** This guide assumes familiarity with [manually building images](./intro) + + +To build an image, simply go to the *Actions* tab of the GitHub repository, run the +`Rhino Linux Image Generation (Meta) [Legacy Workflow]` Action, defined under `legacy.yml` file +![An image of a successful GitHub Actions Workflow](./GitHub-Workflow.png) + +After completion, the disk images can be downloaded below the matrix (as pictured above). diff --git a/pages/dev/os/intro.mdx b/pages/dev/os/intro.mdx new file mode 100644 index 0000000..6be0025 --- /dev/null +++ b/pages/dev/os/intro.mdx @@ -0,0 +1,58 @@ +--- +title: Building an image +description: How to build an image of RL +--- + +import { Callout } from 'nextra/components' + +## How to get started building Rhino Linux images + + + **Warning:** This can only be built with the latest release of Ubuntu and derivatives such as Rhino Linux! + + + + **Important:** Looking how to do release builds? look at [building using Github Actions](./github-actions) + + +### Instructions + +First, make sure the proper dependencies are installed: +``` +sudo apt-get update && sudo apt-get install --reinstall debootstrap mtools dosfstools qemu-user-static binfmt-support dpkg-dev git +``` + +The repository can be cloned into by Git (defaulting to the generic branch): + + **Important:** Depending on the target, clone either the `rpi`, `pinetab`, or `pinephone` branch instead. + +``` +git clone https://github.com/rhino-linux/os.git && cd ./os +``` + +Next, to install the live build dependency: +``` +sudo dpkg -i debs/live-build_*_all.deb +``` + +Unfortunately, live-build has to be patched to support Ubuntu `devel` archives so multiple commands have to be run: +``` +sudo mv /usr/share/debootstrap/functions functions && sudo patch -i 0002-remove-WRONGSUITE-error.patch && sudo mv functions /usr/share/debootstrap/functions && sudo cp binary_grub-efi /usr/lib/live/build/binary_grub-efi +``` + +The last step to get the repository running is making the scripts executable: +``` +chmod -R +x build.sh etc/auto/config etc/terraform.conf etc/ +``` + +Finally, images can be made: +``` +sudo ./build.sh etc/terraform.conf +``` + + + **Note:** Images can be rebuilt using `sudo ./build.sh etc/terraform.conf` + + +The resulting image to flash is found under `builds/[architecture]` where `[architecture]` is either `amd64` or `arm64`. +The in addition, an SHA256 and SHA512 checksum is created to verify. diff --git a/pages/dev/os/repo-structure.mdx b/pages/dev/os/repo-structure.mdx new file mode 100644 index 0000000..e61a622 --- /dev/null +++ b/pages/dev/os/repo-structure.mdx @@ -0,0 +1,35 @@ +--- +title: Structure +description: Brief repo structure +--- + +## [Repository Structure](https://github.com/rhino-linux/os) +This is subject to change, but here is the general of this repository: + +```. +├── 0002-remove-WRONGSUITE-error.patch -> for devel apt archives +├── binary_grub-efi -> Modified grub script for RL +├── build.sh -> Main build script +├── debs +│   └── live-build_20220505_all.deb -> Modified for RL +├── etc +│   ├── auto +│   │   └── config -> Is used to setup live-build +│   ├── config +│   │   ├── bootloaders -> Stores Bootloader configurations +│   │   │   ├── grub-pc -> Is used in UEFI boot +│   │   │   └── isolinux -> Is used in BIOS instead of Grub +│   │   ├── hooks +│   │   │   └── live -> Each step (shell script) that live-build runs incrementally from 000 to 999 +│   │   ├── includes.binary -> Media information +│   │   ├── includes.chroot -> Files that are directly included in media +│   │   └── package-lists.calamares -> Calamares installer packages +│   │   ├── desktop.list.chroot_install -> Apt packages to install onto disk +│   │   ├── desktop.list.chroot_live -> Packages only necessary while booting off a disk image (live boot) +│   │   └── pool.list.binary -> Packages on media (mostly firmware) +│   └── terraform.conf -> RL specific distribution information (shouldn't needed to be changed) +├── LICENSE +├── README.md +├── rebuild-list -> Don't worry about this file +└── ub2r.sh -> Script that converts Ubuntu into Rhino Linux +```