OBS 入门介绍

原文链接 https://openbuildservice.org/help/manuals/obs-beginners-guide/

1 目的

本文档主要面向对不同平台硬件及系统发布版本进行源码编译有兴趣的用户及研发人员。建议读者有linux命令行使用基础知识。

2 概述

2005年创建，open build service(OBS)可自动，持续，重复编译及发布包和镜像。OBS能够生成适用于很多系统(SUSE, Debian, Ubuntu, Red Hat, Windows等)及硬件平台(x86, AMD64, z Systems, POWER等)的镜像及安装包。编译目标考虑两个因素，一个是编译包的硬件target，多指CPU版本，一个是编译包的系统distribution，多指系统版本。

2.1 编译清单(Build Recipe)

OBS生成包，需要:

• Metadata(元数据): 关于包的一些信息，如名称，及描述等，名称及描述的必须的，另外还有一些如版本，许可及上游链接地址是可选项。OBS将这些信息存放在工程的meta里。
• Requirements(依赖): 包要正常编译及工作都需要其他的依赖包。
  依赖包分为两种:1、编译依赖，2、安装依赖。
  编译依赖是在编译过程中，需要的其他包及工具，如编译器；
  安装依赖是在安装包时，需要的依赖包。
• A Package List: 文件清单。在安装及卸载包时，需要知道哪个文件是属于这个包的。

基于RPM的操作系统，如openSUSE，SUSE企业版，或者红帽企业版linux，以上所有的信息都包含在后缀为.spec的文件里。

2.2 编译主机及包(Build Hosts and Packages)

OBS服务器提供网页端接口及后台接口。后台使用是通过osc命令行工具。
OBS后端创建独立分区的沙盒来编译，沙盒隔离于其他宿主机。根据编译清单(RPM系统中是.spec文件)，在编译时其他依赖包先下载及安装。
编译程序根据编译清单的指示执行编译。编译成功则将该工程包中的文件安装到沙盒，通过沙盒文件，编好的RPM包被存放在OBS的download页面(download repository)下。
最后，用户可以自行选择工具安装编好的。SUSE类的系统，用户可以使用YaST or Zypper命令行来安装RPM安装包。
其他一些OBS相关的服务(如通知服务，镜像接口等)执行指定的任务。这些超出了本文档的范畴。
图1 为OBS概览图 https://openbuildservice.org/help/manuals/obs-beginners-guide/images/obs-concept.svg

2.3 工程及包(Projects and Packages)

OBS使用工程管理包，一个工程可以包含多个包并指定的组织目标。工程定义访问控制，依赖库，编译目标(针对操作系统及硬件平台)。
工程中可以创建其他的工程(子工程)，他们与父工程隔离开，可以进行单独的配置。
每个工程的名字通过冒号(:)区分开，如openSUSE的编译服务器字体工程M17N:fonts作为M17N的一个子工程。python程序语言工程devel:languages:python是工程devel:languages的子工程，同时devel:languages是devel工程的子工程。
作为用户，通常在home 工程下编译包。OBS中名为home:USERNAME的工程为home工程。home工程会作为用户的个人工作区，定义编译目标，上传、编译及下载包。用户可以为其他人包的创建临时子工程。
当你看见obs://DOMAIN/PROJECT链接时，需将obs://替换成真实的OBS链接。obs://只是长链接地址的缩写。

3 osc命令行使用

在使用OBS之前。请确认以下的包已经安装。
软件需求
找到适用自己系统的osc并安装，也可以通过openSUSE:Tools:工程查找。

• 对于SUSE类的系统，使用zypper安装osc。(将以下命令行中的DISTRIBUTION更换成对应的系统版本)

root # zypper ar https://download.opensuse.org/repositories/openSUSE:/Tools/DISTRIBUTION/openSUSE:Tools.repo
root # zypper install osc

• 其他操作系统，使用适用的包管理工具安装osc。
• Appimage作为被选方案，Appimage，是应用的打包文件可以运行于很多不同的系统版本上。 可通过https://download.opensuse.org/repositories/openSUSE:/Tools/AppImage/下载该文件，并保存到~/bin路径下，添加可执行权限。
  硬件需求
  确保最少1GB的空闲磁盘空间。osc本地编译的工作目录为:/var/tmp/oscbuild，其缓存的依赖包保存在/var/tmp/osbuild-packagecache路径下。

4 OBS系统配置

