214 lines
7.5 KiB
Markdown
214 lines
7.5 KiB
Markdown
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](/wiki/repo_guide). 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](/wiki/contribute).
|
|
|
|
## 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](https://git.matterlinux.xyz/matter/mp-repo).
|
|
|
|
## 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](/wiki/contribute). 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.
|