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

update: small wiki fixes and minor tweaks

Browse Source
This commit is contained in:
ngn
2024-08-21 03:53:10 +03:00
parent 0ff4366363
commit 2269f448ed
34 changed files with 168 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
wiki/package/create.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "create",
"title": "Create a package",
"author": "ngn",
"date": "04/08/24"
}

274
wiki/package/create.md Normal file
View File

@ -0,0 +1,274 @@
On this page, you will learn how you can create your first
MatterLinux package for the official pools.
## Pre-requirements
- You should have an up-to-date MatterLinux installation
- You should have general understanding of software packaging
- You should have general understanding of building/compiling software
- You should know the basics of bash scripting
- You should know the basics of git version control system
## Getting started
If you want to add your package to the official pools, then please
check the [official pool guidelines](/wiki/pool_guides). Make sure
that your package follows the guidelines or your pull request may be
rejected.
Also, create an account on Gitea server and configure your editor
as specified in the [contribution guide](/wiki/contribute).
## Install requirements
To follow this tutorial you will need a working MatterLinux installation
(minimum version 24.05). You also need to install the following packages
from the [`base` pool](/wiki/pools):
- an editor (`vim` and `nano` is avaliable on the `base` pool)
- build-essential
- [mtsc](https://git.matterlinux.xyz/matter/mtsc)
- git
## Selecting a pool
If you want to add a new package to the official pools, you should
first choose the pool you want to add the package to. You should check
the [list of official pools](/wiki/pools), and figure out which pool
your package belongs to.
## Fork the pool
After selecting the pool, fork it on Gitea and clone it to MatterLinux
system:
```
$ git clone <git repository url>
```
Create a new branch for your package:
```
$ git branch -m new-package
```
To build and create packages, you should install the `build-essential` package from the
[`base` pool](/wiki/pools). This package will provide you with all the base tools
required, such as the GNU C compiler. You will also need
## Create the package template
Change directory into the `src` folder of the pool you cloned, and use the `mp-new`
command (a script from `mp-build`) to create an empty package script:
```
$ cd src
$ mp-new <name of the package>_<version of the package>
```
Package name should be **full lowercase**, it should not contain any non-English characters,
and it should not contain underscore (`_`). If there is an underscore in the package name, replace
it with `-`. Package name also **should NOT contain a version number**.
Version name ideally should contain a version number separated with dots. However this may heavily
change based on how the upstream actually versions the software. Version should also be updated
after every modification. If the modification does not change the upstream version, then you should
suffix the version with `m<number of changes>`, for example `1.2m1`, `8.7.3m7` etc. Version name should
also not contain underscores (`_`), you should replace them with `-`.
For this example we will be packaging the `LXTerminal` (version `0.4.0`) from LXDE:
```
$ cd src
$ mp-new lxterminal_0.4.0
```
## Modify the package script
`mp-new` will create a directory for the new package, named after the package, which will contain a `pkg.sh` script.
This script is called the **package script**. Open this script with the configured editor:
```
# general info
NAME="lxterminal"
DESC=""
VERSION="0.4.0"
# required files
FILES=()
HASHES=()
# install and build depends
DEPENDS=()
BUILD=()
PACKAGE() {
tar xf "${NAME}-${VERSION}.tar.gz"
cd "${NAME}-${VERSION}"
cd .. && rm -r "${NAME}-${VERSION}"
}
```
### Description
First of all you should add a description. Description should be short (less than 200 characters), and
it should explain details about the package. Ideally, description should not contain words such as "*contains*"
and "*includes*". Here are some **bad examples**:
- *LXTerminal package contains a VTE-based terminal emulator*
- *LXTerminal includes the LXDE terminal emulator*
And here are some **good examples**:
- *VTE-based terminal emulator for LXDE*
- *LXDE terminal emulator*
### Version
You should package a stable version of the software, do not package the latest git commit or
something like that. **Package an official released version.**. For this example we will be
packaging the version `0.4.0`.
### Files
List of files needed for this package, you can specify `HTTP(S)` or `FTP(s)` URLs. Or you can
specify simply just filenames to pull the packages from the local source directory.
If possible, you should replace the version number in the URL with the `VERSION` variable.
### Hashes
Specify hashes for the files you specified, you can use the `NOHASH` as the hash to disable
hash verification for a specific file.
### Depends
Run-time dependencies for the package, **do not** specify the make or the build dependencies that are only used
for compiling the software.
### Build
Build-time dependencies for the package, **dot not** specify any run-time dependencies again if they are also needed
for the build process. Also **do not** specify any package that is part of `build-essential`.
With the addition of the details above, here is how our example package script looks like:
```
# general info
NAME="lxterminal"
DESC="Commands for manipulating POSIX Access Control Lists"
VERSION="0.4.0"
# required files
FILES=("https://downloads.sourceforge.net/lxde/lxterminal-$VERSION.tar.xz")
HASHES=("7938dbd50e3826c11f4735a742b278d3")
# install and build depends
DEPENDS=("vte")
BUILD=()
PACKAGE() {
tar xf "${NAME}-${VERSION}.tar.gz"
cd "${NAME}-${VERSION}"
cd .. && rm -r "${NAME}-${VERSION}"
}
```
### Package function
The package function contains the instructions for building the package itself. When building the package, `mp-build`
will download all the files and remove them after the build, so you do not have to deal with that.
To make your life simpler, `mp-new` creates a boilerplate `PACKAGE()` function template. Now will modify it
to make it work our package.
First, we should do is to extract the downloaded file, and change directory into the newly extracted folder:
```
tar xf "${NAME}-${VERSION}.tar.gz"
cd "${NAME}-${VERSION}"
```
Then we can change directory into the pool source directory and run the build and install instructions:
```
./configure --enable-man --prefix=/usr
make && make install
```
With this configuration, `make install` will try to install the package to the actual system, however
we want to install the package to the package build directory, so we will use the `DESTDIR` flag for that:
```
./configure --enable-man --prefix=/usr
make
make DESTDIR="${ROOTDIR}" install
```
`$ROOTDIR` is a custom variable that is set during the package build. During the build it will point to the
package build directory.
After building and installing the package, we can change directory back up, and remove the extracted folder:
```
cd .. && rm -r "${NAME}-${VERSION}"
```
So the final script should look like this:
```
# general info
NAME="lxterminal"
DESC="Commands for manipulating POSIX Access Control Lists"
VERSION="0.4.0"
# required files
FILES=("https://downloads.sourceforge.net/lxde/lxterminal-$VERSION.tar.xz")
HASHES=("7938dbd50e3826c11f4735a742b278d3")
# install and build depends
DEPENDS=("vte")
BUILD=("intltool")
PACKAGE() {
tar xf "${NAME}-${VERSION}.tar.xz"
cd "${NAME}-${VERSION}"
./configure --enable-man --prefix=/usr
make
make DESTDIR="${ROOTDIR}" install
cd .. && rm -r "${NAME}-${VERSION}"
}
```
## Formatting the package script
When you are done, format the package script following these rules:
- If you have multiple files, put each one of them to a new line, same for the hashes.
- If you have more than 5 depends, split them into new lines, grouping 3 depends together.
- If you have long commands in the build function, split them to new lines using a backslash (`\`)
- Prevent using `&&` unless it's absolutely necessary, it usually ends up messing the error checking
- Split unrelated instructions with a newline
You can use the `mp-check` script to automatically check for some of these issues:
```
$ mp-check lxterminal
```
## Building the package
To build the newly created package, run the following in the `src` directory:
```
$ mp-build --no-sign lxterminal
```
This will install all the required dependencies, and only build the specified package.
## Testing the package
When build is completed, you will have a new `.mpf` package archive in the `dist` directory
of the package directory. You can check this archive for any potential issues using `mp-check`
again:
```
$ mp-check lxterminal/dist/lxterminal_0.4.0.mpf
```
After fixing any potential issues and warnings, you can install your newly created package using
the [package manager](/wiki/matt) and test it out:
```
# matt install --yes lxterminal/dist/lxterminal_0.4.0.mpf
$ lxterminal
```
## Stage and commit your changes
After making sure that the package is working as intended, go back to the root of the pool source directory,
and use `git add .` to stage all the changes. Then use `git commit -m <message>` command to commit them. For the
commit message, follow the guidelines on the [contribution page](/wiki/contribute). For our example, the following
message should be fine:
```
$ git commit -m "new: lxterminal package"
```
Then push your branch to the remote:
```
$ git push -u origin new-package
```
## Creating a pull request
Back on the Gitea, create a pull request to the official repository. Provide information about
the package you added, and explain why you think its important to include this package.
Please patiently wait for a response from the maintainer(s) after creating your pull request,
if find out any problems with your package after creating the pull request, fix them and make more commits
to your new branch, they should automatically be added to the pull request.
## You are done!
If you follow every step correctly your pull request will be merged. After the merge, your package will
be added to the [development (next) pools](/wiki/pools) and after some testing it will make it's way to
the stable pools.

6
wiki/package/packages.json Normal file
View File

@ -0,0 +1,6 @@
{
"id": "packages",
"title": "Packages",
"author": "ngn",
"date": "04/08/24"
}

145
wiki/package/packages.md Normal file
View File

@ -0,0 +1,145 @@
On this page, you will find information about MatterLinux packages.
# 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 Gunziped TAR 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 follows this format:
```
package_1.0.mpf
├── DATA
├── CHANGES
├── INSTALL
├── HASHES
└── files.tar.gz
```
Let's break this down:
- `DATA`: An `.ini` formatted file, contains information about package name, version, description,
dependencies, files to keep (save) during update/removal and SHA256 hash of the `MPF` file.
- `CHANGES`: A changelog file, containg information about the chnages accross different package versions
- `INSTALL`: An optional shell script. If it's not empty, then should be ran after the installation. This file
is also named the "install script".
- `HASHES`: Contains MD5 hashes of every file in the `files.tar.gz` archive. Summaries are
followed by a white space (` `) and the full file path. These paths do not start with `/`,
also they do not end with a `/`.
- `files.tar.gz`: The actual files that the package contains, which should be installed.
File structure of the `files.tar.gz` archive matches with the MatterLinux root file structure. This is important
as this archive 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,
extract it in a temporary folder, and list the contents of `files.tar.gz` with the `tar tf files.tar.gz`
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 non-empty install script, `INSTALL`, this shell script is ran by the
[MatterLinux Package Manager (`matt`)](/wiki/matt) using the bash shell, right after the
extraction of `files.tar.gz`, in the package installation directory (usually `/`).
This script is used to do post-install actions, such as adding users, groups etc.
# Working with packages
While installing a package using the [MatterLinux Package Manager (`matt`)](/wiki/matt), `matt`
downloads the target package(s) from the pools, these packages are in the format discussed above.
After downloading and verifying the target package(s), `matt` extracts the packages using `libarchive`.
To learn more about this process see the [page for package management](/wiki/matt).
### Building packages
Package are built with the [`mp-build` tool](https://git.matterlinux.xyz/matter/mp-build). In order to
build a package, you will need the source of the package, which can be found in the source tree of the
pool which contains the package.
After obtaining the source, package can be simply built by running:
```
$ mp-build <package dir>
```
To learn more about building and creating packages, please [see this page](/wiki/create_packages).
### Package scripts
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 sourced by the `mp-build` 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=()
PACKAGE() {
tar xf "${NAME}-${VERSION}.tar.gz"
cd "${NAME}-${VERSION}"
./configure --prefix=/usr && make
make DESTDIR="${ROOTDIR}" install
cd .. && rm -r "${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+FIRST_7_CHARS_OF_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-build` in the build
process.
- `HASHES`: Hashes for the files you specify. You can use `MD5`, `SHA1`, `SHA256` or `SHA512` hashes.
And yes, you need to specify hashes for all the files, using the same order with the `FILES` variable.
You can also specify `NOHASH` instead of a hash if you want to skip hash checking for a file.
- `DEPENDS`: Package(s) that this package depends on.
There are also other options that are not present in this example:
- `KEEP`: A list of files to keep during the update/removal of the package
- `BUILD`: A list packages required for building this package
Now let's take a look at the `PACKAGE` function. Each package needs a `PACKAGE` function, this
function is called by `mp-build` after downloading and verifying all the files. 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-build`.
- `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 -r "${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)
pool sources for more example package scripts.