Basic Overview of the debian/ Directory

這個部份來簡短的說明一下包含在debian/directory底下的Ubuntu packages打包流程的一些重要檔案。最重要的就是『changelog』，『control』，『copyright』和『rules』，因為在每個package底下都會需要這幾個檔案。而不只這些檔案而已，也會有其他檔案在這個『debian/』底下，都是用來客製化和組態這個package的，有部份的檔案會在這個文章被探討到，但絕對不是全部都會。

1. The changelog

這個檔案就如同檔名一樣，就是一系列的版本清單，每個版本所作的改變，裡面的每筆資料都有特定的格式，通常都是『package name』，『version』，『distribution』，『changes』，『who make the changes at a given time』。如果你已經有GPG key了，請確保使用跟你的GPG key相對應的user name和你的email address，底下是個模板：

package (version) distribution; urgency=urgency

 * change details
  - more change details
 * even more change details

-- maintainer name < email address>[two spaces]  date

照著這個格式是非常重要的，尤其是時間，時間必須是RFC 5322的格式，，一般來說你可以使用命令『date -R』來獲取這個資訊。為了方便起見，你可以使用命令『dch』來編輯這個changelog，它將會自動的更新這個時間(dch通常會在devscripts package裡面)。

主要的項次(major points)要使用星號(asterisk) "*"，次要項目(minor bullet points)就用dash "-"。

如果你是從頭開始打包(packaging)的話，使用『dch --create』將會為你建立一個標準的『debian/changelog』。

底下是個hello小程式的changelog：

hello (2.8-0ubuntu1) trusty; urgency=low

  * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe < [email protected]>  Thu, 21 Oct 2013 11:12:00 -0400

注意在版本的部份有個『-0ubuntu1』，代表的是這個distro的版本，可以在相同的source release version的狀況之下，有新的更新就會被被自動更新(舉個例子來說就是可能有bug被解掉了)。

Ubuntu和Debian在package版本的命名方式會有微小的差異，主要是用來防止在相同的source version底下有衝突。

如果有Debian的package在Ubuntu底下被修改的話，則會有一個ubuntuX會被加在Debian版本的後面(X代表的是Ubuntu的版本(revision))，所以假設Debian hello 2.6-1 package在Ubuntu被修改了，則在changelog底下的版本就會變成『2.6-1ubuntu1』。

而如果這個package並沒有存在Debian底下的話，則Debian的版本就會變成0，也就是會變成『2.6-0ubuntu1』。

這部份更進接的訊息請參考Debian Policy Manual的changelog section (Section 4.4)

2. The control file

這個檔案包含了幾個資訊像是『package manager(像是apt-get, synaptic和adept)』，『build-time dependencies』，『maintainer information』等等。

底下是Ubuntu hello package的control file的範例：

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers < [email protected]>
XSBC-Original-Maintainer: Jane Doe < [email protected]>
Standards-Version: 3.9.5
Build-Depends: debhelper (>= 7)
Vcs-Bzr: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
 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).

第一個段落描述了source package的一些資訊，像是欄位『Build-Depends』描述了建制這個package所需要的其他packages，還有一些meta-information像是maintainer的名字，這個package所遵循的Debian Policy的版本，這次打包(packaging)的版本管控倉儲(version control repository)的位置，還有upstream的home page等等。

在Ubuntu裡，通常會將Maintainer的欄位設定成一個普遍的地址，因為每個人都有可能可以改變任何的package，跟Debian不一樣的是因為在Debian裡面只有特定的人或是團隊才能改變這些packages。所以在Ubuntu裡的packages都要將Maintainer的欄位設定成『Ubuntu Developers < [email protected]>』，如果Maintainer欄位被修改了，則舊的值就必須要被存到欄位『XSBC-Original-Maintainer』底下。對於這個欄位，你要的話也可以經由一個script來自動完成，就是在package『ubuntu-dev-tools』底下的script『update-maintainer』。對這個欄位有更多疑問的話請參考Ubuntu的Wiki - 『 Debian Maintainer Field spec』。

對這個檔案有更多的疑問的話請參考Debian Policy Manual的『control file section (Chapter 5)』。

這個檔案裡面描述了upstream和這個打包(packaging)的版權資訊(copyright)。Ubuntu和Debian Policy (Section 12.5)都需要每個安裝的package底下的路徑『/usr/share/doc/$(package_name)/copyright』都要有逐字的copyright和license。

