14 KiB

Raw Blame History

移植GNU Hello到openKylin

本文是openKylin软件包打包移植的示例文档

一、GNU Hello 项目介绍

GNU Hello项目是 GNU 推出的示例软件，此项目将入门的 hello world 程序，以正规的 GNU 规范来实现，作为 GNU 编码标准和 GNU 维护者实践的参考范例。俗话说得好，麻雀虽小，五脏俱全，GNU Hello 虽然只是一个 hello world 程序，却包含了如下几项技术：

Automake 和 Autoconf：生成编译配置脚本
Gnulib：程序的基本函数库
Gettext：国际化支持
getopt：命令行参数支持
help2man：用程序的--help选项输出生成manpage
Texinfo：编写程序文档

GNU项目中其他更复杂的软件系统，只是具体的业务逻辑复杂度更高，其组织结构与GNU Hello项目展示的规范保持一致。

二、对上游源码进行打包

openKylin 使用 apt 作为包管理器，因此将上游软件引入 openKylin 时，需要把上游源代码打包成符合 Debian 规范的源码包。

1. 获取上游源码

GNU Hello 项目的官方网站为：https://www.gnu.org/software/hello/

在官网介绍中获取最新版(2.12.1)的下载地址：https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz

随后下载并解压源码包：

$ wget https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz
$ tar -xaf hello-2.12.1.tar.gz

2. 使用 debmake 产生模板文件

进入源码目录，执行debmake

