diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/install.md | 64 | ||||
| -rw-r--r-- | docs/packagemanager.md | 46 |
2 files changed, 70 insertions, 40 deletions
diff --git a/docs/install.md b/docs/install.md index e6669e2c..dfcc1a4e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,7 +1,9 @@ -## 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. +# Install Alice + +This is a guide to install 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> @@ -17,37 +19,41 @@ 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. + +Prepare the partition and filesystem of your choice. In this guide `ext4` is used 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. +Mount your created partition somewhere. In this guide `/mnt/alice` is used 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.) + +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. +All further commands 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. + +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. +Once we have the repositories cloned, we need to configure `apkg`. `apkg` is the Alice 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 will create one for ease of use. The `apkg` config file should be located at `/etc/apkg.conf` by default. ### Configure apkg.conf @@ -55,7 +61,7 @@ First, we set `CFLAGS` and `CXXFLAGS`. Alice base packages are built using `-O3 ``` # echo 'export CFLAGS="-O3 -march=x86-64 -pipe"' >> /etc/apkg.conf ``` -And use whats in `CFLAGS` for `CXXFLAGS`. +And use what is in `CFLAGS` for `CXXFLAGS`. ``` # echo 'export CXXFLAGS="$CFLAGS"' >> /etc/apkg.conf ``` @@ -67,12 +73,17 @@ I'm also going to set `NINJAJOBS` here. Without it, `ninja` will use all threads ``` # 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`. +Next, we need to set the package 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. +Alice provides four (4) `package repos` (at the time of this writing): `core`, `extra`, `xorg` and `wayland`: + * `core` contains all base packages + * `extra` includes other packages beyond the base + * both `xorg` and `wayland` contain packages for the 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 @@ -111,38 +122,43 @@ Then add these paths to `/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. -> Use uppercase `U` for a system upgrade, and lowercase `u` to upgrade a specific package of your choice. +> Use uppercase `U` for a system upgrade, and lowercase `u` to upgrade a specific package. ``` # 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`. +If you changed `CFLAGS` and `CXXFLAGS` to something other than the default, it is 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`. -> Add the `-f` flag to force rebuild of existing prebuilt package. +> Add the `-f` flag to force rebuild of the existing prebuilt package. > `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 +### Install the kernel + You can configure your own kernel from [kernel.org](https://kernel.org/) or use the one provided by Alice. -> The provided kernel will take a lot of time to compile because many options are enabled. +> 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 @@ -154,29 +170,33 @@ Then generate grub config: ``` ### Hostname + Change `alice` to the hostname of your choice. ``` # echo alice > /etc/hostname ``` -### Fstab +### File systems table 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). +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> @@ -193,12 +213,14 @@ You might need to add your user to the `input` and `video` groups to start the W ``` ### 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 @@ -214,6 +236,7 @@ Enable the service: ``` ### Timezone + Install `tzdata`: ``` # apkg -I tzdata @@ -229,15 +252,18 @@ Alternatively, you can copy it and then uninstall `tzdata` to keep your installe ``` ### Reboot and enjoy! + Exit the chroot environment and unmount the Alice partition, then reboot: ``` # exit # umount /mnt/alice # reboot ``` +The machine is now ready for use. ## 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. + +- `Alice` uses `spm` and `apkg` as its package manager and package build system. Run with the `-h` flag to see the 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.md b/docs/packagemanager.md index f24ea686..12b49334 100644 --- a/docs/packagemanager.md +++ b/docs/packagemanager.md @@ -1,16 +1,20 @@ 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`. +In Alice, there are two package managers: [spm](https://codeberg.org/emmett1/spm) and [autils](https://codeberg.org/emmett1/autils): + * `spm` was written for generic package manager for linux distribution. + * `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` stands for `simple package manager` and is a simple and minimal POSIX compliant shell script. It only depends on core utils and tar (or busybox's utils and tar). `spm` is only intended for compressing some directory into package, then extract package into the system with files being tracked into the database. There is 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 ----------- +The following optiosn are available to `spm`: + ``` -a print all installed packages -b <path> build <path> directory into package @@ -22,7 +26,7 @@ spm - usage -u <pkg> re-install/upgrade <pkg> ``` -- list all install package with version +- list all installed packages with their version: ``` $ spm -a ... @@ -37,7 +41,7 @@ nsxiv 32-1 ... ``` -- build package from directory +- build a package from directory: ``` (build package) $ ./configure --prefix=/usr @@ -56,7 +60,7 @@ $ make DESTDIR=$PWD/fakeroot install # spm -i pkgname#pkgversion-pkgrelease.spm ``` -- install package into system +- install a package into system: ``` # spm -i pkgname#pkgversion-pkgrelease.spm [pkgname] Verify package... @@ -65,7 +69,7 @@ $ make DESTDIR=$PWD/fakeroot install [pkgname] Package 'pkgname#pkgversion-pkgrelease' installed. ``` -- list files installed by 'packagename' +- list files installed by 'packagename': ``` $ spm -l test usr/ @@ -75,7 +79,7 @@ usr/bin/ usr/bin/aaa ``` -- list package owner of a file (can use regex) +- list package owner of a file (can use regex): ``` $ spm -o gcc$ ccache usr/lib/ccache/gcc @@ -84,7 +88,7 @@ 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 +- upgrade/reinstall installed package: ``` # spm -u pkgname#pkgversion-pkgrelease.spm [pkgname] Verify package... @@ -101,7 +105,7 @@ spm - environment |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: +You can pass these environment to the `spm` command: ``` # SPM_ROOT=/mnt/rootfs spm -i pkgname#pkgversion-pkgrelease.spm # SPM_FORCEINSTALL=1 SPM_ROOT=/mnt/rootfs spm -i pkgname#pkgversion-pkgrelease.spm @@ -115,9 +119,9 @@ autils 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. +`apkg` is a main package manager that can solve dependencies, batch install/upgrade/remove packages, perform system upgrades, trigger necessary caches, etc. `apkg` can be run inside or outside the 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: +When running outside the package template, `apkg` will need 'package names' as arguments, and those 'package names' will search through the `APKG_REPO` environment: ``` # apkg testpkg testpkg2 (build testpkg and testpkg2) @@ -126,7 +130,7 @@ When running outside package template, `apkg` will need 'package names' as argum # 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: +When running inside package template, `apkg` will perform the operation within the current directory package. Example: ``` # cd /path/to/local/testpkg @@ -156,7 +160,7 @@ apkg - usage -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` +Here are some quick tips/tricks to using `apkg`: - installing package and its dependencies (mind the uppercase `i`) ``` @@ -192,7 +196,7 @@ swayfx [...] Press Ctrl + C to abort. ``` -- install package without solving dependencies (mind the lowercase `i` and theres no prompt for this option) +- install package without solving dependencies (note the lowercase `i` and theres no prompt for this option) ``` # apkg -i wlroots mesa [...] Package 'wlroots' already installed. @@ -213,7 +217,7 @@ rust ... ``` -- list all installed packages with filter (will only print installed package contains word filter) +- list all installed packages with filter (will only print installed package containing the word filter) ``` $ apkg -a sway swaybg @@ -260,7 +264,7 @@ util-macros [pango] Package 'pango#1.54.0-1' upgraded. ``` -- full system upgrades (mind uppercase `u` and will prompt first if theres package updates) +- full system upgrades (note the uppercase `u` and will prompt first if there is a package update available) ``` # apkg -U [...] Checking for outdated packages... @@ -314,7 +318,7 @@ You can add these environment into `apkg` config file. apkg - config file ------------------ -`apkg` can work without its config file by using all default value. Default config path for `apkg` is `/etc/apkg.conf`. You can change config path by append `APKG_CONF` to `apkg`, example: +`apkg` can work without its config file by using all default values. Default config path for `apkg` is `/etc/apkg.conf`. You can change config path by appending `APKG_CONF` to `apkg`: ``` # APKG_CONF=/etc/apkg-local.conf apkg <args> ``` @@ -333,7 +337,7 @@ $ revdep $ revdep -v ``` -You can combine with `apkg` to rebuild broken packages, example; +You can combine with `apkg` to rebuild broken packages: ``` # apkg -f -u $(revdep) ``` @@ -378,7 +382,7 @@ Usage: apkg-deps --------- -Script to find runtime linked dependencies of installed package. Its good to use when writing package template. +Script to find runtime linked dependencies of installed package. It is recommended to use this when writing a package template. Usage: ``` @@ -412,9 +416,9 @@ $ 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. +Script to print package's redundant dependencies. It is recommended to use this when writing package template for minimizing dependencies and speed up `apkg` dependencies solving. -usage: +Usage: ``` (print package contains redundant dependencies) $ apkg-redundantdeps |