diff --git a/docs/packaging/advanced-config/eopkg-configuration.md b/docs/packaging/advanced-config/eopkg-configuration.md index 29cd0c645..fd5db49b3 100644 --- a/docs/packaging/advanced-config/eopkg-configuration.md +++ b/docs/packaging/advanced-config/eopkg-configuration.md @@ -5,11 +5,11 @@ summary: Modifying the eopkg configuration # Eopkg Configuration -The eopkg configuration file changes how eopkg works. The first section in the config has settings for the process of building a package. The second section allows you to configure the directories that eopkg uses for various operations. Lastly, the `general` section contains settings for the general operation of eopkg. +The `eopkg` configuration file changes how `eopkg` works. The first section in the config has settings for the process of building a package. The second section allows you to configure the directories that `eopkg` uses for various operations. Lastly, the `[general]` section contains settings for the general operation of `eopkg`. ## Copying the default configuration -Solus aims to be a stateless operating system, so the default configuration file for eopkg is saved to `/usr/share/defaults/eopkg/eopkg.conf`. To modify the configuration, you'll have to start by copying the default configuration file into `/etc/eopkg` so it will override the default file: +Solus aims to be a stateless operating system, so the default configuration file for `eopkg` is saved to `/usr/share/defaults/eopkg/eopkg.conf`. To modify the configuration, you'll have to start by copying the default configuration file into `/etc/eopkg` so it will override the default file: ```bash sudo mkdir -p /etc/eopkg && sudo cp /usr/share/defaults/eopkg/eopkg.conf /etc/eopkg/eopkg.conf diff --git a/docs/packaging/advanced-config/local-repository.md b/docs/packaging/advanced-config/local-repository.md index 0e1974030..ce5a752fa 100644 --- a/docs/packaging/advanced-config/local-repository.md +++ b/docs/packaging/advanced-config/local-repository.md @@ -8,7 +8,7 @@ summary: Packaging using a local repository This guide walks you through the steps necessary to tell `solbuild` how to use your locally built `.eopkg` files that are not yet in the Solus repository. :::note -It is not necessary to use a local repository to test most package submissions. The easier and recommended way is to install the `eopkg` files created when a package is built. This procedure is intended for use with stack upgrades, rebuilds, or new packages that need new dependencies that are not yet in the repository. +It is not necessary to use a local repository to test most package submissions. The easier and recommended way is to install the `.eopkg` files created when a package is built. This procedure is intended for use with stack upgrades, rebuilds, or new packages that need new dependencies that are not yet in the repository. ::: We assume you have worked through the [packaging](/docs/packaging) material for creating a package with `solbuild`. @@ -23,7 +23,7 @@ You will also need to ensure that your repository is fully up to date. See [Upda ## Using the local repository -### Copying .eopkg files to the local repository +### Copying `.eopkg` files to the local repository To use your locally built `.eopkg` files as a dependencies for another package, you must copy the regular package file, and any accompanying `-devel` packages to the local repository directory `/var/lib/solbuild/local`. @@ -39,7 +39,7 @@ sudo cp *.eopkg /var/lib/solbuild/local With the `.eopkg` files now present in the local repository, you can use them to build a package by running `go-task build-local`, rather than just `go-task`, and `solbuild` will prefer your packages over packages found in the Solus repository. -Every time you run `go-task build-local`, all `eopkg` files in the local repository will be re-indexed. +Every time you run `go-task build-local`, all `.eopkg` files in the local repository will be re-indexed. ### Best practices when working with a solbuild local repository diff --git a/docs/packaging/creating-a-new-package.md b/docs/packaging/creating-a-new-package.md index 9ad656bb9..f4455018a 100644 --- a/docs/packaging/creating-a-new-package.md +++ b/docs/packaging/creating-a-new-package.md @@ -142,7 +142,7 @@ Once the build completes, your directory should now include the following files: └── tree-2.1.1-1-1-x86_64.eopkg ``` -All these files _except_ the `*eopkg` file(s) should be included in your pull request. You will remove the `.eopkg` files after testing the package. +All these files _except_ the `.eopkg` file(s) should be included in your pull request. You will remove the `.eopkg` files after testing the package. Once your package has built successfully, you will need to [test it](testing-a-package). diff --git a/docs/packaging/procedures/request-a-package-update.md b/docs/packaging/procedures/request-a-package-update.md index f3e1f2dfe..b9f903ec5 100644 --- a/docs/packaging/procedures/request-a-package-update.md +++ b/docs/packaging/procedures/request-a-package-update.md @@ -15,6 +15,6 @@ You will be asked in the form to provide the following information: - Title: `Update $packagename to $version` (Example: `Update nano to 2.9.7`) - Description: Explanation as to the value-add of updating this package. -- Link to source tarball/zip file. Note: master.zip files **are not permitted**. We require versioned tarballs, for example: "1.2.3.tar.gz". +- Link to source tarball/zip file. Note: `master.zip` files **are not permitted**. We require versioned tarballs, for example: "1.2.3.tar.gz". Please put this into a new [issue](https://github.com/getsolus/packages/issues/new?assignees=&labels=Package+Update+Request&projects=&template=request-package-update.yml). diff --git a/docs/user/contributing/style.md b/docs/user/contributing/style.md index b5c9ff78c..6344836be 100644 --- a/docs/user/contributing/style.md +++ b/docs/user/contributing/style.md @@ -84,6 +84,9 @@ console.log("Hello, world!"); - Dev Tracker - Avoid using the term _Dev Tracker_. - Example: "The packages issue tracker", instead of "The dev tracker" +- eopkg + - If you're referring to the application or package, use "`eopkg`" with inline code formatting (see below) + - If you're referring to package files, use "`.eopkg`" with inline code formatting, including the period but no wildcard ### Markdown formatting diff --git a/docs/user/troubleshooting/boot-rescue.md b/docs/user/troubleshooting/boot-rescue.md index ba42f4fcf..d50430a76 100644 --- a/docs/user/troubleshooting/boot-rescue.md +++ b/docs/user/troubleshooting/boot-rescue.md @@ -21,9 +21,9 @@ Multi-booting is when you have multiple operating systems on the same device. Al The inability to access Solus in a multi-boot scenario typically applies to "legacy boot" (non-UEFI), where the other operating system owns GRUB, which is used booting itself and Solus. This can be resolved by accessing the other operating system and running `sudo update-grub`. -## An entry is present in /etc/fstab that is not present at boot time +## An entry is present in `/etc/fstab` that is not present at boot time -If you get to an emergency prompt when the system tries to boot, check /etc/fstab. Look for any entries that might refer to disks not present at boot, such as a USB drive or nfs mount. Try adding "noauto" and rebooting. A USB drive entry might look like: +If you get to an emergency prompt when the system tries to boot, check `/etc/fstab`. Look for any entries that might refer to disks not present at boot, such as a USB drive or NFS mount. Try adding "noauto" and rebooting. A USB drive entry might look like: ```bash UUID=XXXXXX /mnt/mydisk exfat noauto,uid=1000,gid=1000,umask=0022 0 0 @@ -42,7 +42,7 @@ Whether you're using GRUB or UEFI, you will need to mount your Solus root (`/`) 1. First we need to be the root user. Type: `sudo su` 2. Next we make a directory where we will mount our local Solus system: `mkdir /target` -3. Now, using `lsblk`, determine the partition of the Solus system. We recommend checking the size of the partition listed and if it matches the size of your Solus install, use that. It will likely be something along the lines of `sda#` or `sdb#`. For NVME drives, the name will look like `nvme0n1px` +3. Now, using `lsblk`, determine the partition of the Solus system. We recommend checking the size of the partition listed and if it matches the size of your Solus install, use that. It will likely be something along the lines of `sda#` or `sdb#`. For NVMe drives, the name will look like `nvme0n1px` Note: If you see "lvm" as the type, the system has LVM partitions. See the next section for how to mount them. 4. If your root partition is of type sdX / nvme0n1x, replace the "sdX#" in the following command with the partition and mount to the target directory we created: `mount /dev/sdX# /target` @@ -92,7 +92,7 @@ sdb 8:16 1 7.3G 0 disk #### UEFI -If your system uses UEFI as opposed to GRUB, you will also need to mount your EFI System Partition, otherwise referred to as ESP. If you followed our [UEFI guide](/docs/user/quick-start/installation/disks#uefi) during installation of Solus, then in all likelihood your ESP will be about 1GB in size. For an older installation, it may be around 512MB. If you're unsure of the partition, run the following, replacing X with the same letter during your mounting of your root file system, minus the number: +If your system uses UEFI as opposed to GRUB, you will also need to mount your EFI System Partition, otherwise referred to as ESP. If you followed our [UEFI guide](/docs/user/quick-start/installation/disks#uefi) during installation of Solus, then in all likelihood your ESP will be about 1GB in size. For an older installation, it may be around 512MB. If you're unsure of the partition, run the following, replacing "X" with the same letter used during your mounting of your root file system, minus the number: For HDD / SDD drives: @@ -114,7 +114,7 @@ Device Size Type /dev/sda2 111.3G Linux filesystem ``` -Notice we have `/dev/sda1` as the Device with the `EFI System` type and roughly 500mb in size. This is the partition we will be mounting. +Notice we have `/dev/sda1` as the Device with the `EFI System` type and roughly 500MB in size. This is the partition we will be mounting. With our ESP device known, let's go ahead and mount it, replacing `sdX#` in the case below with our partition. @@ -124,7 +124,7 @@ mount /dev/sdX# /target/boot #### Other partitions -If your system has other specific partitions, such as a separate /home partition, they will also need to be mounted. +If your system has other specific partitions, such as a separate `/home` partition, they will also need to be mounted. ### Chrooting to your Solus system @@ -147,7 +147,7 @@ Assuming all goes well, you should now be able to chroot into your Solus system To validate a working network connection (assuming a network connection is available in your live image), you can run `ping google.com` in the chrooted environment. If you get responses from `google.com`, you have a successful connection to the Internet. If you do not, try the following: 1. Exit the chroot by typing `exit` -2. Run +2. Run: ```bash cp /run/systemd/resolve/stub-resolv.conf /target/run/systemd/resolve/ @@ -177,7 +177,7 @@ In the event that disk changes had caused the system to fail to boot, try the fo ### Re-run system-wide configuration triggers -In the chroot environment, run the following command which will perform various configuration triggers to update your icon cache, update GRUB and EFI configuration, re-compile settings, and more. +In the chroot environment, run the following command which will perform various configuration triggers to update your icon cache, update GRUB and EFI configuration, re-compile settings, and more: ```bash sudo usysconf run -f diff --git a/docs/user/troubleshooting/index.md b/docs/user/troubleshooting/index.md index 64aad1b67..6e6a34352 100644 --- a/docs/user/troubleshooting/index.md +++ b/docs/user/troubleshooting/index.md @@ -27,9 +27,9 @@ If eopkg is interrupted, the database may become corrupted. When updating you wi To run database recovery, run `sudo eopkg rdb` in the terminal and then updates should function correctly. -### eopkg check shows broken packages +### `eopkg check` shows broken packages -`eopkg check` checks the sha256sums of files on disk versus what was originally installed by the original .eopkg file. In some cases (for example .pyc files), these files will be modified in the normal operation of Solus. If after reinstalling a package it remains broken, then it's likely nothing to worry about (there are no exceptions made in `eopkg check` for files that are expected to change from use). When reinstalling broken packages, (per above) it only needs to be run once. +`eopkg check` checks the sha256 checksums of files on disk versus what was originally installed by the original `.eopkg` file. In some cases (for example `.pyc` files), these files will be modified in the normal operation of Solus. If after reinstalling a package it remains broken, then it's likely nothing to worry about (there are no exceptions made in `eopkg check` for files that are expected to change from use). When reinstalling broken packages, (per above) it only needs to be run once. ## Updated system and having issues @@ -60,7 +60,7 @@ If Solus partially boots, you can generally get to a TTY using `Ctrl+Alt+F2` to ### Display manager won't start -A common cause of not being able to boot is due to installing the nvidia drivers, but not booting into the latest kernel (the only kernel which has the drivers installed). Also ensure you have the correct driver version installed for your kernel. You can check if you have booted into the latest kernel by comparing the installed package with the booted kernel (instructions for both kernels) +A common cause of not being able to boot is due to installing the NVIDIA drivers, but not booting into the latest kernel (the only kernel which has the drivers installed). Also ensure you have the correct driver version installed for your kernel. You can check if you have booted into the latest kernel by comparing the installed package with the booted kernel (instructions for both kernels) ```bash eopkg info linux-lts | head -n2; uname -a @@ -72,7 +72,7 @@ eopkg info linux-current | head -n2; uname -a If the kernel version and release don't match from lines 2 and 3 of the output, then you aren't booting into the latest kernel and this is the likely cause of X not loading (particularly if you just installed the drivers). A couple of common reasons are: -- On a grub machine, a common cause for not booting the latest kernel is due to Solus not being the boot loader on the MBR. Make sure you are booting via the Solus boot loader (if possible), or update grub on the distro that own the boot loader, see [Legacy/BIOS installation](/docs/user/troubleshooting/installation#legacybios-installation). +- On a GRUB machine, a common cause for not booting the latest kernel is due to Solus not being the boot loader on the MBR. Make sure you are booting via the Solus boot loader (if possible), or update GRUB on the distro that own the boot loader, see [Legacy/BIOS installation](/docs/user/troubleshooting/installation#legacybios-installation). - Another possibility is that the `ESP` has run out of space so the kernel cannot be copied over to it. You can debug why this isn't happening via `sudo CBM_DEBUG=1 clr-boot-manager update`. This will output all information on the process, where it may be failing, or that it is working correctly. @@ -94,7 +94,7 @@ Notable commands to check the boot time are: `systemd-analyze` (note that the fi ### Timeout on partition mount (90s) -If information about a device changes (UUID or mount path `/dev/sda`), this can cause systemd to time out for 90 seconds creating a long boot process. Most frequently this happens with the swap file which can be shared across distros. Most of the devices mounted on boot will appear in `/etc/fstab` or be a parameter in a file where configuring resume `cat /etc/kernel/cmdline.d/*`. +If information about a device changes (UUID or mount path `/dev/sda`), this can cause `systemd` to time out for 90 seconds creating a long boot process. Most frequently this happens with the swap file which can be shared across distros. Most of the devices mounted on boot will appear in `/etc/fstab` or be a parameter in a file where configuring resume `cat /etc/kernel/cmdline.d/*`. `cat /proc/cmdline` will show what parameters the kernel has booted with. diff --git a/docs/user/troubleshooting/installation.md b/docs/user/troubleshooting/installation.md index f4fdde15e..c8b555508 100644 --- a/docs/user/troubleshooting/installation.md +++ b/docs/user/troubleshooting/installation.md @@ -15,12 +15,12 @@ You can check whether the Solus ISO has booted in EFI mode by checking the for t ## I can't boot into Solus after installation! -There are some misunderstandings with how legacy and EFI boot works (usually implemented as UEFI). These sections cover the common misconceptions. +There are some misunderstandings with how legacy and EFI boot work (usually implemented as UEFI). These sections cover the common misconceptions. ### Legacy/BIOS installation -Legacy installations on Solus use the Grub boot loader on an MBR disk. Only one boot loader can be used on an MBR disk, so if you haven't installed the Solus boot loader on the MBR, you will need to boot into the other OS and update grub prior to being able to boot Solus. This will also be required on each update of the kernel to ensure you're booting in the latest release. +Legacy installations on Solus use the GRUB boot loader on an MBR disk. Only one boot loader can be used on an MBR disk, so if you haven't installed the Solus boot loader on the MBR, you will need to boot into the other OS and update GRUB prior to being able to boot Solus. This will also be required on each update of the kernel to ensure you're booting the latest release. ### EFI -EFI allows for multiple boot loaders to be installed, which means you can boot the Solus boot loader directly. To ensure you are booting Solus you need to boot `Linux Boot Manager` from the EFI options. Common keys for bringing up a boot menu or the options during boot are hitting `Esc/F2/F9/F10/F11/F12` during boot (this differs per motherboard). If a boot loader for another OS is not listed in the menu, then it is not correctly registered (and therefore not installed correctly). You can make the Solus boot menu appear via [Displaying the Solus boot menu on boot](/docs/user/quick-start/boot-management#displaying-the-boot-menu-by-default-every-boot) which should be able to boot windows (as it's registered with UEFI properly) as well as Solus, but not other systems. +EFI allows for multiple boot loaders to be installed, which means you can boot the Solus boot loader directly. To ensure you are booting Solus you need to boot `Linux Boot Manager` from the EFI options. Common keys for bringing up a boot menu or the options during boot are hitting `Esc/F2/F9/F10/F11/F12` during boot (this differs per motherboard). If a boot loader for another OS is not listed in the menu, then it is not correctly registered (and therefore not installed correctly). You can make the Solus boot menu appear via [Displaying the Solus boot menu on boot](/docs/user/quick-start/boot-management#displaying-the-boot-menu-by-default-every-boot) which should be able to boot Windows (as it's registered with UEFI properly) as well as Solus, but not other systems. diff --git a/docs/user/troubleshooting/plasma.md b/docs/user/troubleshooting/plasma.md index 05878c874..c4bc1280f 100644 --- a/docs/user/troubleshooting/plasma.md +++ b/docs/user/troubleshooting/plasma.md @@ -17,10 +17,10 @@ This is often caused by a Firefox bug. It can be triggered by various things, li - Bringing up windows with keyboard shortcuts (ex: Super for the app menu, F9 for a drop down terminal) works, but they don't get focused. You can't interact with them. - Mouse cursor is stuck in move mode, it looks like a cross. -You may not need to reboot to recover from this state. Killing all firefox processes may be all that's necessary. To do so: +You may not need to reboot to recover from this state. Killing all `firefox` processes may be all that's necessary. To do so: 1. Open a virtual terminal by pressing `Ctrl+Alt+F3`. -1. Run the following to kill all firefox windows: +1. Run the following to kill all `firefox` windows: ```bash killall firefox