Skip to content

Commit 1e0cb45

Browse files
ruaharicochenx97
authored andcommitted
draft
1 parent 5d8186f commit 1e0cb45

File tree

2 files changed

+85
-91
lines changed

2 files changed

+85
-91
lines changed

content/developer/packaging/basics.md

Lines changed: 42 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,27 @@ description = "Introductory Guide to AOSC OS Packaging"
44
date = 2020-08-03T12:01:46.691Z
55
+++
66

7-
**NOTICE**: This guide assumes you have moderate knowledge about Linux and its CLI (command line interface). Also, you need to have access to a Linux computer with `root` access.
7+
**NOTICE**: This guide assumes you have moderate knowledge about Linux, its CLI (command line interface) and Git. Also, you need to have access to a Linux computer with `root` access.
88

99
# Meet the tools
1010

1111
We will need these tools in order to build packages.
1212

1313
- [Ciel](https://github.com/AOSC-Dev/ciel-rs/)
14-
- Manages systemd-nspawn(1) containers.
14+
- Manages standardised AOSC OS build environments (systemd-nspawn(1) containers).
1515
- [ACBS](https://github.com/AOSC-Dev/acbs/)
1616
- Manages a tree (like our main tree, *<https://github.com/AOSC-Dev/aosc-os-abbs>*) of package build specs.
1717
- Calls Autobuild4 to (actually) read and build the package(s) as specified.
1818
- [Autobuild4](https://github.com/AOSC-Dev/autobuild4/)
1919
- Reads package specifications and run the build scripts.
20-
- [pushpkg](https://github.com/AOSC-Dev/scriptlets/tree/master/pushpkg)
21-
- Pushes built packages to the community repository.
2220

2321
Don't worry about them for now, we will introduce them later.
2422

2523
# Release model
2624

2725
AOSC OS is maintained with a rolling release model. This means that there's no version number attached to a full AOSC OS release (similar to other rolling release Linux distros, like openSUSE Tumbleweed and Arch Linux). However, within the [aosc-os-abbs](https://github.com/AOSC-Dev/aosc-os-abbs) tree, there is a set of packages that constructs the [AOSC OS Core](https://github.com/AOSC-Dev/aosc-os-abbs/blob/stable/README.CORE.md), which consists of core runtime (the GNU C Library, etc.) and toolchains (GCC, etc.). This set of packages are updated in a versioned fashion (Core 7.0.1, 7.0.2, 7.1.1, etc.).
2826

29-
Thanks to the rolling model, there's only one update channel for the users - `stable`. When updating or introducing new packages, developers work on a separate branch in the tree (the aforementioned aosc-os-abbs), create a Pull Request about the modification, then upload the package built to a separate repository (parallel to the `stable` repository). Thus, the users may test the updated packages by using the [AOSC OS APT Topic Manager](https://github.com/AOSC-Dev/atm) (or ATM). Then, if the package is proven to be working, the pull request is merged and then the package is rebuilt against a clean `stable` environment, and pushed to the main repository.
27+
Thanks to the rolling model, there's only one update channel for the users - `stable`. When updating or introducing new packages, developers work on a separate branch in the tree (the aforementioned aosc-os-abbs), create a Pull Request about the modification, then upload the package built to a separate repository and carry out testing. Thus, the users may test the updated packages by using `oma topics`. Then, if the package is proven to be working, the pull request is merged and then the package is rebuilt against a clean `stable` environment with automated tools, and pushed to the main repository.
3028

3129
This process is called topic-based iteration model. This model is employed in order to reduce stress for the developers and ensure the quality of the packages. If you want to learn more about this model, you may want to check [Topic-Based Maintenance Guidelines](@/developer/packaging/topic-based-maintenance-guideline.md).
3230

@@ -36,17 +34,15 @@ The first thing is to install Ciel on the computer. On AOSC OS, just execute the
3634

3735
Since Ciel manages standardised AOSC OS build environment (or the BuildKit), the build process does not have to happen on an AOSC OS machine. If you are using Arch Linux, you can install Ciel from AUR.
3836

39-
Next, we will initialise and configure a Ciel workspace. `~/ciel` is used as a sample path for demonstration. **Note: Ciel needs to be run as `root` (you may use `sudo -i` to gain elevated permission).**
37+
Next, we will initialise and configure a Ciel workspace. **Note: Ciel needs to be run as `root`.** You may use `sudo -i` to gain a root shell and `~` will now point to `/root`. You can also add `sudo` before each command (the corresponding directory of `~` will not change).
4038

41-
Execute the following commands and follow the on-screen instructions, **making sure to enter appropriate maintainer information (the default will not work as it will trip a QA error while you attempt to package)**, when asked if you would like to create an instance, please create one - we will call it `main` here.
39+
First, create a new folder in the appropriate place (it is recommended to leave 10 GB or more free space in the partition where the folder is located) and switch to this folder, and then execute the following command to start configuring the Ciel workspace. When the wizard asks about the Target Architecture, it is generally to select the processor architecture of the current device. When asking for Maintainer Information, please refer to the example to fill in your own information. You can use the default values ​​for the remaining options. When asked if you would like to create an instance, please create one - we will call it `main` here.
4240

4341
``` bash
44-
mkdir ~/ciel
45-
cd ~/ciel
4642
ciel new
4743
```
4844

49-
It is always a good idea to keep the BuildKit environment up-to-date (and this serves as a requirement for AOSC OS packagers).
45+
It is always a good idea to keep the BuildKit environment up-to-date (and this saves time for AOSC OS packagers). BuildKit refers to the standardised AOSC OS build environments, which is generally run in Ciel's containers.
5046

5147
``` bash
5248
# If this step takes too long, you can edit sources.list via "ciel config" to choose a faster mirror.
@@ -64,15 +60,15 @@ Simply execute the following command to build `flac`.
6460
ciel build -i main flac
6561
```
6662

67-
If the build completes without error, and a `Build Summary` is present, congratulations on your first successful build\! You should be able to find the generated deb inside `OUTPUT-stable/debs`.
63+
If the build completes without error, and a `BUILD SUCCESSFUL` is present, congratulations on your first successful build\! You should be able to find the generated deb inside `OUTPUT-stable/debs`.
6864

6965
# Adding a new package
7066

7167
But surely you won't be satisfied by simply building existing packages, right? Here we will discover how to construct a new package from scratch.
7268

7369
Dive into the `TREE` folder, you will find a lot of categories of folders, including some beginning with `core-`, `app-`, `desktop-`, and so on. For more information about these folders, please visit [aosc-os-abbs](https://github.com/AOSC-Dev/aosc-os-abbs). These folders are for organizing purposes, and inside them you will find the various packages (and their build specifications) organised in each of their own directory.
7470

75-
We will use `i3` as an example. This package can be found at `desktop-wm/i3`. Upon entering the directory, you should see a file structure as follows:
71+
We will use `i3` as an example. This package can be found at `desktop-wm/i3`. Upon entering the directory, you should see a file structure as follows (This package has no patches, so there is no `patches` folder under the `autobuild` folder):
7672

7773
``` bash
7874
.
@@ -93,7 +89,7 @@ We will use `i3` as an example. This package can be found at `desktop-wm/i3`. Up
9389
└── spec
9490
```
9591

96-
We will go through which each file is for.
92+
We will go through which each file is for. Unexpected details can be found in other articles such as [AOSC OS Package Styling Manual](@/developer/packaging/package-styling-manual.md).
9793

9894
## `spec`
9995

@@ -130,11 +126,12 @@ This file contains the core configuration like:
130126

131127
- `PKGNAME` : Package name.
132128
- `PKGDES` : Package description.
133-
- `PKGSEC` : Section (or category) where the package belongs to.
129+
- `PKGSEC` : Section (or category) where the package belongs to. It should be noted that the section (category) name is not necessarily the same as the subdirectory name of the package in the package tree. For example, `i3` is in the `desktop-wm` subdirectory of the package tree, but its section is `x11`. The section (category) of the packages accepted by AOSC OS can be found in [Autobuild4 related files](https://github.com/AOSC-Dev/autobuild4/blob/master/sets/section).
134130
- `PKGDEP` : Package dependencies.
135131
- `PKGCONFL` : Package conflicts.
136132
- `BUILDDEP` : Build dependencies (packages which are required during build-time, but not for run-time).
137133
- `PKGRECOM` : Recommended dependencies, installed automatically, but could be removed by user discretion.
134+
- `ABHOST`: Used to define whether the package belongs to `noarch`.
138135

139136
These are only the most common configuration entries. There are much more configurations, but if the software is fairly standard, these configuration should be enough. Other information like which compiler flags to use, which build system to use, can be filled automatically by Autobuild4.
140137

@@ -143,14 +140,16 @@ Here is a basic example taken from `desktop-wm/i3`:
143140
``` bash
144141
PKGNAME=i3
145142
PKGSEC=x11
146-
PKGDEP="dmenu libev libxkbcommon pango perl-anyevent-i3 perl-json-xs \
143+
PKGDEP="libev libxkbcommon pango perl-anyevent-i3 perl-json-xs \
147144
startup-notification xcb-util-cursor xcb-util-keysyms \
148145
xcb-util-wm yajl xcb-util-xrm"
149-
PKGRECOM="i3lock i3status"
146+
PKGRECOM="i3lock i3status dex nm-applet dmenu xss-lock"
150147
BUILDDEP="graphviz doxygen xmlto"
151148
PKGDES="Improved tiling WM (window manager)"
149+
PKGBREAK="i3-gaps<=4.21.1"
150+
PKGREP="i3-gaps<=4.21.1"
152151

153-
PKGCONFL="i3-gaps"
152+
ABTYPE=meson
154153
```
155154

156155
Notice here that you can actually write Bash logic inside `defines`. This is useful when adding platform-specific flags or dependencies, but this is **NO LONGER** recommended, and will be prohibited in the future. For adding platform specific info, use `$VAR__$ARCH` (for example, `AUTOTOOLS_AFTER__AMD64`).
@@ -165,16 +164,18 @@ This file is the script that will be executed before the build process begins. U
165164

166165
This is a directory containing all the patches that will be applied to the source codes before the build. Simple as dropping it in. :)
167166

167+
If necessary, track the source code repository in AOSC-Tracking and synchronize patch changes.
168+
168169
# A complete example: GNU Hello
169170

170171
That's all the basic knowledge you need to build a simple package\! Now, we will try to build a really simple program: [hello](https://www.gnu.org/software/hello/). This program is used to print a greeting on the screen. It is such a simple program that doesn`t have any dependencies.
171172

172-
Return to the `TREE` directory. First, make sure that you are on the right branch. As mentioned above, you should use a separate Git branch for a topic. Here, since we are introducing a new package, according to [AOSC OS Topic-Based Maintenance Guidelines](@/developer/packaging/topic-based-maintenance-guideline.md), the new branch name should be `$PKGNAME-$PKGVER-new`. Thus, we create a branch called `hello-2.12.1-new` and switch to it.
173+
Return to the `TREE` directory. First, make sure that you are on the `stable` branch and up to date with upstream by running `git pull`. Then, create a separate Git branch for the new package, and the branch name should be written following [AOSC OS Topic-Based Maintenance Guidelines](@/developer/packaging/topic-based-maintenance-guideline.md). Since we are introducing a new package, the new branch name should be `$PKGNAME-$PKGVER-new`, i.e. `hello-2.12.1-new`.
173174

174-
Since this program is obviously a utility, we create a directory called `hello` under the directory `app-utils`.
175+
Switch to the new branch. Since this program is obviously a utility, we create a directory called `hello` under the directory `app-utils`.
175176

176177
``` bash
177-
cd TREE/extra-utils
178+
cd extra-utils
178179
mkdir hello
179180
cd hello
180181
```
@@ -187,53 +188,50 @@ SRCS="tbl::https://ftp.gnu.org/gnu/hello/hello-$VER.tar.gz"
187188
CHKSUMS="sha256::8d99142afd92576f30b0cd7cb42a8dc6809998bc5d607d88761f512e26c7db20"
188189
```
189190

190-
Notice here that we replaced the version number inside the tarball URL with an environment variable `$VER`. This is considered as a good practice (since it reduces the modification required when updating the package), and should be used when possible.
191+
Notice here that we replaced the version number inside the tarball URL with an environment variable `$VER`. Source archives (tarballs) must be versioned in order to ensure consistency.
191192

192-
Then, we create the `autobuild` folder, and create the `defines` file. Since this programe has no dependency, `PKGDEP` is not needed. In this case, to avoid version conflicts during compiling, `RECONF=0` is needed. The complete `defines` file looks as follows:
193+
Then, we create the `autobuild` folder, and create the `defines` file. Since this programe has no dependency, `PKGDEP` is not needed. After writing the package name, dependency, description, etc., you should leave a blank line and then write the compilation function and options. Since Autobuild4 will regenerate the configure script, it will cause the problem of version conflicts when compiling `hello`, so you need to use `RECONF=0` to turn off the regenerating the configure script (but this does not mean that you need to turn off this function when compiling other packages). The complete `defines` file looks as follows:
193194

194195
``` bash
195-
PKGNAME=lhello
196+
PKGNAME=hello
196197
PKGSEC=utils
197198
PKGDES="A hello world demo program"
199+
198200
RECONF=0
199201
```
200202

201-
And we are done\! We can now run the following command to build `light`:
203+
And we are done! We can now run the following command to build `hello`:
202204

203205
``` bash
204-
ciel build -i main light
206+
ciel build -i main hello
205207
```
206208

207209
Although we didn't write anything about how to build this program, Autobuild4 automatically figured out that this should be built with `autotools` (i.e., the classic `./configure && make && make install` logic), and should build the program successfully.
208210

209-
## Git conventions
211+
Then, in the Ciel workspace directory, you can see the built `.deb` package in the relevant OUTPUT folder. At this point, you can test whether this package works properly after installing by deb-installer / oma / dpkg. For example, to test whether `hello` works, we should run `hello` in the terminal, and when `LANG` is set to `en_US.UTF-8`, it will output "Hello, World!".
210212

211-
If the build completed successfully, now it's time to commit your build scripts! AOSC OS has strict conventions about Git commit messages. We will only mention the most used ones here. For the full list of package styling and development guidelines, please refer to the [package styling manual](@/developer/packaging/package-styling-manual.md).
213+
## Git commits
212214

213-
For example, we are adding a new package to the tree. Then the commit message should be something like this:
214-
215-
```
216-
$PKG_NAME: new, $VER
217-
```
215+
After following the steps above, you can start trying to package packages that you really want to add or update for AOSC OS. If you want to introduce a new package for AOSC OS, there are more elements to consider than when packaging GNU Hello, such as sorting out runtime dependencies and build dependencies; if you encounter problems during this period, you can ask in our community chat group or AOSC BBS.
218216

219-
Take the hello for example, the commit message should be like:
217+
When a user packages, it does not mean that they must upload it to the AOSC OS main tree. However, we recommend that as long as the software allows AOSC OS maintainers to package and redistribute, and the software package does not exist or is not up-to-date in the main tree, then the package information is welcome to submit the software package information to the main tree and build the AOSC OS software repository together! However, in contrast, individual software does not allow AOSC OS maintainers to package and redistribute (such as individual proprietary software and "free commercial" fonts that do not allow redistribution), or are not suitable for continued provision to users (such as there are subsequent projects, the original projects are no longer updated, and there is an inheritance relationship before and after), or the official is not friendly to redistribution (such as a proprietary software deliberately restricts automatic pulling of software packages, requiring dynamic keys and timestamps to download), and at this time if you want to manage them in the form of a software package (this is a good habit), you can also package them for yourself only.
220218

221-
```
222-
hello: new, 2.12.1
223-
```
219+
If the build completed and tested successfully, after confirming that the software can be packaged and redistributed, now it's time to commit your build scripts! Before commiting, you can use [pakfixer](https://github.com/AOSC-Dev/pfu) to check the build script you wrote and make appropriate modifications.
224220

225-
If you are updating the version of an exisiting package, it should be like this:
221+
In order to make the introduction/update effectively traceable, the AOSC OS main tree puts forward strict requirements on Git commit information. See the [Package Style Manual](@/developer/packaging/package-styling-manual.md) for details. The following excerpts some common formats.
226222

227223
```
228-
$PKG_NAME: update to $NEW_VER
224+
$PKG_NAME: new, $VER # introducing new package
225+
# When introducing new package, in principle, multiple commits should not appear (if any, you need to use `git rebase -i` to enter the visual base to merge multiple commits into one)
226+
hello: new, 2.12.1 # take hello as example
229227
```
230228

231-
Take bash for example, the commit message should be like:
232229
```
233-
bash: update to 5.2
230+
$PKG_NAME: update to $NEW_VER # update existing packages
231+
bash: update to 5.2 # take bash as an example, to upgrade its version to 5.2
234232
```
235233

236-
And please mention all the specific changes made to the package (i.e., dependency changes, feature enablement, etc.) in the long log, for instance:
234+
And please mention all the specific changes made to the package (i.e., dependency changes, feature enablement, patch add or delele, etc.) in the long log, for instance:
237235

238236
```
239237
bash: update to 5.2
@@ -245,11 +243,11 @@ bash: update to 5.2
245243

246244
## Pushing packages to the repository
247245

248-
After a successful build, you can push your local branch (`hello-2.12.1-new` in this example) to your fork or directly to the main repository. Then, you can create a Pull Request and fill in the information. Finally, you should push your finished product to our main repository to be tested by other users.
246+
After the package is built and tested and the commit is successfully performed with Git, you can fork the main tree to your own GitHub, push the local Git branch (such as `hello-2.12.1-new`) to your fork, and then create a Pull Request in the main tree and fill in the information.
249247

250-
Nowadays, the work of uploading and pushing is done by automated tools. For more information, please visit [Making Use of the Automated Maintenance Infrastructure](@/developer/packaging/buildit-bot.md).
248+
Next, please wait for Pull Request review. Community contributors will review and submit modifications (if any), and after the modification and test pass, your Pull Request will be merged. Then, you can use the automated tools to build a package and push new packages or package updates to all users. Nowadays, the work of uploading and pushing is done by automated tools. For more information, please visit [Making Use of the Automated Maintenance Infrastructure](@/developer/packaging/buildit-bot.md).
251249

252-
Then you can patiently wait until someone reviews your Pull Request and tests your package. If everything looks good, your pull request will be merged and you should rebuild it and push the new package to the `stable` repository.
250+
After you submit the first contribution to AOSC OS projects such as the AOSC OS main tree, you can become a contributor. After becoming a contributor, you can push the local Git branch directly to the main tree, then use the automated tools to create Pull Request, build packages, install, test, generate audit reports (`/dickens`), wait for other contributors to review and approve the Pull Request, merge into the stable branch and **build the package again for stable**.
253251

254252
# Epilogue
255253

0 commit comments

Comments
 (0)