You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/developer/packaging/basics.md
+42-44Lines changed: 42 additions & 44 deletions
Original file line number
Diff line number
Diff line change
@@ -4,29 +4,27 @@ description = "Introductory Guide to AOSC OS Packaging"
4
4
date = 2020-08-03T12:01:46.691Z
5
5
+++
6
6
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.
8
8
9
9
# Meet the tools
10
10
11
11
We will need these tools in order to build packages.
12
12
13
13
-[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).
15
15
-[ACBS](https://github.com/AOSC-Dev/acbs/)
16
16
- Manages a tree (like our main tree, *<https://github.com/AOSC-Dev/aosc-os-abbs>*) of package build specs.
17
17
- Calls Autobuild4 to (actually) read and build the package(s) as specified.
- Pushes built packages to the community repository.
22
20
23
21
Don't worry about them for now, we will introduce them later.
24
22
25
23
# Release model
26
24
27
25
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.).
28
26
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.
30
28
31
29
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).
32
30
@@ -36,17 +34,15 @@ The first thing is to install Ciel on the computer. On AOSC OS, just execute the
36
34
37
35
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.
38
36
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).
40
38
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.
42
40
43
41
```bash
44
-
mkdir ~/ciel
45
-
cd~/ciel
46
42
ciel new
47
43
```
48
44
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.
50
46
51
47
```bash
52
48
# 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`.
64
60
ciel build -i main flac
65
61
```
66
62
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`.
68
64
69
65
# Adding a new package
70
66
71
67
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.
72
68
73
69
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.
74
70
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):
76
72
77
73
```bash
78
74
.
@@ -93,7 +89,7 @@ We will use `i3` as an example. This package can be found at `desktop-wm/i3`. Up
93
89
└── spec
94
90
```
95
91
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).
97
93
98
94
## `spec`
99
95
@@ -130,11 +126,12 @@ This file contains the core configuration like:
130
126
131
127
-`PKGNAME` : Package name.
132
128
-`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).
134
130
-`PKGDEP` : Package dependencies.
135
131
-`PKGCONFL` : Package conflicts.
136
132
-`BUILDDEP` : Build dependencies (packages which are required during build-time, but not for run-time).
137
133
-`PKGRECOM` : Recommended dependencies, installed automatically, but could be removed by user discretion.
134
+
-`ABHOST`: Used to define whether the package belongs to `noarch`.
138
135
139
136
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.
140
137
@@ -143,14 +140,16 @@ Here is a basic example taken from `desktop-wm/i3`:
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
165
164
166
165
This is a directory containing all the patches that will be applied to the source codes before the build. Simple as dropping it in. :)
167
166
167
+
If necessary, track the source code repository in AOSC-Tracking and synchronize patch changes.
168
+
168
169
# A complete example: GNU Hello
169
170
170
171
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.
171
172
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`.
173
174
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`.
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.
191
192
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:
193
194
194
195
```bash
195
-
PKGNAME=lhello
196
+
PKGNAME=hello
196
197
PKGSEC=utils
197
198
PKGDES="A hello world demo program"
199
+
198
200
RECONF=0
199
201
```
200
202
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`:
202
204
203
205
```bash
204
-
ciel build -i main light
206
+
ciel build -i main hello
205
207
```
206
208
207
209
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.
208
210
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!".
210
212
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
212
214
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.
218
216
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.
220
218
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.
224
220
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.
226
222
227
223
```
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
229
227
```
230
228
231
-
Take bash for example, the commit message should be like:
232
229
```
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
234
232
```
235
233
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:
237
235
238
236
```
239
237
bash: update to 5.2
@@ -245,11 +243,11 @@ bash: update to 5.2
245
243
246
244
## Pushing packages to the repository
247
245
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.
249
247
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).
251
249
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**.
0 commit comments