content/wiki/pkg.md
2024-01-07 21:23:29 +03:00

5.9 KiB

A MatterLinux package is a compiled files of a software, tool or a libary.

Format

MatterLinux packages uses the MatterLinux Packaging Format, 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 filesystem.

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) 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), 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 the tar tool.

To learn more about this process see the page for mp.

It's also possible to install packages manualy. 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.

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 libary it provides. Preferably the name should not contain _ to avoid confusion with naming.
  • DESC: A short description about the software, tool or the libary that package provides. Explain what it does, what it contains etc.
  • VERSION: Version of the software, tool or libary 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, 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 and BLFS 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 and desktop repo sources for more example pkg.sh scripts.