diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.html | 76 | ||||
| -rw-r--r-- | docs/index.md | 3 | ||||
| -rw-r--r-- | docs/install.html | 6 | ||||
| -rw-r--r-- | docs/install.md | 238 | ||||
| -rw-r--r-- | docs/packagemanager.html | 4 | ||||
| -rw-r--r-- | docs/packagemanager.md | 382 |
6 files changed, 5 insertions, 704 deletions
diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 113adefd..00000000 --- a/docs/index.html +++ /dev/null @@ -1,76 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> -<head> - <meta charset="UTF-8"> - <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <title>Alice Linux - docs</title> - <style> - body { - font-family: monospace; - font-size: 14px; - line-height: 1.25; - max-width: 60em; - margin-left: auto; - margin-right: auto; - padding-left: 1em; - padding-right: 1em; - background-color: #242424; - color: #fefefe; - } - pre { - background-color: #2b2b2b; - border-radius: 3px; - padding: 10px; - overflow-x: auto; - } - code { - color: #f7f3d6; - } - img { - display: block; - max-width: 100%; - } - hr { - border: 0; - border-top: 1px dashed #fefefe; - margin: 20px 0; - } - table { - width: 100%; - border-collapse: collapse; - } - th, td { - padding: 4px; - } - th { - background-color: #2b2b2b; - } - table, th, td { - border: 2px dashed #2b2b2b; - } - a { - color: #90cbf9; - text-decoration: none - } - a:hover { - color: #869edc; - text-decoration: underline - } - </style> -</head> -<body> -<div class="centered-wrapper"> - <h1>docs</h1> - <a href="/">home</a> / <a href="/docs">docs</a> / <a href="https://codeberg.org/emmett1/alicelinux">development</a> / <a href="https://codeberg.org/emmett1/alicelinux/releases">download</a> / <a href="https://sourceforge.net/projects/alice-linux/files/iso/">iso</a> / <a href="/community.html">community</a> / <a href="/donate.html">donate</a> - <hr> -<p>Here lie the documentations for Alice Linux.</p> - -<ul> -<li><a href="./install.html">Install Alice</a></li> -<li><a href="./packagemanager.html">Package Manager</a></li> -</ul> - <br><hr> - <p>Copyright (C) Alice Linux, 2024</p> -</div> -</body> -</html> diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index e59f219f..00000000 --- a/docs/index.md +++ /dev/null @@ -1,3 +0,0 @@ -Here lie the documentations for Alice Linux. -- [Install Alice](./install.html) -- [Package Manager](./packagemanager.html) diff --git a/docs/install.html b/docs/install.html index 5527163a..4c37115a 100644 --- a/docs/install.html +++ b/docs/install.html @@ -43,10 +43,10 @@ padding: 4px; } th { - background-color: #2b2b2b; + background-color: #221e1f; } table, th, td { - border: 2px dashed #2b2b2b; + border: 1px dashed #e7e8eb; } a { color: #90cbf9; @@ -139,7 +139,7 @@ $ curl -O <url>.sha256sum </p> <pre><code># echo 'APKG_REPO="/var/lib/alicelinux/repos/core /var/lib/alicelinux/repos/extra"' >> /etc/apkg.conf </code></pre> -<blockquote><p>NOTE: All repo paths must be declared in the APKG<em></em>EPO variable, seperated by a single space.</p> +<blockquote><p>NOTE: All repo paths must be declared in the APKG_REPO variable, seperated by a single space.</p> </blockquote> <p> After setting up our <code>package repos</code>, make sure <code>apkg</code> can find the packages. We can use <code>apkg -s <pattern></code> to search for packages. diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index e40082e9..00000000 --- a/docs/install.md +++ /dev/null @@ -1,238 +0,0 @@ -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 <url> - $ curl -O <url>.sha256sum -Verify the checksum of the Alice rootfs tarball: - - $ sha256sum -c alicelinux-rootfs-20240525.tar.xz.sha256sum - -Make sure it prints: - 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. - -Clone Alice repos ------------------ - -Fetch the Alice packages repositories somewhere. I'll fetch them inside the /var/lib directory to keep the system clean. - # cd /var/lib - # git clone --depth=1 https://codeberg.org/emmett1/alicelinux - -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. - -Configure apkg.conf -------------------- - -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 four (4) `package repos` (at the time of this writing): `core`, `extra`, `xorg` and `wayland`. `core` contains all base packages, and `extra` includes other packages beyond the base. `xorg` and `wayland` contain packages for gui and their dependencies. - -First, get the absolute path of the `package repos` where we cloned them. By the way, we are still inside the `/var/lib` directory where we cloned the repo. ->NOTE: USE TAB COMPLETION! - # realpath alicelinux/repos/core - /var/lib/alicelinux/repos/core - # realpath alicelinux/repos/extra - /var/lib/alicelinux/repos/extra - -After we have the path of our `package repos`, add it to the `APKG_REPO` variable in `/etc/apkg.conf`. - # echo 'APKG_REPO="/var/lib/alicelinux/repos/core /var/lib/alicelinux/repos/extra"' >> /etc/apkg.conf - ->NOTE: All repo paths must be declared in the APKG_REPO variable, seperated by a single space. - -After setting up our `package repos`, make sure `apkg` can find the packages. We can use `apkg -s <pattern>` to search for packages. - # apkg -s sway - swayidle - swaybg - swaylock - sway - -If the output appears, then we are good to go. - -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 - -Full system upgrade/rebuild ---------------------------- - -On the first install, we should upgrade the system first. -> NOTE: Use uppercase `U` for a system upgrade, and lowercase `u` to upgrade a specific package of your choice. - # apkg -U - -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`. - -> NOTE: Add the `-f` flag to force rebuild of existing prebuilt package. -> NOTE: `apkg -a` prints all installed packages on the system. - - # apkg -u $(apkg -a) - -Install development packages ----------------------------- - -Before installing any additional packages, we need to install development packages. - # apkg -I meson cmake pkgconf libtool automake perl - -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 linux-firmware-nvidia - -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/<service>` to `/var/service` to enable it; remove the symlink to disable it. - -Setup user and password ------------------------ - -Add your user: - # adduser <user> - -Add your user to the `wheel` group: - # adduser <user> 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 <user> input - # adduser <user> video - # adduser <user> audio - - -Root password -------------- - -Set the password for the `root` user: - # passwd - -Networking ----------- - -You might want to set up networking before rebooting. Use `wpa_supplicant` and `dhcpcd`. - # apkg -I wpa_supplicant dhcpcd - -Configure your SSID: - # wpa_passphrase <YOUR SSID> <ITS PASSWORD> >> /etc/wpa_supplicant.conf - -Enable the service: - # ln -s /etc/sv/wpa_supplicant /var/service - # ln -s /etc/sv/dhcpcd /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-<script>` which will be added (or removed) from time to time. -- Use `revdep` to scan for broken libraries and binaries after system upgrades and package removals. You can use `revdep -v` to print out missing required libraries, and use `apkg -f -u $(revdep)` to scan and rebuild broken packages. -- Run `updateconf` to update config files in `/etc` after package upgrades. diff --git a/docs/packagemanager.html b/docs/packagemanager.html index 1a329ea5..95a133da 100644 --- a/docs/packagemanager.html +++ b/docs/packagemanager.html @@ -43,10 +43,10 @@ padding: 4px; } th { - background-color: #2b2b2b; + background-color: #221e1f; } table, th, td { - border: 2px dashed #2b2b2b; + border: 1px dashed #e7e8eb; } a { color: #90cbf9; diff --git a/docs/packagemanager.md b/docs/packagemanager.md deleted file mode 100644 index 3e3ba165..00000000 --- a/docs/packagemanager.md +++ /dev/null @@ -1,382 +0,0 @@ -Package Manager -=============== - -In Alice, theres two package manager used, [spm](https://codeberg.org/emmett1/spm) and [autils](https://codeberg.org/emmett1/autils). Why two package manager? `spm` was written for generic package manager for linux distribution. And `autils` is written specifically for `Alice` and required `spm`. - -spm ---- - -`spm` stands for `simple package manager`. It does simple and minimal written in POSIX compliance shell script. It only depends on core utils and tar (or busybox's utils and tar). `spm` only intended for compressing some directory into package, then extract package into system with files being tracked into database. Theres is no build script, recipe or ports in `spm`. You can write your own tools to use with `spm` either like Arch Linux's `makepkg`, CRUX's `pkgmk` or Slackware's `slackbuild` script. - -spm - usage ------------ - -list `spm` usage: - - -a print all installed packages - -b <path> build <path> directory into package - -h print this help message - -i <file> install <file> package into system - -l <pkg> list files installed by <pkg> - -o <file> print owner of <file> - -r <name> remove installed <name> from system - -u <pkg> re-install/upgrade <pkg> - -list all install package with version: - - $ spm -a - ... - neofetch 7.1.0-1 - nettle 3.10-1 - nghttp2 1.62.1-1 - ninja 1.12.1-1 - nodejs 22.5.1-1 - nspr 4.35-1 - nss 3.102.1-1 - nsxiv 32-1 - ... - -build package from directory: - - (build package) - $ ./configure --prefix=/usr - $ make - - (install into fake directory) - $ make DESTDIR=$PWD/fakeroot install - - (turn fake directory into package (package.spm)) - # spm -b $PWD/fakeroot - - (mv 'package.spm' into correct format (name#version-release.spm)) - # mv package.spm pkgname#pkgversion-pkgrelease.spm - - (install package into system) - # spm -i pkgname#pkgversion-pkgrelease.spm - -install package into system: - - # spm -i pkgname#pkgversion-pkgrelease.spm - [pkgname] Verify package... - [pkgname] Checking for conflicts... - [pkgname] Installing package... - [pkgname] Package 'pkgname#pkgversion-pkgrelease' installed. - -list files installed by 'packagename'$ spm -l test: - - usr/ - usr/share/ - usr/share/aaa - usr/bin/ - usr/bin/aaa - -list package owner of a file (can use regex): - - $ spm -o gcc$ - ccache usr/lib/ccache/gcc - gcc usr/bin/gcc - gcc usr/bin/x86_64-pc-linux-musl-gcc - linux lib/modules/6.6.41-Alice/build/scripts/dummy-tools/gcc - -upgrade/reinstall installed package: - - # spm -u pkgname#pkgversion-pkgrelease.spm - [pkgname] Verify package... - [pkgname] Checking for conflicts... - [pkgname] Upgrading package... - [pkgname] Package 'pkgname#pkgversion-pkgrelease' upgraded. - -spm - environment ------------------ - -|env|description| -|---|---| -|SPM\_ROOT|use custom root location for package installation| -|SPM\_FORCEINSTALL|set any value to ignore conflicted files| - -You can pass these environment to `spm` command, example: - - # SPM_ROOT=/mnt/rootfs spm -i pkgname#pkgversion-pkgrelease.spm - # SPM_FORCEINSTALL=1 SPM_ROOT=/mnt/rootfs spm -i pkgname#pkgversion-pkgrelease.spm - -autils ------- - -`autils` stands for `alice utilitis`. `autils` contains main package manager (apkg), utilities (apkg-\<util\>) and \<random util script\>. `autils` is specifically written to manage `Alice` packages. - -apkg ----- - -`apkg` is a main package manager that can solve dependencies, batch install/upgrade/remove packages, system upgrades, trigger necessary caches, and etc. `apkg` can be run inside or outside package template. - -When running outside package template, `apkg` will need 'package names' as arguments, and those 'package names' will search through `APKG_REPO` environment. Example: - - # apkg testpkg testpkg2 (build testpkg and testpkg2) - # apkg testpkg testpkg2 -i (build and install testpkg and testpkg2) - # apkg -u testpkg testpkg2 (upgrade/reinstall testpkg and testpkg2) - # apkg -f -u testpkg testpkg2 (force rebuild then upgrade/reinstall testpkg and testpkg2) - -When running inside package template, `apkg` will do operation for current directory package. Example: - - # cd /path/to/local/testpkg - # apkg (build testpkg) - # apkg -i (build and install testpkg) - # apkg -u (upgrade/reinstall testpkg) - # apkg -u -f (force rebuild then upgrade/reinstall testpkg) - -apkg - usage ------------- - - -i <pkg(s)> install package(s) - -I <pkg(s)> install packages(s) with dependencies - -d <pkg> list <pkg> dependencies - -D <pkg(s)> list all dependencies - -j <pkg> list all dependents - -u <pkg(s)> upgrade package(s) - -t [pkg(s)] trigger system cache/db updates - -U update system - -f force rebuild - -o <pkg(s)> download source - -p <pkg> print package path - -s <pattern> search packages - -h print this help message - -I won't explain details on every each options here, but I will give quick tips/tricks to use `apkg` - -installing package and its dependencies (mind the uppercase `i`): - - # apkg -I sway - [...] Solving dependencies... - [...] Installing 3 package(s): mesa pango sway - [...] Press ENTER to continue operation. - [...] Press Ctrl + C to abort. - -search available packages: - - $ apkg -s sway - swaybg - swaylock - sway - swayidle - swayfx - -install all package with 'sway' name and its dependencies: - - # apkg -I $(apkg -s sway) - ... - [...] Package 'mesa' is installed - [...] Package 'swaybg' is installed - [...] Package 'swaylock' is installed - [...] Package 'swayidle' is installed - [...] Package 'swayfx' is installed - [...] Solving dependencies... - [...] Installing 2 package(s): pango sway - [...] Press ENTER to continue operation. - [...] Press Ctrl + C to abort. - -install package without solving dependencies (mind the lowercase `i` and theres no prompt for this option): - - # apkg -i wlroots mesa - [...] Package 'wlroots' already installed. - [...] Package 'mesa' already installed. - -list all installed packages: - - $ apkg -a - ... - qemu - ranger - rdfind - readline - rsync - rtorrent - rust - ... - -list all installed packages with filter (will only print installed package contains word filter): - - $ apkg -a sway - swaybg - swayfx - swayidle - swaylock - -list dependencies of a package: - - $ apkg -d sway - wlroots - json-c - pango - -list all dependencies tree of package(s): - - $ apkg -D sway dwm - ... - wayland - wayland-protocols - xkeyboard-config - xcb-proto - xorgproto - util-macros - ... - -upgrade/reinstall package(s): - - # apkg -u wlroots cwm pango - [wlroots] Verify package... - [wlroots] Checking for conflicts... - [wlroots] Upgrading package... - [wlroots] Package 'wlroots#0.17.4-1' upgraded. - [cwm] Verify package... - [cwm] Checking for conflicts... - [cwm] Upgrading package... - [cwm] Package 'cwm#7.4-1' upgraded. - [pango] Verify package... - [pango] Checking for conflicts... - [pango] Upgrading package... - [pango] Package 'pango#1.54.0-1' upgraded. - -full system upgrades (mind uppercase `u` and will prompt first if theres package updates): - - # apkg -U - [...] Checking for outdated packages... - [...] Solving dependencies... - [...] Upgrading 3 package(s): initscripts mesa sowm - [...] Press ENTER to continue operation. - [...] Press Ctrl + C to abort. - -make full system rebuild in dependencies order (`-f`: force rebuild, `-u`: upgrade/reinstall, `-D`: solve dependency order, `-a`: list all installed package(s)): - - # apkg -f -u $(apkg -D $(apkg -a)) -... -(start rebuilding package in dependencies order here) -... - -remove installed packages: - - # apkg -r wlroots pango sway - [...] Package 'wlroots' removed. - [...] Package 'pango' removed. - [...] Package 'sway' removed. - -print package path: - - $ apkg -p sway - /home/emmett/codeberg/alicelinux/repos/wayland/sway - -apkg - environment ------------------- - -You can pass environment to `apkg` to override defaults and in `/etc/apkg.conf`. Available environment and its default value as follows: - -|env|default value|description| -|-|-|-| -|APKG\_ROOT|/|root for package installation| -|APKG\_CONF|/etc/apkg.conf|apkg's config file| -|APKG\_REPO| |defaults is empty, template repo path, space separated variable| -|APKG\_PACKAGE\_DIR|$PWD|prebuilt package directory path| -|APKG\_SOURCE\_DIR|$PWD|package source directory path| -|APKG\_WORK\_DIR|$PWD|package working directory path| -|APKG\_NOPROMPT| |skip prompt, use any value| - -You can add these environment into `apkg` config file. - -/etc/apkg.conf ------------------- - -`apkg` can work without its config file by using all default value. Default config path for `apkg` is `/etc/apkg.conf`. You can override config path by append `APKG_CONF` to `apkg`, example: - # APKG_CONF=/etc/apkg-local.conf apkg <args> - -revdep ------- - -`revdep` is script to find broken packages. Its recomended to run after packages is removed or upgraded. - -Usage: - - (print out broken packages) - $ revdep - - (verbosely print missing libraries) - $ revdep -v - -You can combine with `apkg` to rebuild broken packages, example; - - # apkg -f -u $(revdep) - -> NOTE: `revdep` does not solve dependencies, so you might need manually rebuild broken packages instead combine with `apkg`. - -updateconf ----------- - -`updateconf` is script to update configuration files inside `/etc` directory. Its recomended to run after packages upgrades. - -apkg-chroot ------------ -Script to entering chroot environment of custom root location. - - # apkg-chroot <customroot path> - # apkg-chroot <customroot path> <command> - -apkg-clean ----------- -Print out old package and source caches. - -Options: - - -s print sources only - -p print packages only - -Usage: - - (to remove old packages) - # apkg-clean -p | xargs rm - - (to remove old sources) - # apkg-clean -s | xargs rm - - (to remove both old packages and sources) - # apkg-clean | xargs rm - -apkg-deps ---------- - -Script to find runtime linked dependencies of installed package. Its good to figure out dependenciess when writing package template. - -Usage: - $ apkg-deps <pkg> - -apkg-foreign ------------- - -Script to list installed package outside package repo. - -Usage: - - (print list foreign packages) - $ apkg-foreign - - (remove foreign packages) - # apkg -r $(apkg-foreign) - -apkg-orphan ------------ - -Script to print list package without parent dependencies. - -Usage: - - $ apkg-orphan - -apkg-redundantdeps ------------------- - -Script to print package's redundant dependencies. Its good to use when writing package template for minimizing dependencies and speed up `apkg` dependencies solving. - -usage: - - (print package contains redundant dependencies) - $ apkg-redundantdeps - - (remove redundant dependencies for depends list) - $ apkg-redundantdeps -f |