如果没有经过配置，osc可能直接可以使用，但是建议用户按以下步骤进行系统配置。
依赖包完成下载之后，启动编译前，需要输入root用户密码，这会给重复编译带来一定的不便。以下的配置可以使用户在编译使无需输入root密码。为确保安全性，只有指定的用户才具有root权限。
按照以下步骤配置sudo
第一步: 配置sudo:
按照以下步骤配置osc用户组中的用户免sudo密码编译。

1. 以root用户登录，新建osc用户组。该用户组中包含所有用于编译的用户。

root # groupadd osc

2. 添加用户到osc用户组，该用户组中的用户用于编译。

root # usermod -a -G osc geeko
如果需要添加其他用户到用户组osc时，重复以上步骤。

3. 运行visudo命令创建sudoers配置文件/etc/sudoers.d/osc。

root # visudo -f /etc/sudoers.d/osc

4. 添加以下内容，用于创建命令别名，只有osc用户组用户才能使用。

# sudoers file “/etc/sudoers.d/osc” for the osc group
Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build
%osc ALL = (ALL) NOPASSWD:OSC_CMD

5. 登出系统，并重新登录，使配置生效。
6. 新建OBS配置文件。

geeko > osc ls home:obsgeeko
首次执行该命令，系统会提示输入OBS用户名及密码。