$ cd hello-2.12.1
$ debmake
I: set parameters
I: sanity check of parameters
I: pkg="hello", ver="2.12.1", rev="1"
I: *** start packaging in "hello-2.12.1". ***
I: provide hello_2.12.1.orig.tar.gz for non-native Debian package
I: pwd = "/data2/test/hello"
I: $ ln -sf hello-2.12.1.tar.gz hello_2.12.1.orig.tar.gz
I: pwd = "/data2/test/hello/hello-2.12.1"
I: parse binary package settings: 
I: binary package=hello Type=bin / Arch=any M-A=foreign
I: analyze the source tree
I: build_type = Autotools with autoreconf
I: scan source for copyright+license text and file extensions
I:  43 %, ext = c
I:  27 %, ext = m4
I:  11 %, ext = gmo
I:  11 %, ext = po
I:   1 %, ext = gperf
I:   1 %, ext = mk
I:   1 %, ext = in
I:   1 %, ext = texi
I:   0 %, ext = sin
I:   0 %, ext = sed
I:   0 %, ext = header
I:   0 %, ext = text
I:   0 %, ext = O
I:   0 %, ext = ac
I:   0 %, ext = am
I:   0 %, ext = 1
I:   0 %, ext = pot
I:   0 %, ext = x
I:   0 %, ext = valgrind
I:   0 %, ext = info
I:   0 %, ext = tex
I:   0 %, ext = sub
I:   0 %, ext = rpath
I:   0 %, ext = sh
I:   0 %, ext = guess
I: check_all_licenses
......
I: check_all_licenses completed for 447 files.
I: bunch_all_licenses
I: format_all_licenses
I: make debian/* template files
I: single binary package
I: debmake -x "1" ...
I: creating => debian/control
I: creating => debian/copyright
I: substituting => /usr/share/debmake/extra0/changelog
I: creating => debian/changelog
I: substituting => /usr/share/debmake/extra0/rules
I: creating => debian/rules
I: substituting => /usr/share/debmake/extra1/compat
I: creating => debian/compat
I: substituting => /usr/share/debmake/extra1/watch
I: creating => debian/watch
I: substituting => /usr/share/debmake/extra1/README.Debian
I: creating => debian/README.Debian
I: substituting => /usr/share/debmake/extra1source/local-options
I: creating => debian/source/local-options
I: substituting => /usr/share/debmake/extra1source/format
I: creating => debian/source/format
I: substituting => /usr/share/debmake/extra1patches/series
I: creating => debian/patches/series
I: run "debmake -x2" to get more template files
I: $ wrap-and-sort

运行debmake后生成了新的 debian 目录和模板文件，查看此时的源码树

$ cd ..
$ tree
├── hello-2.12.1
│......
│   ├── debian
│   │   ├── changelog
│   │   ├── compat
│   │   ├── control
│   │   ├── copyright
│   │   ├── patches
│   │   │   └── series
│   │   ├── README.Debian
│   │   ├── rules
│   │   ├── source
│   │   │   ├── format
│   │   │   └── local-options
│   │   └── watch
│......
├── hello_2.12.1.orig.tar.gz -> hello-2.12.1.tar.gz
└── hello-2.12.1.tar.gz

3. 编辑 debian 目录模板文件

(1) 检查 debian/source 文件夹

[1] 确保软件包格式为 quilt

debian/source/format文件中定义了源码包的格式，通常分为3.0 (native)和3.0 (quilt)，根据 openKylin 软件包构建工作流的要求，源码包格式必须为3.0 (quilt)。

$ cat debian/source/format 
3.0 (quilt)

[2] local-options 文件一般不需要，可以去掉

rm debian/source/local-options

(2) 编辑 debian/changelog 文件

debian/changelog是软件包的更新日志，记录内容包括软件包包名，版本号，版本信息描述等。我们先查看debian/changlog文件的默认的初始化内容：

hello (2.12.1-1) UNRELEASED; urgency=low

  * Initial release. Closes: #nnnn
    <nnnn is the bug number of your ITP>

 -- your name <your email address>  Wed, 16 Nov 2022 09:40:47 +0800

第一行最左边是软件包名称，其右侧括号内的是软件包版本号，软件包版本号格式为：<upstream_version>-<revisions>，upstream_version是上游版本号，在执行debmake时，已经自动识别上游版本号为2.12.1；revisions是修订版本，默认是1，对于 openKylin 软件包，使用ok1作为第一次revisions。

版本号右侧的UNRELEASED需要修改为yangtze，中间的描述部分通常写为：Build for openKylin。

最后一行中的your name为个人署名，建议使用英文，your email address为个人电子邮箱，这两处都需要填写，不可缺少。

修改完成后的debian/changlog文件内容应参考如下所示：

hello (2.12.1-ok1) yangtze; urgency=medium

  * Build for openKylin.

 -- zhangsan <zhangsan@email.com>  Tue, 15 Nov 2022 10:13:02 +0800

(3) 编辑 debian/control 文件

debian/control定义了源码包和二进制包的信息，包括编译依赖、安装依赖等，是必不可少的一个文件，根据上游软件展出的信息等进行编写即可，修改完成后如下所示。

Source: hello
Section: devel
Priority: optional
Maintainer: openKylin Developers <developers@lists.openkylin.top>
Standards-Version: 4.3.0
Build-Depends: debhelper-compat (= 9)
Homepage: http://www.gnu.org/software/hello/
Rules-Requires-Root: no

Package: hello
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Conflicts: hello-traditional
Replaces: hello-traditional, hello-debhelper (<< 2.9)
Breaks: hello-debhelper (<< 2.9)
Description: example package based on GNU hello
 The GNU hello program produces a familiar, friendly greeting.  It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them.
 .
 Seriously, though: this is an example of how to do a Debian package.
 It is the Debian version of the GNU Project's `hello world' program
 (which is itself an example for the GNU Project).

(4) 编辑 debian/rules 文件

debian/rules是应当由软件包维护者提供的构建脚本，这个文件事实上是另一个 Makefile，需要根据具体上游软件的编译方法，编写相应的内容。Debian格式的源码包在编译时，默认读取debian/rules文件中的内容作为编译规则，此文件同样不可或缺。

Hello是一个标准的使用Autotools构建的软件包，其编译安装方法为：

$ ./configure 
$ make
$ sudo make install

根据上述编译方法，可以编写 debian/rules 文件内容如下：

#!/usr/bin/make -f
%:
    dh $@

override_dh_auto_clean:
    [ ! -f Makefile ] || $(MAKE) distclean

override_dh_installdocs:
    dh_installdocs NEWS

(5) 处理非必需文件

debian/compat 和 debian/README.Debian 不是必需的文件，对于此软件包可以去掉。

$ rm debian/compat
$ rm debian/README.Debian

4. 打包并测试编译

在源码目录顶层执行dpkg-source -b .，即可将上游源码打包为 Debian 格式的源码包，打包成功后会生成.debian.tar.xz和.dsc结尾的两个新文件。

$ dpkg-source -b .
dpkg-source: info: using source format '3.0 (quilt)'
dpkg-source: info: building hello using existing ./hello_2.12.1.orig.tar.gz
dpkg-source: info: building hello in hello_2.12.1-ok1.debian.tar.xz
dpkg-source: info: building hello in hello_2.12.1-ok1.dsc

$ tree -L 1 ../
../
├── hello-2.12.1
├── hello_2.12.1-ok1.debian.tar.xz
├── hello_2.12.1-ok1.dsc
├── hello_2.12.1.orig.tar.gz -> hello-2.12.1.tar.gz
└── hello-2.12.1.tar.gz

1 directory, 4 files

在把源码包上传至Git仓库之前，我们还可以先在本地进行编译测试，确认 debian/rules 等文件是否编写正确。每次打包时，都建议先完成本地编译测试，再上传到Git仓库。Debian格式的源码包在编译时使用的是dpkg-buildpackage工具。编译成功时，如下所示：

$ dpkg-buildpackage -b -uc
dpkg-buildpackage: info: 源码包 hello
dpkg-buildpackage: info: 源码版本 2.12.1-ok1
dpkg-buildpackage: info: source distribution yangtze
dpkg-buildpackage: info: 源码修改者 your name <your email address>
dpkg-buildpackage: info: 主机架构 amd64
......
dpkg-deb: 正在 '../hello_2.12.1-ok1_amd64.deb' 中构建软件包 'hello'。
dpkg-deb: 正在 'debian/.debhelper/scratch-space/build-hello/hello-dbgsym_2.12.1-ok1_amd64.deb' 中构建软件包 'hello-dbgsym'。
        Renaming hello-dbgsym_2.12.1-ok1_amd64.deb to hello-dbgsym_2.12.1-ok1_amd64.ddeb
 dpkg-genbuildinfo --build=binary
 dpkg-genchanges --build=binary >../hello_2.12.1-ok1_amd64.changes
dpkg-genchanges: info: binary-only upload (no source code included)
 dpkg-source --after-build .
dpkg-buildpackage: info: binary-only upload (no source included)

$ tree -L 1 ../  
../
├── hello-2.12.1
├── hello_2.12.1-ok1_amd64.buildinfo
├── hello_2.12.1-ok1_amd64.changes
├── hello_2.12.1-ok1_amd64.deb
├── hello_2.12.1-ok1.debian.tar.xz
├── hello_2.12.1-ok1.dsc
├── hello_2.12.1.orig.tar.gz -> hello-2.12.1.tar.gz
├── hello-2.12.1.tar.gz
└── hello-dbgsym_2.12.1-ok1_amd64.ddeb

1 directory, 8 files

三、将源码包上传至Gitee平台

1. 创建对应的Git仓库

(1) fork openkylin/community 仓库到个人仓库中

在openKylin组织中创建新的代码仓库，需要用到openkylin/community仓库：https://gitee.com/openkylin/community

在浏览器网页端forkopenkylin/community仓库到个人账号，会生成新的仓库地址：https://gitee.com/<username>/community，将这个新仓库clone到本地。

$ git clone git@gitee.com:<username>/community.git

后续流程从维护者角色来说，分为 单独的包维护者 和 SIG组维护者 两种。

(2) 作为单独的包维护者

[1] 创建软件包维护信息

进入到一级目录packages里面，创建hello.yaml文件，添加以下内容： (更多填写示例可以浏览：https://gitee.com/openkylin/community/tree/master/packages)

name: hello
path: hello
maintainers:
- name: 你的Gitee ID
  openkylinid: 你的openkylinid用户名
  displayname: 你的姓名或昵称
  email: 你的联系邮箱

[2] 将改动推送到个人远端仓库中，并向openkylin/community仓库提交pr

$ git add packages
$ git commit -m "添加hello软件包维护信息"
$ git push origin master

推送到个人仓库之后，在web页面端发起Pull Requests请求，对应的社区管理人员审核通过并接受pr之后，openkylin平台内部会根据软件包维护信息中描述的内容自动创建相应openkylin仓库。

例如，上面的hello软件包的pr请求合并之后，会创建出名为hello的openkylin仓库，可以在浏览器中访问该仓库，这里hello软件包对应的仓库地址为：https://gitee.com/openkylin/hello

(3) 作为SIG组维护者

[1] 创建软件包维护信息

这一步需要在对应的sig组的sig.yaml文件中添加源码包名称，这里以Packaging SIG组举例，操作示例如下：

$ echo "- hello" >> sig/packaging/sig.yaml

[2] 将改动推送到个人远端仓库中，并向openkylin/community仓库提交pr

$ git add sig/packaging/sig.yaml
$ git commit -m "新增hello软件包"
$ git push origin master

推送到个人仓库之后，在web页面端发起Pull Requests请求，对应的SIG组维护者审核通过并接受pr之后，openkylin平台内部会根据软件包维护信息中描述的内容自动创建相应openkylin仓库。

2. 构建本地Git仓库

获取构建工具：https://gitee.com/openkylin/packaging-tools

$ path/to/source-packing.py import-to-git --dsc-file hello_2.12.1-ok1.dsc --packaging-branch openkylin/yangtze

3. 推送至远程Git仓库

$ cd hello
$ git remote add origin git@gitee.com:openkylin/hello.git
$ git push --all && git push --tags

此时可以在浏览器中打开Gitee平台的仓库链接(https://gitee.com/openkylin/hello)，查看源代码是否推送成功。

14 KiB Raw Blame History Unescape Escape

移植GNU Hello到openKylin

一、GNU Hello 项目介绍

二、对上游源码进行打包

1. 获取上游源码

2. 使用 debmake 产生模板文件

3. 编辑 debian 目录模板文件

(1) 检查 debian/source 文件夹

[1] 确保软件包格式为 quilt

[2] local-options 文件一般不需要，可以去掉

(2) 编辑 debian/changelog 文件

(3) 编辑 debian/control 文件

(4) 编辑 debian/rules 文件

(5) 处理非必需文件

4. 打包并测试编译

三、将源码包上传至Gitee平台

1. 创建对应的Git仓库

(1) fork openkylin/community 仓库到个人仓库中

(2) 作为单独的包维护者

[1] 创建软件包维护信息

[2] 将改动推送到个人远端仓库中，并向openkylin/community仓库提交pr

(3) 作为SIG组维护者

[1] 创建软件包维护信息

[2] 将改动推送到个人远端仓库中，并向openkylin/community仓库提交pr

2. 构建本地Git仓库

3. 推送至远程Git仓库

14 KiB

Raw Blame History