developer/packaging/basics: 整修与补充

content/developer/packaging/basics.md

@@ -4,29 +4,27 @@ description = "Introductory Guide to AOSC OS Packaging"
 date = 2020-08-03T12:01:46.691Z
 +++
 
-**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.
+**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.
 
 # Meet the tools
 
 We will need these tools in order to build packages. 
 
   - [Ciel](https://github.com/AOSC-Dev/ciel-rs/)
-      - Manages systemd-nspawn(1) containers.
+      - Manages standardised AOSC OS build environments (systemd-nspawn(1) containers).
   - [ACBS](https://github.com/AOSC-Dev/acbs/)
       - Manages a tree (like our main tree, *<https://github.com/AOSC-Dev/aosc-os-abbs>*) of package build specs.
       - Calls Autobuild4 to (actually) read and build the package(s) as specified.
   - [Autobuild4](https://github.com/AOSC-Dev/autobuild4/)
       - Reads package specifications and run the build scripts.
-  - [pushpkg](https://github.com/AOSC-Dev/scriptlets/tree/master/pushpkg)
-      - Pushes built packages to the community repository.
 
 Don't worry about them for now, we will introduce them later.
 
 # Release model
 
 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.).
 
-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.
+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 tests. 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.
 
 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).
 
@@ -36,17 +34,15 @@ The first thing is to install Ciel on the computer. On AOSC OS, just execute the
 
 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.
 
-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).**
+Next, we will initialise and configure a Ciel workspace. **Note: Ciel needs to be run as `root`.** You may use `sudo -i` to gain elevated permission, then the root shell will be entered, and the `~` will point to `/root`. You can also add `sudo` before each command (the corresponding directory of `~` will not change).
 
-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.
+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.
 
 ``` bash
-mkdir ~/ciel
-cd ~/ciel
 ciel new
 ```
 
-It is always a good idea to keep the BuildKit environment up-to-date (and this serves as a requirement for AOSC OS packagers).
+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.
 
 ``` bash
 # 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`.
 ciel build -i main flac
 ```
 
-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`.
+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`.
 
 # Adding a new package
 
 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.
 
 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.
 
-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:
+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):
 
 ``` bash
     .
@@ -93,7 +89,7 @@ We will use `i3` as an example. This package can be found at `desktop-wm/i3`. Up
     └── spec
 ```
 
-We will go through which each file is for.
+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).
 
 ## `spec`
 
@@ -130,11 +126,12 @@ This file contains the core configuration like:
 
   - `PKGNAME` : Package name.
   - `PKGDES` : Package description.
-  - `PKGSEC` : Section (or category) where the package belongs to.
+  - `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).
   - `PKGDEP` : Package dependencies.
   - `PKGCONFL` : Package conflicts.
   - `BUILDDEP` : Build dependencies (packages which are required during build-time, but not for run-time).
   - `PKGRECOM` : Recommended dependencies, installed automatically, but could be removed by user discretion.
+  - `ABHOST`: Used to define whether the package belongs to `noarch`.
 
 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.
 
@@ -143,14 +140,16 @@ Here is a basic example taken from `desktop-wm/i3`:
 ``` bash
 PKGNAME=i3
 PKGSEC=x11
-PKGDEP="dmenu libev libxkbcommon pango perl-anyevent-i3 perl-json-xs \
+PKGDEP="libev libxkbcommon pango perl-anyevent-i3 perl-json-xs \
         startup-notification xcb-util-cursor xcb-util-keysyms \
         xcb-util-wm yajl xcb-util-xrm"
-PKGRECOM="i3lock i3status"
+PKGRECOM="i3lock i3status dex nm-applet dmenu xss-lock"
 BUILDDEP="graphviz doxygen xmlto"
 PKGDES="Improved tiling WM (window manager)"
+PKGBREAK="i3-gaps<=4.21.1"
+PKGREP="i3-gaps<=4.21.1"
 
-PKGCONFL="i3-gaps"
+ABTYPE=meson
 ```
 
 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
 
 This is a directory containing all the patches that will be applied to the source codes before the build. Simple as dropping it in. :)
 
+If necessary, track the source code repository in AOSC-Tracking and synchronize patch changes.
+
 # A complete example: GNU Hello
 
 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.
 
-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.
+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`.
 
-Since this program is obviously a utility, we create a directory called `hello` under the directory `app-utils`.
+Switch to the new branch. Since this program is obviously a utility, we create a directory called `hello` under the directory `app-utils`.
 
 ``` bash
-cd TREE/extra-utils
+cd extra-utils
 mkdir hello
 cd hello
 ```
@@ -187,53 +188,50 @@ SRCS="tbl::https://ftp.gnu.org/gnu/hello/hello-$VER.tar.gz"
 CHKSUMS="sha256::8d99142afd92576f30b0cd7cb42a8dc6809998bc5d607d88761f512e26c7db20"
 ```
 
-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.
+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.
 
-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:
+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:
 
 ``` bash
-PKGNAME=lhello
+PKGNAME=hello
 PKGSEC=utils
 PKGDES="A hello world demo program"
+
 RECONF=0
 ```
 
-And we are done\! We can now run the following command to build `light`:
+And we are done! We can now run the following command to build `hello`:
 
 ``` bash
-ciel build -i main light
+ciel build -i main hello
 ```
 
 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.
 
-## Git conventions
+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!".
 
-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).
+## Git commits
 
-For example, we are adding a new package to the tree. Then the commit message should be something like this:
-
-```
-$PKG_NAME: new, $VER
-```
+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.
 
-Take the hello for example, the commit message should be like:
+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.
 
-```
-hello: new, 2.12.1
-```
+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.
 
-If you are updating the version of an exisiting package, it should be like this:
+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.
 
 ```
-$PKG_NAME: update to $NEW_VER
+$PKG_NAME: new, $VER  # introducing new package
+# 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)
+hello: new, 2.12.1  # take hello as example
 ```
 
-Take bash for example, the commit message should be like:
 ```
-bash: update to 5.2
+$PKG_NAME: update to $NEW_VER # update existing packages
+bash: update to 5.2 # take bash as an example, to upgrade its version to 5.2
 ```
 
-And please mention all the specific changes made to the package (i.e., dependency changes, feature enablement, etc.) in the long log, for instance:
+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:
 
 ```
 bash: update to 5.2
@@ -245,11 +243,11 @@ bash: update to 5.2
 
 ## Pushing packages to the repository
 
-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.
+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.
 
-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).
+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).
 
-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.
+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**.
 
 # Epilogue