fix: Update IDs for few posts, add the package creation wiki page
This commit is contained in:
parent
a015cca9f2
commit
4b9e0c7cf4
@ -1,5 +1,5 @@
|
||||
{
|
||||
"id": "rel24",
|
||||
"id": "first_release",
|
||||
"title": "First release!",
|
||||
"date": "19/01/24",
|
||||
"author": "ngn"
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"id": "progress-base",
|
||||
"id": "progress_base",
|
||||
"title": "Progress of the base repo",
|
||||
"date": "15/12/23",
|
||||
"author": "ngn"
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"id": "a-bootable-system",
|
||||
"id": "a_bootable_system",
|
||||
"title": "A bootable system",
|
||||
"date": "22/12/23",
|
||||
"author": "ngn"
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"id": "finally-a-website",
|
||||
"id": "finally_a_website",
|
||||
"title": "Finally a website!",
|
||||
"date": "09/12/23",
|
||||
"author": "ngn"
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"id": "stable",
|
||||
"id": "moving_towards_stable",
|
||||
"title": "Moving towards a more stable experience",
|
||||
"date": "21/02/24",
|
||||
"author": "ngn"
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"id": "xorg",
|
||||
"title": "Xorg is now avaliable",
|
||||
"id": "xorg_is_available",
|
||||
"title": "Xorg is now available",
|
||||
"date": "03/02/24",
|
||||
"author": "ngn"
|
||||
}
|
||||
|
||||
@ -10,10 +10,12 @@ edit a page or create a new page, make a [pull request](/wiki/contribute) to [co
|
||||
|
||||
## Packaging
|
||||
| Name | Description |
|
||||
| --------------------------------------- | ----------------------------------------------------- |
|
||||
| --------------------------------------- | ---------------------------------------------------------------- |
|
||||
| [Releases](/wiki/release) | Learn about MatterLinux release cycle |
|
||||
| [Repo](/wiki/repo) | Learn about MatterLinux repos and how they work |
|
||||
| [Package](/wiki/package) | Learn about MatterLinux packages |
|
||||
| [Repo Guidelines](/wiki/repo_guide) | Package guidelines for the official repos |
|
||||
| [Create a package](/wiki/create_pkg) | Learn how you can create and add a package to the official repos |
|
||||
| [Package Management](/wiki/package_man) | Learn about MatterLinux package manager |
|
||||
| [Mirrors](/wiki/mirrors) | Discover repo mirrors and learn how you can setup one |
|
||||
|
||||
|
||||
6
wiki/pkg/create.json
Normal file
6
wiki/pkg/create.json
Normal file
@ -0,0 +1,6 @@
|
||||
{
|
||||
"id": "create_pkg",
|
||||
"title": "Create a package",
|
||||
"author": "ngn",
|
||||
"date": "23/02/24"
|
||||
}
|
||||
213
wiki/pkg/create.md
Normal file
213
wiki/pkg/create.md
Normal file
@ -0,0 +1,213 @@
|
||||
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.
|
||||
@ -79,7 +79,6 @@ without the signatures.
|
||||
MatterLinux releases offer 2 different repos, `base` and `desktop`. There are also development/testing
|
||||
`base` and `desktop` repos ("next repos"). URLs for these repos and the mirrors can be found at the [mirrors page](/wiki/mirrors).
|
||||
|
||||
|
||||
This repos can provide packages for users, these packages can be managed using the
|
||||
[MatterLinux Package Manager (`mp`)](https://git.matterlinux.xyz/matter/mp). For more information see the page for [package management](/wiki/package_man).
|
||||
|
||||
|
||||
6
wiki/pkg/repo_guide.json
Normal file
6
wiki/pkg/repo_guide.json
Normal file
@ -0,0 +1,6 @@
|
||||
{
|
||||
"id": "repo_guide",
|
||||
"title": "Repo Guidelines",
|
||||
"author": "ngn",
|
||||
"date": "23/02/24"
|
||||
}
|
||||
18
wiki/pkg/repo_guide.md
Normal file
18
wiki/pkg/repo_guide.md
Normal file
@ -0,0 +1,18 @@
|
||||
Packages in the official MatterLinux repos follow these guidelines:
|
||||
|
||||
- **Packaged software should be free or/and open source**: Proprietary software won't be included
|
||||
to the repos. However, we **may** make exceptions for the drivers.
|
||||
- **Packaged software should be stable**: Software known to be unstable will not packaged,
|
||||
if the stability is related to the version of the software, we may package a different/patched
|
||||
version of the software.
|
||||
- **Packaged software should be secure**: Outdated software that has critical vulnerabilities
|
||||
will not be packaged.
|
||||
- **Packaged software should be (somewhat) popular**: No, we are not gonna package some random
|
||||
ass window manager that only has 3 users and was last updated in 1993
|
||||
|
||||
The following software packages will not be added, so do not waste your time with PRs or issues:
|
||||
- DWM or other Suckless tools that are configured using header files
|
||||
- Any Wayland window managers ("compositors"), we only have Weston which used for testing the Wayland environment
|
||||
- Other init systems (`sysvinit`, `runit` etc.)
|
||||
- Non-libre kernel
|
||||
- Snap
|
||||
Loading…
Reference in New Issue
Block a user