content/wiki/pkg/create.md

On this you will learn how you can create your first MatterLinux package for the official repos.

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 repos, then please check the official repo guidelines. Make sure that your package follows the guidelines or your pull request maybe rejected.

Also create an account on Gitea server and configure your editor as specified in the contribution guide.

Selecting a repo

If you want to add a new package to the official repos, you should first choose the repo you want to add the package to. If you are packaging a software that is fundamental to the OS, such as a kernel, or a C library, you should add your package to the base repo. If this is not the case then you should add the package to the desktop repo.

Fork the repo

After selecting the repo, fork it on Gitea and clone it to MatterLinux system:

$ git clone <fork repo url>

Install mp-repo

MatterLinux project has few different tools used for building and creating packages, these tools are part of the mp-repo tool. To install it, follow the instructions on the README.

Create the package template

Change directory into the src folder of the repo you cloned, and use the mp-temp command (a script from mp-repo) to create an empty package script:

$ cd src 
$ mp-temp <name 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.

For this example we will be packaging the LXTerminal from LXDE:

$ cd src 
$ mp-temp lxterminal

Modify the package script

mp-temp will create a directory for the new package, which will contain a pkg.sh script. This script is called the package script. Open this script with the configured editor:

NAME="lxterminal"
DESC=""
VERSION=""
FILES=()
HASHES=()
DEPENDS=()

build() {
  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 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 release or something like that. Package an official release 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

Dependencies for the package, do not specify the make or the build dependencies that are only used for compiling the software. These dependencies should be specified in the repo.sh script which is located at the root of the repo.

With the addition of the details above, here is how our example package script looks like:

NAME="lxterminal"
DESC="VTE-based terminal emulator for LXDE"
VERSION="0.4.0"
FILES=("https://downloads.sourceforge.net/lxde/lxterminal-$VERSION.tar.xz")
HASHES=("7938dbd50e3826c11f4735a742b278d3")
DEPENDS=("vte")

build() {
  tar xf $NAME-$VERSION.tar.gz
  cd $NAME-$VERSION

  cd .. && rm -r $NAME-$VERSION
}

Build function

The build function contains the instructions for building the package itself. When building the package, mp-repo will download all the files and remove them after the build, so you do not have to deal with that.

First, we should do is to extract the downloaded file, and change directory into the newly extracted folder:

tar xf $NAME-$VERSION.tar.xz
cd $NAME-$VERSION

Then we can change directory into the repo 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:

NAME="lxterminal"
DESC="VTE-based terminal emulator for LXDE"
VERSION="0.4.0"
FILES=("https://downloads.sourceforge.net/lxde/lxterminal-$VERSION.tar.xz")
HASHES=("7938dbd50e3826c11f4735a742b278d3")
DEPENDS=("vte")

build() {
  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 (\)
• If you have really short and related commands, put them into the same line using &&
• Split unrelated instructions with a newline

Building the package

To build the newly created package, run the following in the src directory:

$ mp-repo --no-sign .. <package name>

This will install all the required dependencies, and only build the specified package.

Testing the package

When the package is built, inspect its contents using the tar tf command, and extract it to test it:

$ tar tf ../dist/<package name>_<version>.mpf
# tar xf ../dist/<package name>_<version>.mpf -C /

Staging and commit your changes

After making sure that the package is working as intended, go back to the root of the repo source directory, and use git add . to stage all the changes. Then use git commit -m <message> to commit them. For the commit message, follow the guidelines on the contribution page. For our example, the following message should be fine:

$ git commit -m "new: Add lxterminal package"

Then push your changes:

$ git push -u origin main

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.