diff --git a/news/24.json b/news/24.json index f939e4e..aa1abff 100644 --- a/news/24.json +++ b/news/24.json @@ -1,5 +1,5 @@ { - "id": "rel24", + "id": "first_release", "title": "First release!", "date": "19/01/24", "author": "ngn" diff --git a/news/base.json b/news/base.json index c84379b..2b48d2b 100644 --- a/news/base.json +++ b/news/base.json @@ -1,5 +1,5 @@ { - "id": "progress-base", + "id": "progress_base", "title": "Progress of the base repo", "date": "15/12/23", "author": "ngn" diff --git a/news/boot.json b/news/boot.json index b80446a..3cbe61a 100644 --- a/news/boot.json +++ b/news/boot.json @@ -1,5 +1,5 @@ { - "id": "a-bootable-system", + "id": "a_bootable_system", "title": "A bootable system", "date": "22/12/23", "author": "ngn" diff --git a/news/hello.json b/news/hello.json index 54e9e8d..20a04de 100644 --- a/news/hello.json +++ b/news/hello.json @@ -1,5 +1,5 @@ { - "id": "finally-a-website", + "id": "finally_a_website", "title": "Finally a website!", "date": "09/12/23", "author": "ngn" diff --git a/news/stable.json b/news/stable.json index 0fa8f52..b59ea4f 100644 --- a/news/stable.json +++ b/news/stable.json @@ -1,5 +1,5 @@ { - "id": "stable", + "id": "moving_towards_stable", "title": "Moving towards a more stable experience", "date": "21/02/24", "author": "ngn" diff --git a/news/xorg.json b/news/xorg.json index 532250a..a3480aa 100644 --- a/news/xorg.json +++ b/news/xorg.json @@ -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" } diff --git a/wiki/main.md b/wiki/main.md index 5c1fa42..57615c1 100644 --- a/wiki/main.md +++ b/wiki/main.md @@ -9,13 +9,15 @@ edit a page or create a new page, make a [pull request](/wiki/contribute) to [co | [Post-Installation](/wiki/post_install) | Make your system (somewhat) usable | ## 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 | -| [Package Management](/wiki/package_man) | Learn about MatterLinux package manager | -| [Mirrors](/wiki/mirrors) | Discover repo mirrors and learn how you can setup one | +| 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 | ## Other | Name | Description | diff --git a/wiki/pkg/create.json b/wiki/pkg/create.json new file mode 100644 index 0000000..e8524fc --- /dev/null +++ b/wiki/pkg/create.json @@ -0,0 +1,6 @@ +{ + "id": "create_pkg", + "title": "Create a package", + "author": "ngn", + "date": "23/02/24" +} diff --git a/wiki/pkg/create.md b/wiki/pkg/create.md new file mode 100644 index 0000000..83f7c7f --- /dev/null +++ b/wiki/pkg/create.md @@ -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 +``` + +## 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 +``` + +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 .. +``` +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/_.mpf +# tar xf ../dist/_.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 ` 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. diff --git a/wiki/pkg/repo.md b/wiki/pkg/repo.md index 65add51..c60d9a6 100644 --- a/wiki/pkg/repo.md +++ b/wiki/pkg/repo.md @@ -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). diff --git a/wiki/pkg/repo_guide.json b/wiki/pkg/repo_guide.json new file mode 100644 index 0000000..0e2febe --- /dev/null +++ b/wiki/pkg/repo_guide.json @@ -0,0 +1,6 @@ +{ + "id": "repo_guide", + "title": "Repo Guidelines", + "author": "ngn", + "date": "23/02/24" +} diff --git a/wiki/pkg/repo_guide.md b/wiki/pkg/repo_guide.md new file mode 100644 index 0000000..cffc1fe --- /dev/null +++ b/wiki/pkg/repo_guide.md @@ -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