From bfb2eac6d9bf99f3b00910252df8d0fda915ae7d Mon Sep 17 00:00:00 2001 From: emmett1 Date: Tue, 2 Jun 2026 23:52:35 +0800 Subject: docs updated --- docs/apkg_helpers.md | 86 ++++++++++ docs/bootloader.md | 88 ++++++++++ docs/install.md.new | 312 +++++++++++++++++++++++++++++++++++ docs/networking.md | 27 +-- docs/packagemanager.md.new | 397 +++++++++++++++++++++++++++++++++++++++++++++ docs/readme.md | 3 +- docs/using_autils.md | 245 ++++++++++++++++++++++++++++ docs/writing_abuild.md | 229 ++++++++++++++++++++++++++ 8 files changed, 1367 insertions(+), 20 deletions(-) create mode 100644 docs/apkg_helpers.md create mode 100644 docs/bootloader.md create mode 100644 docs/install.md.new create mode 100644 docs/packagemanager.md.new create mode 100644 docs/using_autils.md create mode 100644 docs/writing_abuild.md diff --git a/docs/apkg_helpers.md b/docs/apkg_helpers.md new file mode 100644 index 00000000..bbc54648 --- /dev/null +++ b/docs/apkg_helpers.md @@ -0,0 +1,86 @@ +# apkg helper scripts + +autils includes several helper scripts that work alongside `apkg` for package inspection, cleanup, and maintenance. See `man ` for full details on each command. + +## apkg-chroot + +Enter a chroot environment with virtual filesystems mounted. Useful for building packages or performing system maintenance inside an alternative root. + +```sh +apkg-chroot /mnt/alice # launch interactive shell +apkg-chroot /mnt/alice apkg -i mypkg # run a command inside the chroot +``` + +Must be run as root. Mounts `/dev`, `/proc`, `/sys`, `/run`, copies `/etc/resolv.conf`, and cleans up all mounts on exit. + +## apkg-clean + +List stale `.spm` package files and orphaned source tarballs that are no longer referenced by any current package recipe. Pipe to `xargs rm` to actually clean up. + +```sh +apkg-clean # list all unreferenced files +apkg-clean -p # list only stale packages +apkg-clean -s # list only stale sources +apkg-clean | xargs rm # remove them +``` + +## apkg-deps + +Show runtime library dependencies of an installed package. Uses `ldd` to find shared libraries needed by the package's binaries, then maps those libraries back to the packages that provide them. + +```sh +apkg-deps mypkg +``` + +Useful for discovering implicit runtime dependencies not listed in the formal `depends` file. Excludes the package itself and base system packages (gcc, musl, binutils, glibc). + +## apkg-foreign + +List installed packages that are not found in any configured repository. These may have been installed from an external source or had their recipes removed. + +```sh +apkg-foreign +``` + +Takes no arguments; outputs one package name per line. + +## apkg-genabuild + +Scaffold a new package recipe from a source URL. Parses the name and version from the URL and creates a directory with skeleton `abuild` and `info` files. + +```sh +apkg-genabuild https://example.com/mypkg-1.2.3.tar.gz +apkg-genabuild https://github.com/user/repo/archive/v1.0.tar.gz myname +``` + +Special handling for GitHub tag archives, PyPI packages (prefixes `python-`), and CPAN packages (prefixes `perl-`). An optional second argument overrides the derived package name. + +## apkg-orphan + +List orphan packages: packages that are installed and exist in a repository, but have no other installed package depending on them. These may be safe to remove. + +```sh +apkg-orphan +``` + +Takes no arguments; outputs one package name per line. + +## apkg-purge + +Remove a package and all its dependencies that are no longer needed by any other installed package. This is a "deep" removal compared to `apkg -r` which only removes the specified package. + +```sh +apkg-purge mypkg # dry-run: show what would be removed +apkg-purge -p mypkg # actually purge from the system +``` + +## apkg-redundantdeps + +Find redundant entries in `depends` files. A dependency is redundant if another listed dependency already pulls it in transitively. + +```sh +apkg-redundantdeps mypkg # check one package +apkg-redundantdeps # check all packages +apkg-redundantdeps -f mypkg # fix by removing redundant entries +apkg-redundantdeps -f # fix all packages +``` diff --git a/docs/bootloader.md b/docs/bootloader.md new file mode 100644 index 00000000..bc6bbd47 --- /dev/null +++ b/docs/bootloader.md @@ -0,0 +1,88 @@ +# Bootloader + +This document covers installing and configuring the two bootloaders available in Alice Linux: Limine and GRUB. + +## Limine + +Limine is a modern, lightweight bootloader supporting BIOS and UEFI. + +Install the package: + +``` +# apkg -I limine +``` + +### BIOS + +Deploy Limine to the target disk: + +``` +# limine bios-install /dev/sdX +``` + +### UEFI + +Copy the Limine EFI executable to the EFI system partition: + +``` +# mkdir -p /boot/EFI/BOOT +# cp /usr/share/limine/BOOTX64.EFI /boot/EFI/BOOT +``` + +### Configuration + +Create `/boot/limine.conf`: + +``` +timeout: 5 + +/Alice Linux + protocol: linux + kernel_path: boot():/vmlinuz + cmdline: root=/dev/sda2 rw loglevel=3 quiet + module_path: boot():/initrd-linux +``` + +Use `boot()` to reference the partition where `/boot` resides, or specify the partition directly with `uuid()` or a path like `hd(0,2)`. + +For full configuration options, see the [Limine documentation](https://github.com/limine-bootloader/limine/blob/trunk/CONFIG.md). + +## GRUB + +GRUB is the GNU Grand Unified Bootloader, supporting UEFI on x86_64 only. + +Install the package: + +``` +# apkg -I grub +``` + +### Install + +Install GRUB for UEFI (requires the EFI system partition mounted at `/boot`): + +``` +# grub-install --target=x86_64-efi --efi-directory=/boot +``` + +### Configuration + +Generate the GRUB configuration file: + +``` +# grub-mkconfig -o /boot/grub/grub.cfg +``` + +GRUB settings are controlled by `/etc/default/grub`. Key options: + +- **`GRUB_DEFAULT`**: Default menu entry (default: `0`) +- **`GRUB_TIMEOUT`**: Seconds before booting the default entry (default: `5`) +- **`GRUB_CMDLINE_LINUX_DEFAULT`**: Kernel command line arguments +- **`GRUB_GFXMODE`**: Framebuffer resolution (default: `auto`) +- **`GRUB_DISABLE_OS_PROBER`**: Disable probing for other operating systems (default: enabled for security) + +After editing `/etc/default/grub`, regenerate the config: + +``` +# grub-mkconfig -o /boot/grub/grub.cfg +``` diff --git a/docs/install.md.new b/docs/install.md.new new file mode 100644 index 00000000..b0322b5c --- /dev/null +++ b/docs/install.md.new @@ -0,0 +1,312 @@ +# Install Alice + +Here is a guide to installing Alice Linux on your computer using the chroot method. You can do this from your existing Linux distribution or from a live environment, such as Alice Live or another Linux distribution. Make sure your chosen environment has the necessary partitioning tools, filesystem tools, and extraction tools. + +## Get Alice rootfs tarball + +Download the Alice rootfs tarball from the [release](https://codeberg.org/emmett1/alicelinux/releases) page, along with its `sha256sum` file. +``` +$ curl -O +$ curl -O .sha256sum +``` + +Verify the checksum of the Alice rootfs tarball. +``` +$ sha256sum -c alicelinux-rootfs-20240525.tar.xz.sha256sum +alicelinux-rootfs-20240525.tar.xz: OK +``` + +## Prepare the partition and filesystem + +Prepare the partition and filesystem of your choice. In this guide, I will use `ext4` as an example. +``` +# cfdisk /dev/sdX +# mkfs.ext4 /dev/sdXY +``` + +Mount your created partition somewhere. In this guide, I will use `/mnt/alice` as the mount point. +``` +# mkdir /mnt/alice +# mount /dev/sdXY /mnt/alice +``` + +## Extract the Alice rootfs tarball + +Extract the Alice rootfs into the mounted partition. +``` +$ tar xvf alicelinux-rootfs-*.tar.xz -C /mnt/alice +``` + +## Enter chroot + +First, chroot into Alice. (Replace `/mnt/alice` with your chosen mount point) +``` +# /mnt/alice/usr/bin/apkg-chroot /mnt/alice +``` + +Any further commands after this will be executed inside the Alice environment. + +## Configure apkg.conf + +Once we have the repositories cloned, we need to configure `apkg`. `apkg` is Alice's package build system (or package manager). By default, Alice does not provide an `apkg` config file (yes, `apkg` can work without a config file), but we need to create one. The `apkg` config file should be located at `/etc/apkg.conf` by default. Let's create one. + +First, we set `CFLAGS` and `CXXFLAGS`. Alice base packages are built using `-O3 -march=x86-64 -pipe`. You can use these settings or change them to your preference. +``` +# echo 'export CFLAGS="-O3 -march=x86-64 -pipe"' >> /etc/apkg.conf +``` + +And use whats in `CFLAGS` for `CXXFLAGS`. +``` +# echo 'export CXXFLAGS="$CFLAGS"' >> /etc/apkg.conf +``` + +Next set `MAKEFLAGS`. I will use `6` for my `8 threads` machine. +``` +# echo 'export MAKEFLAGS="-j6"' >> /etc/apkg.conf +``` + +I'm also going to set `NINJAJOBS` here. Without it, `ninja` will use all threads of your machine when compiling. +``` +# echo 'export NINJAJOBS="6"' >> /etc/apkg.conf +``` + +Next, we need to set the package's build scripts path (I'll call it `package repos`) so `apkg` can find them. The `APKG_REPO` variable can accept multiple values for multiple `package repos`. + +Alice provides two (2) `package repos` (at the time of this writing): `core` and `extra`. `core` contains all base packages, and `extra` includes other packages beyond the base. + +I'm gonna use directory `/var/lib/repos/core` and `/var/lib/repos/extra` for `core` and `extra` repos respectively. +``` +# echo 'APKG_REPO="/var/lib/repos/core /var/lib/repos/extra"' >> /etc/apkg.conf +``` + +You can also create a directory the community repo. +> NOTE: The community repo is not held to the same standards as the official repos. +> Additionally all repo paths must be declared in the APKG_REPO variable, separated by a single space. +``` +# echo 'APKG_REPO="/var/lib/repos/core /var/lib/repos/extra /var/lib/repos/community"' >> /etc/apkg.conf +``` + +Next, we will set up directories for `packages`, `sources`, and `work`. By default, these directories are inside the package template, but we will change them to `/var/cache/pkg`, `/var/cache/src`, and `/var/cache/work` respectively. You can change these to any location where you want to store these files. + +First, create the directories. +``` +# mkdir -p /var/cache/pkg +# mkdir -p /var/cache/src +# mkdir -p /var/cache/work +``` + +Then add these paths to `/etc/apkg.conf`. +``` +# echo 'APKG_PACKAGE_DIR=/var/cache/pkg' >> /etc/apkg.conf +# echo 'APKG_SOURCE_DIR=/var/cache/src' >> /etc/apkg.conf +# echo 'APKG_WORK_DIR=/var/cache/work' >> /etc/apkg.conf +``` + +## Configure reposync.conf + +`reposync` is a tool to sync package templates from git repositories. Add remote repos for `core` and `extra` into `/etc/reposync.conf`. The format of remote repos in `reposync.conf` is `||`. +``` +# echo 'https://codeberg.org/emmett1/alicelinux|core|/var/lib/repos/core' >> /etc/reposync.conf +# echo 'https://codeberg.org/emmett1/alicelinux|extra|/var/lib/repos/extra' >> /etc/reposync.conf +``` + +If you also want the community repo, add it as well. +> NOTE: The community repo is not held to the same standards as the official repos. +``` +# echo 'https://codeberg.org/emmett1/alicelinux|community|/var/lib/repos/community' >> /etc/reposync.conf +``` + + +Now run `reposync` to sync latest package templates. +``` +# reposync +``` + +After setting up our `package repos`, make sure `apkg` can find the packages. We can use `apkg -s ` to search for packages. +``` +# apkg -s sway +swayidle +swaybg +swaylock +sway +``` + +Lets combine with `-p` flags to show path or package templates. +``` +# apkg -p $(apkg -s sway) +/var/lib/repos/extra/sway +/var/lib/repos/extra/swaylock +/var/lib/repos/extra/swaybg +/var/lib/repos/extra/swayidle +``` + +If the output appears, then we are good to go. + +## Full system upgrade/rebuild + +On the first install, we should upgrade the system first. + +Before we do, install development packages first. +``` +# apkg -I meson cmake pkgconf libtool automake perl +``` + +> NOTE: use upppercase 'i' for solve dependencies, lowecase 'i' without solve dependencies. + +Now lets upgrade our system. +``` +# apkg -U +``` + +> NOTE: Use uppercase `U` for a system upgrade, and lowercase `u` to upgrade a specific package of your choice. + +If you changed `CFLAGS` and `CXXFLAGS` to something other than the default, it's a good time to perform a full rebuild first. In this case, you can skip upgrading the system because performing a full rebuild will already use the latest version in `package repos`. +``` +# apkg -u $(apkg -a) +``` + +> NOTE: Add the `-f` flag to force rebuild of existing prebuilt package. +> NOTE: `apkg -a` prints all installed packages on the system. + +## Install kernel + +You can configure your own kernel from [kernel.org](https://kernel.org/) or use the one provided by Alice. + +> NOTE: The provided kernel will take a lot of time to compile because many options are enabled. + +If you want to use Alice's kernel, just run. +``` +# apkg -I linux +``` + +## Install firmware + +If your hardware requires firmware, install it using. +``` +# apkg -I linux-firmware +``` + +## Install bootloader + +In this guide, I'm going to use `grub` as the bootloader. Install `grub`. +``` +# apkg -I grub +``` + +Then generate grub config. +``` +# grub-install /dev/sdX +# grub-mkconfig -o /boot/grub/grub.cfg +``` + +## Hostname + +Change `alice` to the hostname of your choice. +``` +# echo alice > /etc/hostname +``` + +## Fstab + +Change the partition and filesystem of your choice below. +``` +# echo '/dev/sda1 swap swap defaults 0 1' >> /etc/fstab +# echo '/dev/sda2 / ext4 defaults 0 0' >> /etc/fstab +``` + +## Enable runit services + +Alice uses busybox's `runit` as its main service manager. Enable the required services. +``` +# ln -s /etc/sv/tty1 /var/service +# ln -s /etc/sv/tty2 /var/service +# ln -s /etc/sv/tty3 /var/service +``` + +I'm enabling 3 `tty` services. `tty` is required; without it, you won't be able to log in (or run any commands). + +> The runit service directory is `/etc/sv`. +> Create a symlink from `/etc/sv/` to `/var/service` to enable it; remove the symlink to disable it. + +## Setup user and password + +Add your user. +``` +# adduser +``` + +Add your user to the `wheel` group. +``` +# adduser wheel +``` + +You might need to add your user to the `input` and `video` groups to start the Wayland compositor later, and the `audio` group to have working audio. +``` +# adduser input +# adduser video +# adduser audio +``` + +## Root password + +Set the password for the `root` user. +``` +# passwd +``` + +## Networking + +You might want to set up networking before rebooting. For wifi connection, install `wpa_supplicant`. +``` +# apkg -I wpa_supplicant +``` + +Configure your SSID. +``` +# wpa_passphrase >> /etc/wpa_supplicant.conf +``` + +Enable the service. +``` +# ln -s /etc/sv/wpa_supplicant /var/service +``` + +Then configure & enable `udhcpc` service. +``` +# vi /etc/sv/udhcpc/conf +# ln -s /etc/sv/udhcpc /var/service +``` + +## Timezone + +Install `tzdata`. +``` +# apkg -I tzdata +``` + +Then create a symlink for your timezone to `/etc/localtime`. +``` +# ln -s /usr/share/zoneinfo/Asia/Kuala_Lumpur /etc/localtime +``` + +Alternatively, you can copy it and then uninstall `tzdata` to keep your installed packages minimal. +``` +# cp /usr/share/zoneinfo/Asia/Kuala_Lumpur /etc/localtime +# apkg -r tzdata +``` + +## Reboot and enjoy! + +Exit the chroot environment and unmount the Alice partition, then reboot. +``` +# exit +# umount /mnt/alice +# reboot +``` + +# Some important notes + +- `Alice` uses `spm` and `apkg` as its package manager and package build system. Run with the `-h` flag to see available options. +- Additional scripts are provided with the name `apkg-