Notes: 可配置目录结构
如果你想用文件夹及子文件夹的形式区分项目与子项目的关系，如下修改配置文件~/.oscrc中的对应行:
checkout_no_colon = 1
这样配置后，如果要下拉(checkout)工程时，工程名的写法也要对应配置。如要下拉home工程，则会在本地生成home/obsgeeko目录结构，而不是home:obsgeeko。
默认的工程分级使用冒号(?

5 涵盖场景

本文档基于以下的假设，你可能会碰到其他的场景:

• 在Subversion(SVN)周后，Git普遍被使用，很多OBS的概念有了新的形式。你已经拥有版本管理系统，比如Git及Subversion(SVN)的知识。
• 你正使用的是openSUSE Build Service，官网https://build.opensuse.org。如果你使用其他的OBS版本，一些使用命令可能有所差异。
• 你拥有一个Open Build Service的账户。
• 你当前的系统是基于RPM的系统，比如openSUSE 或 SUSE企业版。
• 系统已配置，上述第4节OBS系统配置已完成。
  所有例子都基于以下元素:
• 用户名geeko，用于编译
• OBS用户名obsgeeko，home工程home:obsgeeko，
• 另一个OBS用户obstux，home工程home:obstux，用于演示协作编译等。
• 上游OBS https://github.com/obs-example/my-first-obs-package 有一个可用的工程例子，这个工程中包含了用C++编写的一些源码。

本文档主要描述了以下内容:

• 6 配置home工程
  使用网页端接口配置home工程
• 7 新建项目
  基于github上的源码创建包
• 8 源码patch的应用。
  在有源码的基础上应用patch
• 9 为工程建立分支。
  新建分支，应用改变，并提交改变到上游。
• 10 安装OBS上的包
  添加OBS的下载库到系统资源列表，并安装包。

6 配置home工程

本节讲述了创建openSUSE用户后如何设置home工程。
第一次登录，home工程是空的，编译需要选定编译目标(target: 系统版本及硬件平台)。编译目标针对项目设定。一个项目下的所有包都使用一个编译目标(target)。不过，可以对包的target进行disable。
根据以下步骤设置home工程:
第二步: 设置默认的home工程编译目标

1. 设置home工程的编译目标；
2. 点击右上角home project；
3. 点击Repositories栏，再点击Add Repositories；
4. 选择要编译的系统版本；
   OBS提供几个linux发布版本，对于SUSE发布版，建议激活openSUSE Tumbleweed 和最新的openSUSE Leap release版本。
   点击openSUSE Backports for SLE 12使能SUSE企业版的编译目标。
5. 点击Overview栏查看可使用的编译目标位于右侧。

如果需要增加其他的编译目标，重复以上步骤添加。
优化编译目标，点击Repositories栏，找到对应的系统版本编译目标，点击Repositories，此时会显示，可用的硬件架构以及可增加的包库。

7 新建工程

本节描述了编译github(上游源码工程)简单的C++源码，此处假设，读者要编译的适用与不同SUSE版本的包中包含源码。

首先检查许可说明(license)。
在开始编译之前，到上游工程(存放源代码)检查对应的许可说明。
比如，对于openSUSE build service，需要根据源码是否开元重新分配包。在发布编好的包时，服务端会检查源码的许可声明，如果你的包没有开源许可，会被拒绝。
https://license.opensuse.org上有再用的许可清单，开源许可说明详细信息及对照参见 https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses
按照以下步骤，新建上游工程:

1. 配置home工程，参考第6节:配置home工程。
2. 选择或新建一个具有足够容纳包大小的目录。
3. (下拉)checkout home工程。

geeko > osc checkout home:obsgeeko
这个命令会在本地目录下新建一个名为home:obsgeeko空目录

4. 在本地工具目录创建新包。

geeko > cd home:obsgeeko
geeko > osc mkpac my-first-obs-package

5. 从上游工程下载代码，将其保存至home:obsgeeko/my-first-obs-package。
   下载源码的TAR(压缩包)。我们的例子工程在github上，链接地址: https://github.com/obs-example/my-first-obs-package/releases，如果没有发布的版本，点击Clone or download button，用Download ZIP下载最新的代码。
6. 创建编译清单，这个文件包含了元数据和编译命令。
   本例，我们编译openSUSE使用的rpm包，基于RPM的系统，创建.spec文件。spec文件的结构如下:

例1: spec文件的结构:

\# spec file for package my-first-obs-package
\#
\# -- Copyright omitted --

Name:           my-first-obs-package 【1】
Version:        0.1.0 【1】
Release:        0 【1】
License:        GPL-3.0 【1】 
Group:          Documentation 【1】 
Summary:        Frobnication Tool  【1】
Url:            https://github.com/obs-example/my-first-obs-package 【1】
Source:         my-first-obs-package-%{version}.tar.gz 【1】
BuildRequires:  gcc 【2】
BuildRequires:  cmake 【2】
BuildRoot:      %{_tmppath}/%{name}-%{version}-build【2】

%description 【3】
This tool frobnicates the bar with the foo when choosing the baz.

%prep 【4】
%setup -q -n %{name}-%{version}

%build 【5】

%install 【6】

%files 【7】
%defattr(-,root,root,-)
%doc README LICENSE *.txt
%{_bindir}/*

%changelog 【8】

【1】文件头。元数据信息，如包名，版本，发布，许可，RPM组，简要的说明，上游源码地址及源码文件名
【2】编译依赖。列出所有编译过程中的依赖包。这些包会在编译开始之前被编译安装。
【3】描述部分
关于包的用途以及概括性的描述。
【4】准备内容
编译需要的源码准备。这部分一般包含源码的解压及打包，解压使用宏定义%setup，压缩用宏定义%patch表示。(关于patch的更多内容，请阅读第8节：源码 patch。)
【5】编译部分
包含编译相关的命令和RPM宏。
【6】安装部分
包含关于安装时创建目录及拷贝文件的命令行及宏。
【7】文件部分
列出所有属于该包的文件，相关文档文件用%doc标注，在安装时文档文件会被自动安装到默认的文档目录下。
【8】change log部分
这个部分经常是空的。OBS会查找工程目录下后缀为.changes的文件，自动将其添加为changelog，changelog 文件变动记录的概览信息。
关于完整的spec文件，请访问 https://build.opensuse.org/package/view_file/home:obsgeeko/my-first-obs-package/my-first-obs-package.spec。

7. 创建changelog文件。

geeko > osc vc

这个命令会使用默认的编辑器打开一个文本文件，内容如下：

---

Fri Aug 23 12:31:41 UTC 2017 - geeko@example.com

添加一个简短的变动说明。通常，一个changelog文件会包含包变动信息概述，比如，该包的版本，应用补丁文件名，以及其他的变动信息。
保存更改并推出编辑器。此时，osc便创建了名为my-first-obs-package.changes的文件。

8. 添加所有的文件到工作目录下。

geeko > osc add *.spec *.changes *.tar.gz

9. 编译默认的编译目标(build target)包。

geeko > osc build --local-package

这里使用–local-package选项，因为是本地编译，该包还没有被上传到OBS。
默认的编译目标是在配置文件~/.oscrc中build_repository变量指定的。对于openSUSE Build Service，编译目标通常是openSUSE Tumbleweed。
编译其他版本的包，请用以下命令：

geeko > osc build --local-package openSUSE_Tumbleweed x86_64 *.spec

10. 检查编译是否成功。如果没有错误，将包提交到OBS home工程下。

geeko > osc commit
如果遇到编译错误，可以使用 osc buildlog命令查看。如下所示：
查看指定编译版本的编译信息，在工作目录下使用osc buildlog命令：
geeko > osc openSUSE_Tumbleweed x86_64

8 源码应用patch

本节主要讲述如果在上游工程的基础上应用patch，这里我们用与第7节：新建工程相同的工程演示。
需要应用patch的几个原因;

• 用户没有直接修改上游工程的权限，通常，用户不能直接提交changelog到上游工程。如果用户提交(changes)变动到上游工程，变动会推迟应用到工程里甚至被拒绝应用。
  patch文件可以在作出改变的同时，保证最初源码的不变性。并且可以允许change与上游工程的发布链，代码风格以及中间操作相独立。
• 应用保密机制以及bug修复，或者指定版本修复。
• 改动源码，会直接出发OBS编译。
• 提高安全性及可追溯性。 不直接修改源码，可以使校验改动更方便，校验改动经常使用checksum(MD5 or SHA)值检验。
• 保持结构的连贯性。 从组织管理者的角度来看，将改动与源码分离更佳，将改动保存在patch文件中，每个用户都能看到哪些文件有哪些改动。

我们假设你现在已经创建了第7节：新建工程描述的工程。工程的文件结构大致如下：

工程目录结构
├── my-first-obs-package-0.1.0.tar.gz
├── my-first-obs-package.changes
└── my-first-obs-package.spec

在这个例子中，我们修改src/main.cpp代码中的问候语。
第三步应用patch。

1. 在终端命令行中，切换到工作目录下。
2. 准备patch文件。
   a. 解开源码包。

geeko > tar xvf my-first-obs-package-*.tar.gz
如果你是在github上下载的文档，这个文档包含了一个名字结构是NAME-VERSION的目录。在本例中，将解压后的文件放在my-first-obs-package-0.1.0/目录下。

   b. 切换到my-first-obs-package-0.1.0/下，复制原始的C++文件。

geeko >cd my-first-obs-package-0.1.0/
geeko >cp src/main.cpp src/main.cpp.orig

    c. 修改 src/main.cpp文件。
    d. 创建diff文件，并认真检查变动。

geeko > diff -u src/main.cpp.orig src/main.cpp
输出如下:

--- src/main.cpp.orig   2017-08-09 16:28:31.407449707 +0200
+++ src/main.cpp        2017-08-09 16:28:49.131541230 +0200
@@ -2,7 +2,7 @@

 int main()
 {
-    std::cout<<"Hello OBS!\n";
+    std::cout<<"Hello Alice!\n";

     return 0;
 }

    e. 将输出保存至文件。

geeko > diff -u src/main.cpp.orig src/main.cpp \
../my-first-obs-package_main.diff

    patch文件的名字用户可以任意指定。不过，我们建议文件名带有描述性并且加入上游工程的名称，如果这个patch与bug或问题有关系，将bug号等信息也添加到patch文件名中。用户可以用.diff或.patch作为文件的后缀。
    f. 你可以删除my-first-obs-package-0.1.0/目录。

3. 打开spec文件，在文件头的Source行下加入以下信息。

Source: my-first-obs-package-%{version}.tar.gz
Patch0: my-first-obs-package_main.diff

4. 在%prep下加入%patch宏。

%prep
%setup -q -n %{name}-%{version}
%patch0

5. 本地应用patch文件。
6. 重新编译

geeko > osc build

7. 如果没有问题，提交chages

geelo > osc commit
根据提示，指定并保存提交信息。
如果需要处理很多patch文件，可以使用quilt工具。关于quilt更过信息，请查询 https://savannah.nongnu.org/projects/quilt

9 包的分支

讲述拉取别人的OBS工程到本地，修改提交。branchco建立branch工程并下拉指定的别人的工程到本地。
本节主要描述如果实现工程之间的协作。用户可以为OBS中具有写权限的所有工程中创建分支。默认新的分支以home工程子工程的形式创建，分支名默认以home:obsgeeko:branches开头。
需要工程分支的原因如下：

• 修改源码，编译，测试改动效果，提交改动到原始工程。通常，用户在没有仓库写权限的情况下，使用该工作流程。
• 不影响原始工程的前提下应用改动。
• 应用临时改动，在不同路径下开发测验
  假设你已经下拉(check out)home:obsgeeko/my-first-obs-package。在OBS上，有另一个用户obstux想改动源码中的欢迎信息，改动最后被提交到原始工程中。
  obstux用户需按以下步骤执行：

第4步，工程的分支创建

1. 在终端，在一个足够容量的本地分区下，选择或创建一个目录。
2. 创建geeko的工程分支。

tux > osc branchco home:obsgeeko my-first-obs-package

这个命令会创建branch工程home:obstux:branches/my-first-obs-package，并且会下拉home:obsgeeko my-first-obs-package，存放至本地home:obstux:branches:home:obsgeeko:my-first-obs-package。

3. 切换到本地工程分支路径下。

4. tux > cd home:obstux/branches/home/obsgeeko/my-first-obs-package

5. 做出改动，按照第8节，应用patch。
6. 编译目标。

geeko > osc build

7. 查看编译log。

geeko > osc buildlog openSUSE_Tumbleweed x86_64

8. 确认所有添加及删除的文件都被上传到OBS仓库中。

tux > osc addremove

9. 如果没有出现错误，提交更新。
10. 创建发布申请，添加注释信息并完成发布。

tux > osc submitreq

如果没有指定项，提交会被发布到拉的分支(原始)的工程包中。在提交发布之后，用户会发布一个指定版本的源码。之后的改变默认不会自动被拉入。
如果一个分支中存在多个包，所有的包会被一起发布。入股不想所有包均被发布，可以按照以下命令指定源码，目标工程及报名。

tux > osc submitreq home:obstux:branches:home:obsgeeko my-first-obs-package home:obsgeeko

此时，用户obstux已经完成一个完成一次任务，发布申请以及提交到obsgeeko。用户obsgeeko可以选择接受或者取消此处发布申请。

• 接受发布申请。用户obstux的提交会诶集成到home:obsgeeko工程中，本次发布申请结束。
• 取消发布神奇。用户obstux的提交不会被集成到home:obsgeeko工程中。
  取消发布申请的原因可以是编译问题以及编程风格问题，查阅提交的用户如要取消发布申请必须给出原因。用户obstux可以 1) 修改申请并重新发布申请，覆盖前一次申请。2) 不同意取消发布，重新打开申请。3) 接受取消申请，并废弃申请。
  用户obsgeeko可以按照如下命令做出回应。

第5步 处理发布申请

1. 列出所有home工程下所有的发布申请。

geeko > osc request list -s new -P home:obsgeeko

2. 找到正确的发布申请，如果你知道申请号，可以使用申请号。

geeko > osc request show 246

3. 查看申请，并做出决定。

• 接受申请。

geeko > osc request accept 246 --message=“Reviewed OK.”

• 取消申请。

geeko > osc request decline 256 --message=“Declined, because of missing semicolon.”

如果申请被接受，此次申请的变动会被集成到home:obsgeeko工程中。
如果申请被取消，用户可以解决问题并重新提交，如果创建新的发布申请，OBS会覆盖前一次的提交申请。

安装OBS包

OBS提供了包含所有编译成功的平台架构的安装包的地方，如果你在home工程下新增了包，所有成功编译的包都会出现在 https://download.opensuse.org/repositories/home:/obsgeeko。
home工程及手动创建的子工程的包会在OBS显示，分支工程的子工程中的包不会被发布，如果用户需要编译结果，可用osc getbinaries命令来下载二进制编译文件。
例如，如果用户使能openSUSE Tumbleweed的版本，所有openSUSE Tumbleweed的编译包会发布在https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_Tumbleweed
download repository提供的下载包需要Zypper or YaST安装及管理。

安装home工程my-first-obs-package的包，按照以下步骤。

1. 进入工作目录，指定下载地址。

geeko > osc repourls
https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_Tumbleweed/home:obsgeeko.repo
https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_42.2/home:obsgeeko.repo

2. 复制需要的发布地址，在本例中，我们拷贝openSUSE_Tumbleweed版本发布地址。
3. 使用zypper工具，添加上一步复制的地址。

root #zypper addrepo https://download.opensuse.org/repositories/home:/obsgeeko/openSUSE_Tumbleweed/home:obsgeeko.repo
根据提示，接受下载网址的GPG key。

4. 安装包

root # zypper install my-first-obs-package

如果需要更新包，重新执行第4步，用户不需要重第一步开始执行，因为此网址已经配置在系统系统中。

其他osc命令

以下简要说明osc几个常用的子命令的用途及用法，用户可使用osc SUBCOMMAND --help查看子命令的简要说明。
osc diff
与git diff类似，生成一个diff，存放本地的变动情况，比较本地与远程仓库的区别。
osc list
列出obs服务器源码及二进制文件
osc prjresults
显示工程编译信息。
osc status
显示本地文件状态

完~