update: small wiki fixes and minor tweaks
This commit is contained in:
6
wiki/package/create.json
Normal file
6
wiki/package/create.json
Normal file
@ -0,0 +1,6 @@
|
||||
{
|
||||
"id": "create",
|
||||
"title": "Create a package",
|
||||
"author": "ngn",
|
||||
"date": "04/08/24"
|
||||
}
|
274
wiki/package/create.md
Normal file
274
wiki/package/create.md
Normal 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
6
wiki/package/packages.json
Normal file
@ -0,0 +1,6 @@
|
||||
{
|
||||
"id": "packages",
|
||||
"title": "Packages",
|
||||
"author": "ngn",
|
||||
"date": "04/08/24"
|
||||
}
|
145
wiki/package/packages.md
Normal file
145
wiki/package/packages.md
Normal 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.
|
Reference in New Issue
Block a user