content/wiki/pkg/create.md

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 maybe
rejected.

Also create an account on Gitea server and configure your editor
as specified in the [contribution guide](/wiki/contribute).

## 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. 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` pool.

If the software is mainly targeted for server use, you should add the package
to the `server` pool.

If none of these is the case then you should add the package to the `desktop`
pool.

## Fork the pool 
After selecting the pool, fork it on Gitea and clone it to MatterLinux 
system:
```
$ git clone <git repo url>
```

## Install requirements 
To build and create packages, you should install the `build-essential` package from the
`base` pool. This package will provide you with all the scripts and the tools required.

## 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-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:
```
# 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=()

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

## Building the package 
To build the newly created package, run the following in the `src` directory:
```
$ mp-build --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, check out the newly created root directory inside the package directory
to make sure that everything is placed where it should be:
```
$ tree <pacakge_name>/root
```

## Staging 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>` 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.