一般來說，copyright資訊會在程式的原始資料夾裡面的COPYING檔案裡面找到，這個檔案必須包含底下的相關資訊，作者姓名，和打包的人，這個source的URL，包含年份和這個copyright保持者的資訊，還有這個copyright的文字描述，底下次一個模板：

Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: Hello
Source: ftp://ftp.example.com/pub/games

Files: *
Copyright: Copyright 1998 John Doe <[email protected]>
License: GPL-2+

Files: debian/*
Copyright: Copyright 1998 Jane Doe <[email protected]>
License: GPL-2+

License: GPL-2+
 This program is free software; you can redistribute it
 and/or modify it under the terms of the GNU General Public
 License as published by the Free Software Foundation; either
 version 2 of the License, or (at your option) any later
 version.
 .
 This program is distributed in the hope that it will be
 useful, but WITHOUT ANY WARRANTY; without even the implied
 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE.  See the GNU General Public License for more
 details.
 .
 You should have received a copy of the GNU General Public
 License along with this package; if not, write to the Free
 Software Foundation, Inc., 51 Franklin St, Fifth Floor,
 Boston, MA  02110-1301 USA
 .
 On Debian systems, the full text of the GNU General Public
 License version 2 can be found in the file
 `/usr/share/common-licenses/GPL-2'.

上面的這個範例遵循著Machine-readable debian/copyright，如果你有需要的話，也歡迎使用這個格式來撰寫你的copyright資訊。

4. The rules file

這個檔案會處理建立這個package的所有工作，這個檔案就是一個Makefile，裡面有需要編譯和安裝軟體的target，並且會從這些需要安裝的檔案中建立一個『.deb』檔案。並且會有一個target來清除所有已經建制的檔案，所以清除以後就會只剩原始的source package。

底下是個由『dh_make(可以在package『dh-make』裡面找到)』所建立的簡單版本rule file：

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
       dh  $@

上面這個簡單的命令主要是傳遞所有debian/rules裡面被呼叫的所有建制target，並且將其當成參數傳給『/usr/bin/dh』，所以他自己會呼叫所有相關的『dh_*』命令。

dh確實會執行一系列的debhelper的命令，在debian/rules裡面支援的命令包含了『build』，『clean』，『install』，『binary-arch』，『binary-indep』和『binary』。如果你想要看到每個target裡面跑了什麼命令的話可以使用：

$ dh binary-arch --no-act

在『binary-indep』系列的命令都會傳遞option『-i』來確保只會運作在binary獨立的package上。而在『binary-arch』系列的命令則會傳遞option『-a』，來確保只會在架構相依的package上運行。

當每個debhelper命令成功運作時，都會紀錄log在『debian/package.debhelper.log』，所以dh可以辨別那一個命令是已經被執行過了，並且會忽略這些命令的執行，如果你執行『dh_clean』之後就會去清除這個log。

每次『dh』執行時，它都會去檢查這個log，並且找到在序列裡最後被紀錄的命令，然後執行在這序列裡的下一個命令。如果想要複寫這個行為的話可以用options『--until』，『--before』，『--after』，『--remaining』。

如果debian/rules裡面包含的一個target是有名字像是『override_dh_command』的話，則當它在序列裡執行到那個命令時，dh將會在rule file裡面執行這個target，而不是執行真正的命令。而這個即將要被複寫的target則可以執行一個帶有相關options的command，又或者是執行一個完全不同的命令(如果想要使用這個功能的話，你必須要有在debhelper 7.0.50版本以上的Build-Depend)。

更多範例的話可以看一下『/usr/share/doc/debhelper/examples/』或者是amn 一下dh，或者想要進階的訊息可以看一下Debian Policy Manual裡的『the rules section (Section 4.9)』。

5. Additional Files

除了上面4個必須的檔案以外，下面在介紹一下3個也蠻重要的檔案。

5.1 The install file

這個檔案會被『dh_install』所呼叫，用來安裝檔案到binary package底下。這個檔案有兩個標準用途：

  • 如果你的檔案沒有被upstream的build system給維護的話，你可以用這個檔案將你所需要的檔案給包進這個package裡面。
  • 將一個很大的source package給分割成數個binary packages。

在上面的第一個case中，這個install file裡面的每一行都會有一個要安裝的檔案，並指定這個檔案和要安裝的資料夾。舉個例子來說，下面這個範例將會安裝一個在source package的root資料夾裡的script - 『foo』到路徑『usr/bin』底下，然後在資料夾debian底下的『bar.desktop』檔案安裝到『usr/share/applications』底下：

foo usr/bin
debian/bar.desktop usr/share/applications

當一個source package變成多個binary packages時，df將會先將所有的檔案給安裝到『debian/tmp』底下，而不會先將其安裝到『debian/< package>』底下。被安裝到『debian/tmp』底下的檔案接下來將會被移動到分開的binary packages，名字就會像是多個『$package_name.install』。

通常這種作法都會被用來從架構相依(architecture dependent)的package裡面，切割一堆的架構獨立(architecture independent )的資料，然後在將其移動到架構之下。

在這種案例底下，僅有需要被安裝的檔案名稱或資料夾會在檔案裡面，而不需要有『installation directory』。舉個例子來說，底下foo.install這個檔案只包含了架構相依(architecture dependent)的檔案，看起來像是這樣：

# foo.install
usr/bin/
usr/lib/foo/*.so

而檔案foo-common.install則只包含了架構獨立的檔案，看起來會像是

/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/

所以上面兩個檔案將會產生兩個binary packages，foo和foo-common。兩個檔案都需要在debian/control裡面有各自的描述段落。

如果想要有更進接的資訊請參考『man dh_install』或是Debian New Maintainers’ Guide裡面的install file section (Section 5.11)。

5.2 The watch file

這個檔案允許我們使用工具『uscan(在package - devscripts底下)』自動的檢查新的upstream的版本，這個檔案的第一行必須是版本，然後接下來才是包含了URLs，舉例來說：

version=3

http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

在這個rource的root資料夾底下執行『uscan』將會馬上去匹配在debian/changelog下的最新upstream的版本，如果有找到新的upstream版本的話，將會自動的下載，舉例來說：

$ uscan
hello: Newer version (2.7) available on remote site:
  http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
  (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

如果你的tarball是在Launchpad上的話，則這個debian/watch檔案就會有一點複雜，這部份相關可以看一下『Question 21146』和『Bug 231797』，在這個case底下，請使用像是底下:

version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

更進階的資訊請參考『man uscan』和Debian Policy Manual的watch file section (Section 4.11)。

如果想要看watch file回報還沒有跟upstream同步的清單列表請參考『Ubuntu External Health Status』。

5.3 The source/format file

這個檔案代表了source package的格式，它應該會有一行來表示應該要有的格式：

  • 3.0 (native) 代表 Debian native packages (也就是沒有upstream的版本)。
  • 3.0 (quilt), 代表這個packages有數個分開的upstream tarball。
  • 1.0 ，代表這個package希望被顯性的宣告成預設的格式。

以目前來說，如果這個檔案並未存在的話，則這個package source format將會被預設成1.0。你可以明確的將其宣告在source/format檔案裡。如果你選擇不要使用這個檔案來定義其source format的話，則Lintian將會警告你說有檔案遺失了，但是對於這個警告，其實可以直接省略沒關西。

如果可以的話，建議最好是使用比較新的3.0 source format，因為它提供了一系列的功能如下:

  • 支援額外的壓縮格式，像是：bzip2, lzma和xz。
  • 支援數個upstream的tarballs。
  • 如果你要朔身(strip)debian的資料夾的話，並不需要去重新包裝這個upstream 的tarball。
  • Debian的一些特殊改變(changes)將不會被存在『single.diff.gz』底下，但是會存在『debian/patches/』底下的多個patches底下，而這些patches又可以跟『quilt』相容。

https://wiki.debian.org/Projects/DebSrc3.0底下整理了許多額外資訊，參考這些資訊你就可以將相關的資訊給轉換到3.0的source package formats了。

額外的資訊可以參考『man dpkg-source』和Debian New Maintainers’ Guide的『source/format section (Section 5.21)』。

6. Additional Resources

上面每個章節裡面下面都會有個連結，而這些連結都會連到比較詳細的『Debian Policy Manual』底下。在 Chapter 4, “Required files under the debian directory”底下更進接的討論了control，changelog，copyright和rules files。而在Chapter 5, “Other files under the debian directory”底下則討論了許多可能會使用到的檔案。

Ref:
http://packaging.ubuntu.com/html/debian-dir-overview.html

results matching ""

    No results matching ""