content/wiki/pkg_man.md

Package management is the process of installing, updating and removing software, tools and libaries.
On GNU/Linux systems, package management is usually done with a package manager. 

# MatterLinux Package Manager 
In a Matter system, package management is generally done with the MatterLinux Package Manager (`mp`).
`mp` lets you install, remove, update and search different MatterLinux packages accross different repos.

### Installation
`mp` should be already installed on a MatterLinux system. However if you want to install `mp` from
the source, then you should follow [this section](https://git.matterlinux.xyz/matter/mp#installation) 
from the README.

Note that you should run all the `mp` and releated commands as the root user.

### Configuration
Configuration file for `mp` can be found at `/etc/mp/cfg`. This file is used specify repos and 
configure general settings.

Here is the configuration shipped with the releases:
```
[general]
tmpdir = /tmp/mp

[base]
uri = https://pkgs.matterlinux.xyz/base

[desktop]
uri = https://pkgs.matterlinux.xyz/desktop
```
Lets start by breaking down the `[general]` section:

- `tmpdir (path)`: Specifies the temporary directory used by the `mp`. This directory will be used to save 
packages and signatures, most of the files in this directory will be removed after operation.

Other general configuration options are:

- `debug (yes/no)`: This setting is used to enable the debug logging, however `mp` don't have any 
debug logging (it will be implemented in the future) so there is no point at enabling it.

Next sections specify the repos. Section name is the repo name, and it **should match with the 
actual repo name**. Repo options are:

- `uri (URI)`: Repo URI, you can use `http`, `https` or `ftp` protocols.
- `signing (yes/no)`: Enable/disable PGP signature verification for the repo, by default it's enabled.

**IMPORTANT: DO NOT DISABLE SIGNATURE VERIFICATION IF YOU DON'T KNOW WHAT YOU ARE DOING! THERE IS NO 
WAY TO CONFIRM IF THE PACKAGES ARE LEGIT WITHOUT THE SIGNATURE VERIFICATION!**

### MP\_ROOT
Another configuration option that you can use is the `MP_ROOT` option. Unlike the other options,
this option is not specified in the configuration file, it's specified as an enviroment variable.

This option lets you change the target root directory. By default `mp` install all the packages to `/`,
stores all the information under the `/` etc. By chaning the target root directory you can change this.

For example lets say you want to install all the packages to `/tmp/testroot`. To do so, 
first you will need to setup a root file system structure inside `/tmp/testroot`:
```
# mkdir /tmp/testroot
# pushd /tmp/testroot
# mkdir -p etc boot dev home proc root run srv sys tmp usr/lib usr/bin usr/sbin var/lib
# ln -sf bin usr/bin
# ln -sf sbin usr/sbin
# ln -sf lib usr/lib
# ln -sf lib64 usr/lib
# popd
```
Now you can use `mp` with the `MP_ROOT` variable, for example:
```
# MP_ROOT=/tmp/testroot mp-sync
# MP_ROOT=/tmp/testroot mp-install which 
```

### Syncing Repos
To sync remote repo information and package lists, you can use the `mp-repo` command. After running it 
`mp` will:

1. Download the repo metada for all the repos. Repo metadata is located at `REPO_URI/repo`
2. Parse the repo metadata and download all the repo package lists. These lists are located at 
`REPO_URI/REPO_NAME.tar.gz`
3. Move and extract the repo lists to `$MP_ROOT/var/lib/mp/repos/REPO_NAME` and parse the plain package lists (`pkgs`)
4. Tell you the repo signatures 

You can add these signatures to your pubring with `gpg`: 
```
# gpg --receive-keys [fingerprint]
```

### Installing Packages 
To install a package, you can use the `mp-install` command:
```
# mp-install which 
```
After running this command, `mp` will:

1. Check all the synced repos for the `which` package 
2. Check if the package is already installed
3. Resolve all the dependencies for the `which` package
4. Ask you if you want to continue with the installation
5. Download the `which` package and it's signature from the repo to the `tmpdir`
6. Verify the package using the signature
7. Extract the package to `$MP_ROOT`
8. Run the package install script if it contains one 
9. Add an entry for the `which` package to `$MP_ROOT/var/lib/mp/db` and `$MP_ROOT/var/lib/mp/files`

You can also install multiple packages using the `mp-install` command:
```
# mp-install grub systemd linux
```

### Removing/Uninstalling Packages
To remove an installed package, you can use the `mp-remove` command:
```
# mp-remove which
```

After running this command, `mp` will:

1. Check all the installed packages to see if `which` is installed or not
2. Find all the files that `which` package extracted during the installation 
3. Ask you if you want to continue with the removal
4. Delete all the files found in the step 2
5. Remove the the package entry for the `which` package from `$MP_ROOT/var/lib/mp/db` and `$MP_ROOT/var/lib/mp/files`

You can also remove multiple packages:
```
# mp-remove git curl
```

### Updating Packages
You can update all of the installed packages using the `mp-update` command.
After running this command, `mp` will:

1. Check if all the installed packages are up-to-date 
2. Find all the packages that are not up-to-date
3. Ask if you want to continue with the update
4. Act like the `mp-install` command, it will download, verify and install all 
the packages, overwriting old files 
5. Save new up-to-date package entries to the `$MP_ROOT/var/lib/mp/db` and `$MP_ROOT/var/lib/mp/files`,
overwriting the old entries.

### Searching Packages
You can search for packages in the repos using the `mp-search` command:
```
# mp-search which
```
This will provide the following information about the package:
- Name of the package
- Repo that the package is in 
- Description
- Hash (sum)
- Version
- If the package is installed
- If the package is up-to-date

After running this command, `mp` will:

1. Check all the repos for the `which` package
2. Fetch information about the package from the `$MP_ROOT/var/lib/mp/repos/REPO_NAME` and `$MP_ROOT/var/lib/mp/db`. 

# Other Package Managers
It's a really bad idea to use multiple package managers as they may conflict and may result in an 
unstable system. However package managers such as flatpak and snap offer containerized packages,
making them possible to use with other package managers.

- Flatpak will be added to `desktop` repo in the future. Currently the only way to use flatpak is to 
install it from the source.
- Snap will never be added to any official repo, so only way to use it is to install it from the source.