matter/content
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adding new pages and reorganizing existing ones

Browse Source
This commit is contained in:
ngn
2024-01-19 14:29:23 +03:00
parent bf37ea1ad8
commit f001b26d84
32 changed files with 402 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
wiki/pkg/mirrors.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "mirrors",
"title": "Mirrors",
"author": "ngn",
"date": "12/01/24"
}

47
wiki/pkg/mirrors.md Normal file
View File

@ -0,0 +1,47 @@
Mirrors are web and FTP servers that mirror repos from the official repo web server.
# Usage
To use a mirror with `mp`, change the repo URI for the target repo in your `mp`
configuration file (`/etc/mp/cfg`).
### Creating a mirror
To create a mirror you can use the `matter-mirror` tool. This tool is included
with the `tools` repository. To install it [see the project READMDE](https://git.matterlinux.xyz/Matter/tools#installation).
After installing `matter-mirror`, specify an URI and an output directory (files will be downloaded
into the output directory). For example to mirror the `base` repo from
`https://pkgs.matterlinux.xyz/base` to `base_mirror` directory:
```
$ mkdir base_mirror
$ matter-mirror -u https://pkgs.matterlinux.xyz/base -o base_mirror
```
To serve the mirror, you can setup a web server such as `nginx`, or you can setup a FTP
server such as `pure-ftpd`.
You will mostly likely want to update your mirror every once in a while. To do so you can
create a cron job. For example to update your mirror every day at 00:00, you can add the
following entry to your `/etc/crontab`:
```
0 0 * * * <user> matter-mirror -u <url> -o <output dir path>
```
# List
This section contains information about different MatterLinux repo and mirros
that you can use. To add your mirror to this list get in contact with the maintainer/developers.
> **Note**
>
> Official mirrors are **ALWAYS** signed with the `F9E70878C2FB389AEC2BA34CA3654DF5AD9F641D`
> fingerprint (belongs to the maintainer, ngn). If syncing with a mirror tells you otherwise, then
> **DO NOT USE THAT MIRROR** and report it to the maintainer/developers in order to remove it
> from the list.
### Official repos
| Repo | URI | Location |
| ------- | -------------------------------------- | ----------- |
| base | `https://pkgs.matterlinux.xyz/base` | 🇹🇷 Turkey |
| desktop | `https://pkgs.matterlinux.xyz/desktop` | 🇹🇷 Turkey |
### Mirrors
Currently there are no available mirrors.

6
wiki/pkg/pkg.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "package",
"title": "Package",
"author": "ngn",
"date": "06/01/24"
}

138
wiki/pkg/pkg.md Normal file
View File

