diff --git a/content/developer/packaging/basics.md b/content/developer/packaging/basics.md index 9bfda52..e024db2 100644 --- a/content/developer/packaging/basics.md +++ b/content/developer/packaging/basics.md @@ -8,33 +8,37 @@ date = 2020-08-03T12:01:46.691Z # Meet the tools -We will need these tools in order to build packages. Don't worry about them for now, we will investigate them later. +We will need these tools in order to build packages. - [Ciel](https://github.com/AOSC-Dev/ciel-rs/) - Manages systemd-nspawn(1) containers. - [ACBS](https://github.com/AOSC-Dev/acbs/) - Manages a tree (like our main tree, **) of package build specs. - - Calls Autobuild3 to (actually) read and build the package(s) as specified. - - [Autobuild3](https://github.com/AOSC-Dev/autobuild3/) + - 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 (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. 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). # Setting up the environment -The first thing is to install `ciel` on the computer. On AOSC OS, just install ciel from the official repository. +The first thing is to install Ciel on the computer. On AOSC OS, just execute the command `oma install ciel`. + +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. -Since Ciel manages standardised AOSC OS build environment (or the [BuildKit](https://aosc.io/downloads/#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. Notice that Ciel will need to be run as `root` and Ciel cannot be used in a Docker instance. -Next, we will initialise and configure a Ciel workspace. `~/ciel` is used as a sample path for demonstration. Notice that Ciel will need to be run as `root` and Ciel cannot be used in a Docker instance. Execute the following commands and follow the on-screen instructions, when asked if you would like to create an instance, please create one - we will call it `main` here. +Execute the following commands and follow the on-screen instructions, when asked if you would like to create an instance, please create one - we will call it `main` here. ``` bash mkdir ~/ciel @@ -49,9 +53,9 @@ It is always a good idea to keep the BuildKit environment up-to-date (and this s ciel update-os ``` -# Building our very first package\! +# Building our very first package -Now that we have a build environment set-up, we can try to build a package that is already in the tree. Let's start with a relatively trivial one, `extra-multimedia/flac`. +Now that we have a build environment set-up, we can try to build a package that is already in the tree. Let's start with a relatively trivial one, `app-multimedia/flac`. Simply execute the following command to build `flac`. @@ -66,9 +70,9 @@ If the build completes without error, and a `Build Summary` is present, congratu 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 `base-` and `core-` prefixes, as well as some with `extra-`. 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. +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 `TREE/extra-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: ``` bash . @@ -96,12 +100,12 @@ We will go through which each file is for. This file is responsible for telling ACBS where to download the source file, and the package's version and revision. A basic `spec` file should look like this: ``` bash -VER=4.17.1 # Version of the software. +VER=4.24 # Version of the software. # REL=0 The package revision. If not specified, the variable is given a value of 0. # If using a source tarball. -SRCS="tbl::https://i3wm.org/downloads/i3-$VER.tar.bz2" # Download address for the source code. -CHKSUMS="sha256::1e8fe133a195c29a8e2aa3b1c56e5bc77e7f5534f2dd92e09faabe2ca2d85f45" # Checksum of the source tarball. +SRCS="tbl::https://i3wm.org/downloads/i3-$VER.tar.xz" # Download address for the source code. +CHKSUMS="sha256::5baefd0e5e78f1bafb7ac85deea42bcd3cbfe65f1279aa96f7e49661637ac981" # Checksum of the source tarball. # If using Git. SRCS="git::commit=$COMMIT_ID::https://some.git.hosting/somewhere" @@ -118,7 +122,7 @@ One thing worth noting is the revision number. You can ignore this line if you a ## `autobuild/` -This is the directory where all the Autobuild3 scripts and definitions live. Autobuild3 is a sophisticated build system that can automatically determine a series of build-time processes, like which build system to use, which build parameter to use, and so on. +This is the directory where all the Autobuild4 scripts and definitions live. Autobuild4 is a sophisticated build system that can automatically determine a series of build-time processes, like which build system to use, which build parameter to use, and so on. ## `autobuild/defines` @@ -132,9 +136,9 @@ This file contains the core configuration like: - `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. -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 Autobuild3. +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. -Here is a basic example taken from `extra-wm/i3`: +Here is a basic example taken from `desktop-wm/i3`: ``` bash PKGNAME=i3 @@ -159,43 +163,39 @@ This file is the script that will be executed before the build process begins. U ## `autobuild/patches/` -This is a directory containing all the patches that will be applied to the source codes before the build. - -Simple as dropping it in. :) +This is a directory containing all the patches that will be applied to the source codes before the build. Simple as dropping it in. :) -# A complete example: `light` +# 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: [light](https://github.com/haikarainen/light). +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. -This program is used to provide a easy command to control the backlight of laptop. Since it only uses file API to interact with the backlight subsystem, this program is very simple and does not require and dependency other than `glibc`. +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 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 `light-1.2.1-new` and switch to it. - -Since this program is obviously a utility, we create a directory called `light` under the directory `extra-utils`. +Since this program is obviously a utility, we create a directory called `hello` under the directory `app-utils`. ``` bash cd TREE/extra-utils -mkdir light -cd light +mkdir hello +cd hello ``` -Then, we create the `spec` file. Look up the project website and find out the download URL for the latest version. After manually checking the `sha256` checksum of the latest tarball, we can fill in the file. +Then, we create the `spec` file. Look up the project website and find out the download URL for the latest version. Then, check the HASH checksum (for example, MD5 and SHA-256) of the latest tarball. In these case, we can check its SHA-256 checksum by command `sha256sum hello-2.12.1.tar.gz`. ``` bash -VER=1.2.1 -SRCS="tbl::https://github.com/haikarainen/light/archive/v$VER.tar.gz" -CHKSUMS="sha256::53d1e74f38813de2068e26a28dc7054aab66d1adfedb8d9200f73a57c73e7293" +VER=2.12.1 +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. -Then, we create the `autobuild` folder, and create the `defines` file. 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. In this case, to avoid version conflicts during compiling, `RECONF=0` is needed. The complete `defines` file looks as follows: ``` bash -PKGNAME=light +PKGNAME=lhello PKGSEC=utils -PKGDEP="glibc" -PKGDES="Program to easily change brightness on backlight-controllers." +PKGDES="A hello world demo program" +RECONF=0 ``` And we are done\! We can now run the following command to build `light`: @@ -204,7 +204,7 @@ And we are done\! We can now run the following command to build `light`: ciel build -i main light ``` -Although we didn't write anything about how to build this program, Autobuild3 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. +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 @@ -212,27 +212,42 @@ If the build completed successfully, now it's time to commit your build scripts! For example, we are adding a new package to the tree. Then the commit message should be something like this: - light: new, 1.2.1 - $PKG_NAME: new, $VER +``` +$PKG_NAME: new, $VER +``` + +Take the hello for example, the commit message should be like: + +``` +hello: new, 2.12.1 +``` If you are updating the version of an exisiting package, it should be like this: - bash: update to 5.2 - $PKG_NAME: update to $NEW_VER +``` +$PKG_NAME: update to $NEW_VER +``` + +Take bash for example, the commit message should be like: +``` +bash: update 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: - bash: update to 5.2 +``` +bash: update to 5.2 - - Make a symbolic link from /bin/bash to /bin/sh for program compatibility. - - Install HTML documentations. - - Build with -O3 optimisation. +- Make a symbolic link from /bin/bash to /bin/sh for program compatibility. +- Install HTML documentations. +- Build with -O3 optimisation. +``` ## Pushing packages to the repository -After a successful build, you can push your local branch (`light-1.2.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 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. -The second task must be done using [pushpkg](https://github.com/AOSC-Dev/scriptlets/tree/master/pushpkg). If you are using AOCS OS, install the `pushpkg` package (or otherwise grab the script, add the script to PATH, make sure it is executable). Then, invoke `pushpkg` inside the `OUTPUT` directory. You will need to provide your LDAP credentials and the destination repository (for this example, `light-1.2.1-new`). +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. diff --git a/content/developer/packaging/basics.zh.md b/content/developer/packaging/basics.zh.md index 4facc65..362ea9a 100644 --- a/content/developer/packaging/basics.zh.md +++ b/content/developer/packaging/basics.zh.md @@ -64,7 +64,7 @@ ciel update-os ciel build -i main flac ``` -如果构建过程成功完成并显示 `Build Summary` 提示,恭喜,您的处女包打出来啦!您刚刚打出来的包已由 Autobuild3 存放于 `OUTPUT-stable/debs`。 +如果构建过程成功完成并显示 `Build Summary` 提示,恭喜,您的处女包打出来啦!您刚刚打出来的包已由 Autobuild4 存放于 `OUTPUT-stable/debs`。 # 引入新包 @@ -122,7 +122,7 @@ CHKSUMS="SKIP sha256::some_checksum sha256::sume_checksum" ## `autobuild/` -该文件夹存放 Autobuild3 定义及脚本文件。Autobuild3 可以通过解析这些文件(使用什么构建系统?使用什么构建参数?等)来组织构建流程。 +该文件夹存放 Autobuild4 定义及脚本文件。Autobuild4 可以通过解析这些文件(使用什么构建系统?使用什么构建参数?等)来组织构建流程。 ## `autobuild/defines` @@ -136,7 +136,7 @@ CHKSUMS="SKIP sha256::some_checksum sha256::sume_checksum" - `BUILDDEP` : 构建依赖(仅在构建时需要的软件包)。 - `PKGRECOM` : 推荐依赖,在安装软件包时会自动安装,但可根据用户需要卸载。 -上面列出的只是最常见的几个配置项。Autobuild3 还有许多其他配置参数,但如果软件包依赖信息和构建流程相对标准,一般不会需要使用其他参数。Autobuild3 会自动填入编译器参数、构建系统等其他构建参数。 +上面列出的只是最常见的几个配置项。Autobuild4 还有许多其他配置参数,但如果软件包依赖信息和构建流程相对标准,一般不会需要使用其他参数。Autobuild3 会自动填入编译器参数、构建系统等其他构建参数。 以 `desktop-wm/i3` 为例: @@ -169,7 +169,7 @@ PKGCONFL="i3-gaps" 接下来,我们来实战软件包配置编写。该章节介绍 [hello](https://www.gnu.org/software/hello/) ,这是一个由 GNU 编写的简易问候程序,可在屏幕上打印一句“Hello, world!”。本软件没有依赖项,故而非常适合入门。 -首先切换到 `TREE` 目录,并确定我们目前处于正确的 Git 分支。如前面提到的主题制迭代流程所要求,您需要首先为这个包创建一个 Git 分支。由于要引入新软件包,根据 [AOSC OS 主题制维护指南 (AOSC OS Topic-Based Maintenance Guidelines)](@/developer/packaging/topic-based-maintenance-guideline.md),分支名称应为 `$PKGNAME-$PKGVER-new`,即 `hello-2.12-new`。 +首先切换到 `TREE` 目录,并确定我们目前处于正确的 Git 分支。如前面提到的主题制迭代流程所要求,您需要首先为这个包创建一个 Git 分支。由于要引入新软件包,根据 [AOSC OS 主题制维护指南 (AOSC OS Topic-Based Maintenance Guidelines)](@/developer/packaging/topic-based-maintenance-guideline.md),分支名称应为 `$PKGNAME-$PKGVER-new`,即 `hello-2.12.1-new`。 因为 `hello` 属于实用工具,我们要在 `app-utils` 下创建 `hello` 目录。 @@ -204,7 +204,7 @@ RECONF=0 ciel build -i main hello ``` -很简单,对吧?这是因为 Autobuild3 的自动探测功能判断出这个包需要使用 `autotools`(即 `./configure && make && make install`)流程进行构建。 +很简单,对吧?这是因为 Autobuild4 的自动探测功能判断出这个包需要使用 `autotools`(即 `./configure && make && make install`)流程进行构建。 ## Git 操作规范 @@ -228,7 +228,6 @@ hello: new, 2.12.1 $PKG_NAME: update to $NEW_VER ``` - 现在以bash为例,若要将其版本升级至 5.2,则提交信息为: ``` bash: update to 5.2 @@ -248,7 +247,7 @@ bash: update to 5.2 在成功构建软件包后,您可以将本地 Git 分支(如 `hello-2.12.1-new`)推送至您的 fork 中(如有提交权限,可推送至主树中)。随后,您需要创建拉取请求(Pull Request, PR)并按模板要求填入信息,最后即可将软件包推送至社区软件源的测试分支中供用户测试。 -目前,软件包的上传与推送工作由自动化设施完成,相关内容请见[使用自动化设施构建软件包](@/developer/infrastructure/buildbots.md)。 +目前,软件包的上传与推送工作由自动化设施完成,相关内容请见[使用自动化设施构建软件包](@/developer/packaging/buildit-bot.zh.md)。 接下来,请静候 PR 审核和软件包测试。如果一切顺利,在您的 PR 被合并后,请重构相关软件包并将其上传至 `stable` 源。