Skip to content

Commit

Permalink
Package management re-organization (#558)
Browse files Browse the repository at this point in the history 
* Update history and rollback to comply to the style guide

* Reorganize basics.md

- Reformat the topic as a table for better scannability.
- Move the "Base development tools"
section to the development topic

* Re-organize repo-management.md

- Apply the style guide to the topic.
- Re-organize the topic for better scannability.

* Update package management based on feedback.

* Edit note in the "Rollback" section for clarity
  • Loading branch information
@deoxys94
deoxys94 authored Sep 7, 2024
1 parent 360c04d commit 7b65069
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 202 deletions.
109 changes: 12 additions & 97 deletions docs/user/package-management/basics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,103 +3,18 @@ title: Basics to Package Management
summary: Basics to Package Management
---

# Basics to Package Management
# Basics of package management in Solus

Solus uses the eopkg package management system to deliver software to the end-user.
Below are some basic commands for using eopkg.
Solus uses the eopkg package manager. You can use `eopkg` to install, update, and remove software packages on your Solus system.

## Installing software
The following table lists the most common `eopkg` commands:

You can install one or more packages by using:

```bash
sudo eopkg install packagename
```

For example:

```bash
sudo eopkg install gnome-documents gnome-music
```

## Reinstalling software

You can reinstall one or more packages by using:

```bash
sudo eopkg install --reinstall packagename
```

For example:

```bash
sudo eopkg install --reinstall gnome-documents gnome-music
```

## Uninstalling software

You can uninstall one or more packages by using:

```bash
sudo eopkg remove packagename
```

For example:

```bash
sudo eopkg remove gnome-documents gnome-music
```

## Get information on software

You can get information on software, such as its description, version, installation size, and more, by using

```bash
eopkg info packagename
```

For example:

```bash
eopkg info gnome-documents
```

## Updating

You can update your system by using:

```bash
sudo eopkg upgrade
```

If you want to **only** update a specific piece of software on your system, you can specify is like below:

```bash
sudo eopkg upgrade firefox
```

## Searching

You can search the software selection Solus provides by using:

```bash
eopkg search term
```

For example:

```bash
eopkg search documents
```

Notice that you don't need to search for a specific software name, although you can do that. We search summaries and software names by default.

## Base development tools

If you are wanting to compile software under Solus, we recommend installing our `system.devel` component by running the following:

```bash
sudo eopkg install -c system.devel
```

This will provide items such as `clang`, `gcc`, `make`, a multitude of devel sub-packages, and more. Our `system.devel` is similar to packages on other operating systems, such as Debian's build-essentials.
| Action | Command | Example |
| ----------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| Install software | `sudo eopkg install PACKAGE_NAME` | `sudo eopkg install gnome-documents gnome-music` |
| Reinstall software | `sudo eopkg install --reinstall PACKAGE_NAME` | `sudo eopkg install --reinstall gnome-documents gnome-music` |
| Uninstall software | `sudo eopkg remove PACKAGE_NAME` | `sudo eopkg remove gnome-documents gnome-music` |
| Update your system | `sudo eopkg upgrade` | - |
| Update specific software | `sudo eopkg upgrade PACKAGE_NAME` | `sudo eopkg upgrade firefox` |
| Search for software | `eopkg search KEYWORD` | `eopkg search documents` |
| Get information on software, such as description or version | `eopkg info PACKAGE_NAME` | `eopkg info gnome-documents` |
Binary file added docs/user/package-management/eopkg-history-output.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
55 changes: 39 additions & 16 deletions docs/user/package-management/history-and-rollback.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,57 @@ title: History and Software Rollback
summary: History and Software Rollback
---

# History and Software Rollback
# History and software rollback in Solus

Solus provides a history and rollback feature via its package manager, `eopkg`. This feature allows you to see when your repository was last updated, actions such as installation, removal, and upgrading of software.
Solus offers a feature to view your history of software changes and revert your system to previous versions.

Our rollback feature allows you to essentially rewind your system's software back to a previous state, assuming you or our repository has the versions in question.
You can use this feature if you have issues after installing packages or system updates, and you need to return to a working state.

## History
## History of software changes

You can see the history from `eopkg` by using:
- To see your history of software changes, open a terminal and execute:

```bash
eopkg history
```
```bash
eopkg history
```

The terminal displays a list of all the software changes in your system.

![eopkg history output](./eopkg-history-output.png)

## Rollback

:::info
:::warning[Important]

If you have a local repository set up, [disable it](https://help.getsol.us/docs/packaging/advanced-config/local-repository#disabling-the-local-solbuild-repository-in-eopkg) before doing rollbacks or you may get an error.
Reverting software changes works if either:

> Error parsing repository index information. Index file does not exist or is malformed.
- The Solus repository has the version of the package you need, or
- You have a local copy of the package.

:::

To rollback your system, first use the above history command to check what the transaction / operation number was. Then, we use the following command:
1. Disable any [local repository](https://help.getsol.us/docs/packaging/advanced-config/local-repository#disabling-the-local-solbuild-repository-in-eopkg) you have.

Local repositories can cause errors during rollbacks.

1. Open a terminal.

1. View the history of software changes:

```bash
sudo eopkg history
```

1. Note the number of the most recent software change.

1. Go back to the desired state:

```bash
sudo eopkg history -t NUMBER
```

Replace `NUMBER` with a number lower than the latest software change.

```bash
sudo eopkg history -t number
```
For example, if you want to revert operation 100, use 99 as the number.

The number, in this case, is the operation before the one you want to change. So if the number was `100`, then you would use `99`.
After reverting to the desired state, verify your system status. You might need to restart your system to see some of the changes.
111 changes: 22 additions & 89 deletions docs/user/package-management/repo-management.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,103 +3,36 @@ title: Repository Management
summary: Repository Management
---

# Repository Management
# Repository management

While Solus currently only provides two repositories, stable (shannon) and unstable, our package manager does support actively using multiple repositories on your system. This is useful if you are using a vendor-provided repository.
Solus offers two main software sources: stable (shannon) and unstable. The `eopkg` package manager can use multiple sources on your system, which is helpful if you use a source provided by another vendor.

## Official Solus repositories
## Official repositories

The official Solus repositories are:

| Repository | URL | Notes |
| -------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stable (shannon)** | `https://cdn.getsol.us/repo/shannon/eopkg-index.xml.xz` | This is the default repository. |
| **Unstable** | `https://cdn.getsol.us/repo/unstable/eopkg-index.xml.xz` | This repository should only be used if you intend to build Solus packages or to test new packages before they are synced to the _stable_ repository. |
| Repository | URL | Notes |
| ---------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Stable (shannon) | `https://cdn.getsol.us/repo/shannon/eopkg-index.xml.xz` | Default software source. |
| Unstable | `https://cdn.getsol.us/repo/unstable/eopkg-index.xml.xz` | Only use this source if build Solus packages or you test new software before it moves to the stable source. |

:::danger

It is not always safe to perform a system update when using the **unstable** repository. Always check the topic of the [#solus-packaging](https://matrix.to/#/#solus-packaging:matrix.org) Matrix room before updating.
Updating your system while using the **unstable** source might be risky.

:::

## Adding a repository

You can add a repository by using:

```bash
sudo eopkg add-repo Name URL
```

For example:

```bash
sudo eopkg add-repo Example https://example.com/repo/eopkg-index.xml.xz
```

**Note:** This does not enable the repository.

## Removing a repository

You can remove a repository by using:

```bash
sudo eopkg remove-repo Name
```

For example:

```bash
sudo eopkg remove-repo Example
```

## Enabling a repository

You can enable a repository for usage, by using:

```bash
sudo eopkg enable-repo Name
```
Before updating, check the [#solus-packaging](https://matrix.to/#/#solus-packaging:matrix.org) Matrix room.

For example:

```bash
sudo eopkg enable-repo Example
```

## Disabling a repository

You can disable a repository by using:

```bash
sudo eopkg disable-repo Name
```

For example:

```bash
sudo eopkg disable-repo Example
```

## Updating a repository

You can update the index of a repository by using:

```bash
sudo eopkg update-repo Name
```

For example:

```bash
sudo eopkg update-repo Example
```

**Note:** You can update all repositories by **not** providing a name.

## List repositories

You can list all the repositories added on your system by using:
:::

```bash
eopkg list-repo
```
## Repository management commands

The following table lists the `eopkg` commands you can use to manage your software sources.
| Action | Command | Example |
| -------------------------------------- | ------------------------------ | ------------------------------------------------------------------------- |
| Add a repository | `sudo eopkg add-repo NAME URL` | `sudo eopkg add-repo Example https://example.com/repo/eopkg-index.xml.xz` |
| Remove a repository | `sudo eopkg remove-repo NAME` | `sudo eopkg remove-repo Example` |
| Enable a repository | `sudo eopkg enable-repo NAME` | `sudo eopkg enable-repo Example` |
| Disable a repository | `sudo eopkg disable-repo NAME` | `sudo eopkg disable-repo Example` |
| Update a repository | `sudo eopkg update-repo NAME` | `sudo eopkg update-repo Example` |
| Update all repositories | `sudo eopkg update-repo` | `sudo eopkg update-repo` |
| List repositories added to your system | `eopkg list-repo` | `eopkg list-repo` |

0 comments on commit 7b65069

Please sign in to comment.