@ -0,0 +1,138 @@
A MatterLinux package is a compiled files of a software, tool or a library.
# Format
MatterLinux packages uses the **M**atterLinux **P**ackaging **F**ormat, `MPF`. Don't let fancy name
mislead you, a basic `MPF` file is just a renamed `TAR GZ` archive. The reason that packages use the
`.mpf` extension and not the `.tar.gz` extension is to make it easier to recognize and easier to work
with in the scripts and the tools.
### Naming
A package is named after the software and the version of that software that it provides. For
example package containing `bash` version `5.2.15` is named `bash_5.2.15.mpf`.
### Structure
File structure of a package matches with the MatterLinux root file structure. This is important
as a package will most likely be extracted in a MatterLinux root file system.
For example, we can take a look at the `which` package, to do this you can download the `MPF` file
and list its contents with the `tar tf` command:
```
usr/
usr/share/
usr/share/man/
usr/share/man/man1/
usr/share/man/man1/which.1
usr/share/info/
usr/share/info/dir
usr/share/info/which.info
usr/bin/
usr/bin/which
```
### Install Scripts
Some packages may contain an install script, `install.sh`, this shell script is ran by the
[MatterLinux Package Manager (`mp`)](/wiki/package_man) using the bash shell, right after the
extraction.
This script is used to do post-install actions, such as adding users, groups etc.
This script is located at the root of the package. For example let's take a look
at the `systemd` package:
```
...
etc/X11/xinit/
etc/X11/xinit/xinitrc.d/
etc/X11/xinit/xinitrc.d/50-systemd-user.sh
etc/credstore.encrypted/
install.sh
usr/
usr/lib/
usr/lib/libudev.so
usr/lib/libnss_resolve.so.2
...
```
# Usage
While installing a package using the [MatterLinux Package Manager (`mp`)](/wiki/package_man), `mp`
downloads the target package(s) from the repos, these packages are in the format discussed above.
After downloading and verifying the target package(s), `mp` extracts the packages using `libarchive`.
To learn more about this process see the [page for package management](/wiki/package_man).
It's also possible to install packages manually. To do this you can grab a package you want
and extract it to your the root directory by running: `tar xvf <package_version.mpf> -C /`
# Building
Package are built with the `mp-repo` tool. In order to build a package, you will need the source
for the repo that contains the package. This is because a package itself does not store any metadata,
this is all handled by the repo.
To learn more about the `mp-repo` tool, and how you can use it to build packages, see the
[repo package](/wiki/repo).
### Package Source
Source code for a packages can be found in the source code of the repo that the package is in.
Source files for a repo will be located under the `src` directory.
### Package Script
Each package source contains a `pkg.sh` shell script. This is the source script that is used to
build the package. In the build process, this shell script gets imported by the `mp-repo` tool
using the `source` command.
Let's take a closer look at a `pkg.sh` file:
```
NAME="which"
DESC="Shows the full path of (shell) commands"
VERSION="2.21"
FILES=("https://ftp.gnu.org/gnu/which/which-$VERSION.tar.gz")
HASHES=("097ff1a324ae02e0a3b0369f07a7544a")
DEPENDS=()
build() {
tar xf $NAME-$VERSION.tar.gz
cd $NAME-$VERSION
./configure --prefix=/usr && make
make DESTDIR=$ROOTDIR install
cd .. && rm -rf $NAME-$VERSION
}
```
This `pkg.sh` file is for the `which` package (version `2.21`). Let's start by breaking down the
variables:
- `NAME`: Specifies the package name. A package should be named after the software, tool or library
it provides. Preferably the name should not contain `_` to avoid confusion with naming.
- `DESC`: A short description about the software, tool or the library that package provides.
Explain what it does, what it contains etc.
- `VERSION`: Version of the software, tool or library the package provides. If you are using a
git commit version, you can name the version `LAST_VERSION+COMMIT_ID`
- `FILES`: Upstream files and patches needed to build this package, you can use `http`, `https`
or `ftp` protocols.
You can also specify multiple files. These files will be downloaded by `mp-repo` in the build
process.
- `HASHES`: Hashes for the files you specify. You can use `MD5`, `SHA1`, `SHA256` or `SHA512` sums.
And yes, you need to specify hashes for all the files, using the same order with the `FILES` variable.
- `DEPENDS`: Package(s) that this package depends on.
Now let's take a look at the `build` function. Each package needs a `build` function, this
function is called by `mp-repo` after downloading and verifying all the packages. It will be
called in the `$ROOTDIR`. This directory will contain all the downloaded files, any files
in this directory will be included into the build, so don't forget to cleanup.
> **Note**
>
> You don't need to cleanup the downloaded files in the package script,
> they will be cleaned by the `mp-repo`.
- `tar xf $NAME-$VERSION.tar.gz`: Extract the downloaded archive file.
- `cd $NAME-$VERSION`: Change directory into the extracted directory.
- `./configure --prefix=/usr && make`: Builds the `which` tool, different packages may have
different build instructions. These instruction are usually provided by the upstream. You can
also check out [LFS](https://www.linuxfromscratch.org/lfs/view/12.0-systemd/) and [BLFS](https://www.linuxfromscratch.org/blfs/view/12.0-systemd/) for instructions.
- `make DESTDIR=$ROOTDIR install`: Install the package. Make sure that you are installing the package
into the `$ROOTDIR` and not the root file system.
- `cd .. && rm -rf $NAME-$VERSION`: Change directory back into `$ROOTDIR` and clean the extracted archive.
Check out [`base`](https://git.matterlinux.xyz/Matter/base) and
[`desktop`](https://git.matterlinux.xyz/Matter/desktop) repo sources for more
example `pkg.sh` scripts.

6
wiki/pkg/pkg_man.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "package_man",
"title": "Package Management",
"author": "ngn",
"date": "15/01/24"
}

200
wiki/pkg/pkg_man.md Normal file
View File

@ -0,0 +1,200 @@
Package management is the process of installing, updating and removing software, tools and libraries.
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 across 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**
>
> You should run all the `mp` and related 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 are you doing! There is no
> way to confirm the legitimacy of the packages without signature verification!
### Environment options
`mp` also has a few other options that you specify as an environment variable.
One of these is the `MP_ROOT` option. 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 changing 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
```
Another one of these environment options is the `MP_YES` option. By default operations such as
installing packages, updating packages and removing packages will ask you to confirm the operation
using an interactive yes/no prompt. To disable this prompt and confirm all operations by default,
you can set the `MP_YES` environment variable. You can set it to whatever you want, just make sure
it's set.
`MP_NORET` is another option that you can set. By default `mp` will print the return status for each
command, you can disable this by setting `MP_NORET` to whatever you want.
The last one of these options is the `MP_QGREP` option. This option is only useful if you are using
the query command. If set, `mp` will print grep-able output for this command. Again, you can set it
to whatever you want.
### 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 metadata 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 public key ring 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 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.
For example, this command will return a list of all the packages that contain `lib`
in their name:
```
# mp-search lib
```
After running this command, `mp` will:
1. Check all the repos for any packages that contain `lib` in the name
2. Print the package
3. Print the count of the results
### Querying packages
You can get more information about a package by querying it. For example to get
more information about the `which` package:
```
# mp-query 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.

6
wiki/pkg/release.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "release",
"title": "Releases",
"author": "ngn",
"date": "15/01/24"
}

74
wiki/pkg/release.md Normal file
View File

@ -0,0 +1,74 @@
On this package you will find information about MatterLinux release cycle and
version numbering.
## Release Cycle
MatterLinux will make a new release once a year. A new release means every package will be updated
to a more recent version. Packages will replace the old ones,
meaning old packages will no longer be available and support for the old release will end.
If you are using an old release, you will able to update to the latest one by running a
full update using the [MatterLinux Package Manager](/wiki/package_man).
During the testing of the new release, repos for the new release will be located
at [next.matterlinux.xyz](https://next.matterlinux.xyz).
### Package Updates
Packages usually won't be updated to a more recent version during the life of a MatterLinux release,
however sometimes packages may be updated for bug fixes, security issues and minor improvements.
### ISOs and Release Archives
- ISO: A bootable disk image
- Release Archive: An archive used during the installation of a release
With new release, a new ISO and a release archive will be published. ISO and release
archive file for a release may update before the next release to keep the
packages in these archive files and the ISOs up-to-date.
### Learn the version you are using
You can learn the MatterLinux release version you are using by printing
out the `/etc/os-release` file:
```
# cat /etc/os-release
```
## Version Numbering
MatterLinux and all it's projects are version numbered after the year.
For example MatterLinux release for the year 2024 is versioned "MatterLinux 24".
Minor numbers may be added for other releases. For example the 2nd release of the
MatterLinux 24 ISO would be named "MatterLinux 24.01".
Similarly 15th release of the MatterLinux package manager for the year 2024
is versioned "24.14".
## Building Releases
You can build an up-to-date ISO and a release archive using MatterLinux [tools](https://git.matterlinux.xyz/matter/tools).
To install these tools [see the project READMDE](https://git.matterlinux.xyz/Matter/tools#installation).
You should be on a MatterLinux system for a proper build!
### Building the Release Archive
To build a release archive, you can use the `matter-base` tool. This tool will create a temporary directory,
install all the required base packages into it and then it will archive it all up for the final archive.
All you need to do is to specify a name for the archive, for example:
```
# matter-base matterlinux_example-build
```
### Building the ISOs
Official ISOs are built using the `matter-iso` tool. By providing a release archive and a configuration
directory to this tool, you can create an ISO image.
> **Note**
>
> ISO image is created using `grub-mkrescue`, so you should install `libisoburn` before proceeding.
As the configuration directory, you can clone the [official ISO configuration](https://git.matterlinux.xyz/Matter/iso).
Or you can use your own custom configuration.
To build the ISO with the release archive that we created on the previous example, using the configuration directory
located at `./iso`:
```
# matter-iso matterlinux_example-build.tar.gz iso
```
The final ISO should be available at `./iso/dist/<name_version>.iso` after the build.

6
wiki/pkg/repo.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "repo",
"title": "Repo",
"author": "ngn",
"date": "11/01/24"
}

115
wiki/pkg/repo.md Normal file
View File

@ -0,0 +1,115 @@
A MatterLinux repo is a FTP or web server that contains unique [packages](/wiki/package).
# Structure
A repo contains:
- Packages (`.mpf`)
- Package signatures (`.mpf.sig`)
- Repo metadata
- Package list
### Package Files and Signatures
MatterLinux repos 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 repo metadata.
### Repo Metadata
Repo metadata contains information about the repo itself. Such as the repo name,
author and the public key used to sign the packages.
This metadata can be found in the `repo` file at the root of the repo. For example
the repo metadata for `https://pkgs.matterlinux.xyz/base` is located at
`https://pkgs.matterlinux.xyz/base/repo`. `INI` format is used for this metadata file.
### Package List
A list containing all packages and all the package metadata can be found in an
archive file named after the repo. For example the package list for
`https://pkgs.matterlinux.xyz/base` is located at `https://pkgs.matterlinux.xyz/base/base.tar.gz`.
This archive file contains a file named `pkgs`, which contains repo package list in the
`INI` format. It contains the package names, descriptions, versions, sums and dependencies.
### Repo Source
Source for a repo has a simple structure that also contains all the source files for the packages.
For example lets take a look the structure of the [`base`](https://pkgs.matterlinux.xyz/base)
repo source:
```
├── dist
│   ├── acl_2.3.1.mpf
│   ├── acl_2.3.1.mpf.sig
│   ├── base.tar.gz
│  ...
│   ├── repo
│   ├── sed_4.9.mpf
│   ├── sed_4.9.mpf.sig
│  ...
├── LICENSE.txt
├── README.md
├── repo.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 repo. **All the packages in the repo should use a license
compatible with this license.**
- `README.md`: README file. Contains a small description about the repo.
- `repo.sh`: Repo script contains information about the repo, later used to build the
repo metadata.
- `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 repos. 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.
# Usage
MatterLinux provides 2 different official repos:
- [`base`](https://pkgs.matterlinux.xyz/base): Contains base system packages such as `glibc`, `systemd`,
`linux` etc.
- [`desktop`](https://pkgs.matterlinux.xyz/desktop): Additional packages users may want to install
for a more ideal desktop system.
This repos can provide packages for users, these packages can be managed using the
[MatterLinux Package Manager (`mp`)](https://git.matterlinux.xyz/matter/mp). For more information see the page for [package management](/wiki/package_man).
### Building an already existing repo
To build an already existing repo, such as the `base` or the `desktop` repo, first you will need to
download the repos source. Source for the `base` and the `desktop` repo can be found on
[MatterLinux Git Server](https://git.matterlinux.xyz/matter).
After downloading the repo source, you will need to install the `mp-repo` tool, which is the tool
used for building MatterLinux repos. To do so please follow the steps [here](https://git.matterlinux.xyz/Matter/mp-repo#installation).
Finally to build the repo:
```
$ mp-repo <repo dir>
```
You will mostly likely want to disable package signing though, as you are probably not the
owner of the repo:
```
$ mp-repo --no-sign <repo dir>
```
### Creating a new repo
If you want to create an unofficial repo, setup the folder structure for the source repo as
explained above. Then create a repo script, you can copy one from the official repos and
edit it.
After adding your packages and building them with `mp-repo`, you can host them on an FTP
or a web server to make it available to other people. Also you can add this unofficial repo
to this wiki page [by creating an issue](https://git.matterlinux.xyz/Matter/content/issues).