content/wiki/pkg/pools.md

On this page, you will find information about MatterLinux package pools.

# Structure 
A pool contains:

- [Packages](/wiki/packages) (`.mpf` files)
- Package signatures (`.mpf.sig` files)
- Pool info file (`INFO`)
- Package list file (`LIST`)

### Package files and signatures
MatterLinux pools contain at least two package. Each package also has a PGP signature 
that can be used to verify the package. These signatures belong to public key fingerprint
specified in the pool metadata.

### Pool info file
Pool info file contains information about the pool itself. This information includes
- Pool name
- Pool size
- Pool maintainer
- Pool public key (used for package signatures)

This info file can be found in the at the root of the pool. For example the pool info file 
for `https://pkgs.matterlinux.xyz/base` is located at `https://pkgs.matterlinux.xyz/base/INFO`.
`INI` format is used for this file.

### Package list file
A list containing all the package information can be found in an archive file named `LIST`.
This file is located at the root of the pool. For example the package list for `https://pkgs.matterlinux.xyz/base`
is located at `https://pkgs.matterlinux.xyz/base/LIST`.

This archive has the following structure:
```
list
├── package-one_version 
│   └── DATA
├── package-two_version
│   └── DATA 
...
```
The `DATA` file contains the information for that specific package and it's extracted from packages.
To learn more about these please check out the page for [packages](/wiki/packages).

### Pool sources
Source for a pool has a simple structure. It also contains all the source files for all the packages in
that pool. For example lets take a look the structure of the [`base`](https://pkgs.matterlinux.xyz/base) 
pool source:
```
base
├── dist
│   ├── acl_2.3.1.mpf
│   ├── acl_2.3.1.mpf.sig
│   ├── INFO
│   ...
│   ├── LIST
│   ├── sed_4.9.mpf
│   ├── sed_4.9.mpf.sig
│   ...
├── LICENSE.txt
├── README.md
├── pool.sh
├── sign-dist.sh
└── src
    ├── acl
    │   └── pkg.sh
    ├── attr
    │   └── pkg.sh
    ├── autoconf
    │   └── pkg.sh
    ├── automake
    │   └── pkg.sh
    ├── bash
    │   ├── pkg.sh
    │   ├── skelprof
    │   └── skelrc
    ...
```
Let's break this down:

- `LICENSE.txt`: License used for the pool. **All the packages in the pool should use a license
compatible with this license.**
- `README.md`: README file. Contains a small description about the pool.
- `pool.sh`: Pool script contains information about the pool, used to build the 
pool info file.
- `src`: Contains package sources (package scripts, extra patches, configuration files etc.)
- `dist`: Contains the compiled (built) packages. 
- `sign-dist.sh`: An extra shell script that you can find in the official pools. It is just a 
small script that is used to sign all the packages in the `dist` directory if they are built 
without the signatures.

# Using different pools
MatterLinux releases offer 2 different pools, `base` and `desktop`. There are also development/testing 
`base` and `desktop` pools (named "next"). URLs for these pools and the mirrors can be found at the [mirrors page](/wiki/mirrors). 

These pools can provide packages for users, these packages can be managed using the 
[MatterLinux package manager (`mp`)](/wiki/mp).

### Building an already existing pool 
To build an already existing pool, such as the `base` or the `desktop` pool, first you will need to 
download the pool's source. Source for the `base` and the `desktop` pool can be found on [MatterLinux Git Server](https://git.matterlinux.xyz/matter).

After downloading the pool source, you will need to install the `mp-pool` tool, which is the tool 
used for building MatterLinux pools. To do so please follow the steps [here](https://git.matterlinux.xyz/Matter/mp-pool#installation).

Finally to build the pool:
```
$ mp-pool <pool dir>
```

You will mostly likely want to disable package signing though, as you are probably not the 
owner of the pool:
```
$ mp-pool --no-sign <pool dir>
```

### Hosting pools
Unlike most of the package managers, `mp` does not use HTTP, FTP or RSYNC to communicate with the pools. It has it's own
custom protocol named [MPTP](/wiki/mptp). Pools are hosted over this protocol using [pooler](https://git.matterlinux.xyz/matter/pooler).

To get host a pool using `pooler`, download and install the `pooler` by following the instructions on the [README](https://git.matterlinux.xyz/matter/pooler). It's also in the official pools so you can install it with `mp` as well. 
After installing it, you can simply host the pool by running:
```
$ pooler <pool dir>
```
This will start the MPTP server on port 0.0.0.0:5858. You can also host multiple pools by specifying them:
```
$ pooler <pool dir 1> <pool dir 2> <pool dir 3>
```
Note that each pool needs to have a unique name for in order to host multiple pools using the same
pooler instance.

If you want to change the service address, you can do so by using the `-h` and the `-p` flag:
```
$ pooler -h 0.0.0.0 -p 5566 <pool dir>
```
You can also specify host names for your pools:
```
$ pooler <pool dir 1>::p1.example.com <pool dir 2>::p2.example.com
```

### Creating a new pool 
If you want to create an unofficial pool, setup the directory structure for the source pool as 
explained above. Then create a `pool.sh` script, you can copy one from the official pools and 
edit it.

After adding your packages and building them with `mp-pool`, you can host it using pooler.
I suggest you also host them on a HTTP or a FTP server just to make them easier to access.
Doing so will also allow other people to use [`matter-mirror` tool to mirror your pool](/wiki/mirrors).

Also you can add your unofficial pool to this wiki page [by creating an issue](https://git.matterlinux.xyz/Matter/content/issues).