wspkg - 工作站軟體清單與 meta-package 管理工具
==============================================
217 工作站實驗室 <217ta@csie.ntu.edu.tw>
我們系上的工作站使用了兩種以上的作業系統（目前是 Debian 和 FreeBSD），但是因為
不同系統安裝軟體的方法不同，且並非每個軟體都跨平臺，使得以往不同作業系統的軟體
清單不同步，累積了不少差異。
我們的主要目標是取代工作站上與平臺密切相關的軟體清單和手動生成的 meta-package。
藉由使用簡單且一致的純文字清單格式，我們能夠在僅使用系統內建的 shell、make
等基本指令和開發工具的前提下，為不同的平臺產生對應格式的 meta-package。
我們也非常歡迎大家把這個工具拿去用在自己管理的機器，或是其他工作站以外的地方。
快速操作說明
------------
下載原始碼
~~~~~~~~~~
如果您的系統上有安裝 https://git-scm.com/[Git]，請使用以下指令：
-----------------------------------------------------------------------------
git clone https://pkgbuild.csie.ntu.edu.tw/git/wspkg.git
git clone https://pkgbuild.csie.ntu.edu.tw/git/wspkg-data.git
-----------------------------------------------------------------------------
如果沒有，請從我們的 https://pkgbuild.csie.ntu.edu.tw/cgit[Git 網頁瀏覽界面]
點選想要下載的版本，從 download 連結下載壓縮檔。
編譯程式與文件
~~~~~~~~~~~~~~
雖然我們希望能盡可能只使用 shell 和系統內建的基本指令來完成工作，但是對於有些
較複雜的文字處理可能效能不如預期，因此仍有小部份是用 C 語言編寫來節省操作時間。
如果您只想要編譯程式，請切換至 `wspkg` 資料夾並執行：
-----------------------------------------------------------------------------
make ASCIIDOC=true PANDOC=true
-----------------------------------------------------------------------------
如果您想要編譯程式並產生文件，請先確定系統上有安裝
http://www.methods.co.nz/asciidoc/[AsciiDoc] 和 http://pandoc.org/[Pandoc]，
再切換至 `wspkg` 資料夾並執行：
-----------------------------------------------------------------------------
make
-----------------------------------------------------------------------------
使用軟體清單
~~~~~~~~~~~~
`wspkg-data` 資料夾中放置的是我們用在工作站的軟體清單，您可以直接使用它，也可以
自行修改，製作符合需求的清單。使用前我們必須將 `WSPKGDIR` 環境變數指到 `wspkg`
資料夾的絕對路徑：
-----------------------------------------------------------------------------
export WSPKGDIR="/path/to/downloaded/wspkg" # sh, bash, ksh, zsh
setenv WSPKGDIR "/path/to/downloaded/wspkg" # csh, tcsh
-----------------------------------------------------------------------------
接著我們就能使用 `wspkg-data` 中的 Makefile（副檔名為 mk），以下列出可用的功能：
|=========================================================================
| `make -f <list>.mk all` | 產生處理過的清單和 meta-package
| `make -f <list>.mk install` | 產生可用於安裝的套件庫
| `make -f <list>.mk clean` | 清除整個輸出目錄
| `make -f <list>.mk show` | 顯示所有重要變數的值
|=========================================================================
`<list>` 請自行替換成要使用的清單名稱，例如 `wslinux` 和 `wsbsd` 。我們也提供了
輔助用的 `build.sh` 工具，用於在執行 `make` 前檢查環境變數並提供適當的提示。
為了避免遇到難解的錯誤訊息，我們建議使用 `build.sh` 代替 `make` 。
執行 `./build.sh <list>` 和 `make -f <list>.mk` 的結果是相同的。
清單處理流程
------------
目前大致的流程
~~~~~~~~~~~~~~
以下以工作站使用的清單 `wslinux` 和 `wsbsd` 為例：
-----------------------------------------------------------------------------
+------------------------------------------------+
| 共用清單： wscommon.h |
| linux* 工作站套件對應表： wslinux/wslinux.pkg |
| bsd* 工作站套件對應表： wsbsd/wsbsd.pkg |
+------------------------------------------------+
|
| cpp (wspkg-sh/packages-cpp.sh)
v
+-----------------------------------------------------+
| linux* 工作站清單處理 script： wslinux/wslinux.sed |
| bsd* 工作站清單處理 script： wsbsd/wsbsd.sed |
+-----------------------------------------------------+
|
| sed
v
+-----------------------------------------------------+
| linux* 工作站套件清單： wslinux/out/wslinux.list |
| bsd* 工作站套件清單： wsbsd/out/wsbsd.list |
+-----------------------------------------------------+
/ \
debian/debian.mk / \ freebsd/freebsd.mk
內的規則 / \ 內的規則
/ \
+------------------------+ +-----------------------------+
| 供 linux* 工作站使用的 | | 供 bsd* 工作站使用的 |
| Debian meta-package | | FreeBSD meta-port Makefile |
+------------------------+ +-----------------------------+
-----------------------------------------------------------------------------
目前支援的平臺
~~~~~~~~~~~~~~
目前我們已經大致完成
link:wspkg-doc/debian.html[Debian (HTML)]
link:wspkg-doc/debian.pdf[Debian (PDF)] 與
link:wspkg-doc/freebsd.html[FreeBSD (HTML)]
link:wspkg-doc/freebsd.pdf[FreeBSD (PDF)]
的支援。為了避免 README 內容太多，所以我們將個別平臺的文件放到獨立的檔案中。
清單編寫方式
------------
基本設定
~~~~~~~~
每份清單，不論是否與其他清單共用檔案，都必須有自己的 Makefile。以下以 `wslinux`
為例說明 Makefile 中必須指定的變數。注意 `include` 指令非常重要，不可以任意改變
位置，也不可以省略，否則設定值可能會失效。
-----------------------------------------------------------------------------
# 五項必要的設定
NAME= wslinux # 清單的名稱
USE_MACRO= cpp # 指定處理 macro 的工具，目前只支援 cpp
WSPKG_IN_COMMON= wscommon.h # 共用清單檔名稱
BACKEND= debian # 指定輸出後端，例如 debian 和 freebsd
PKGNAME= 217-meta # 指定輸出套件的名稱
include $(WSPKGDIR)/wspkg-mk/defaults.mk
# 選擇性的其他設定
DEBIAN_SIGN= yes
DEBIAN_KEY_PKGSIGN= DF9831FA
include $(WSPKGDIR)/wspkg-mk/packages.mk
-----------------------------------------------------------------------------
填寫完成以後即可執行 `make show` 來查看目前各個變數的值。除了前五項必須寫在最
前面以外，其他的變數值如果想要修改，都必須放在兩行 `include` 指令的中間。
編寫共用清單
~~~~~~~~~~~~
共用清單是 macro 處理工具（例如 cpp）真正讀入的清單檔，這也代表著這個檔案必須
使用 macro 語言中的指令（例如 `#include` ）將不同平臺的套件對應表載入。這個檔
案的名稱是 Makefile 中的 `$(WSPKG_IN_COMMON)` 。我們繼續以 `wslinux` 為例說明
共用清單檔中必要的項目。
-----------------------------------------------------------------------------
// 載入對應目前平臺的套件對應表
#if (defined WSLINUX) // wspkg 會自動將清單名稱轉為大寫並定義同名的 macro
# include "wslinux/wslinux.pkg"
#elif (defined WSBSD) // 當另一份清單也使用這個共用清單時會定義不同的 macro
# include "wsbsd/wsbsd.pkg"
#endif
// 這些是在各平臺都使用相同名稱的套件
bash vim screen mutt lftp
// 這些是在各平臺名稱不同的套件
IMAGEMAGICK XSLTPROC PHP_CLI PANDOC MENUMAKER
-----------------------------------------------------------------------------
編寫套件對應表
~~~~~~~~~~~~~~
現在我們已經有一份可在不同平臺共用的套件清單，接著我們寫一份對應表，將各平臺
名稱不同的套件對應到真正可以使用的名稱。這個檔案的名稱是 Makefile 中的
`$(WSPKG_IN_PLATFORM_PKG)` 。
-----------------------------------------------------------------------------
#define IMAGEMAGICK imagemagick
#define XSLTPROC xsltproc
#define PHP_CLI php5-cli
#define PANDOC pandoc
#define MENUMAKER // 在這個平臺上找不到，但在其他平臺上有
-----------------------------------------------------------------------------
處理產生的清單
~~~~~~~~~~~~~~
有些時候我們可能會遇到一些突發狀況，例如某些套件暫時移出套件庫，或是暫時有相依
性無法滿足。這時候為了對特定平臺暫時刪除某些套件，我們可以寫一個 sed script。
這個檔案的名稱是 Makefile 中的 `$(WSPKG_IN_PLATFORM_SED)` 。
開發
----
基本原則
~~~~~~~~
. 用簡單易懂的格式。
. 一個 script 只做好一件事情。
. 除 `/bin/sh` 和 `/usr/bin/env` 外，不要使用絕對路徑。
. 用 shell script 寫大部分的小程式，用 Makefile 組合這些小程式。
. 只有在其他工具效能太差時，才考慮改用 C 或 C++ ，目前我們並不接受
Perl、Python、Ruby 這類未在 POSIX 規範內的語言。
可攜性要求
~~~~~~~~~~
因為軟體清單常常是用在剛安裝好，還缺少很多軟體的系統，所以我們希望使用這份清單
時，能盡量不依賴外部程式，以避免為了處理清單還需要安裝額外軟體的麻煩。原則上
我們接受使用多數 POSIX 標準內有規定的程式和語言。
我們認為以下軟體是我們可以依賴並假設一定會存在的：
. POSIX shell (`/bin/sh`) 與基本的系統指令。
. POSIX sed (`/usr/bin/sed`)
. POSIX awk (`/usr/bin/awk`)
. POSIX make (`/usr/bin/make`)，我們的 Makefile 不依賴 GNU 或 BSD make
專用的功能。
. POSIX standard C compiler (`/usr/bin/c99`)。
. C 和 C\++ 編譯器與前處理器，請用 `cc` 、 `cpp` 、 `c++` 這類通用的名稱，
不要使用 `gcc` 、 `g++` 或 `clang` 、 `clang++` 這類與特定編譯器實作
有關的名稱。雖然 `CC` 也可以代表 C++ 編譯器，但是因為和 `cc` 只有大小寫
的差別，容易造成誤會，所以也不要使用。
當然，如果您正在寫 `debian/*.sh` 或 `freebsd/*.sh` 這類只使用在特定平臺的
script，您可以使用只在特定平臺才有的程式。例如 `debian/*.sh` 內可以使用
`bash` 和 `perl` ，而 `freebsd/*.sh` 內可以使用 `csh` 和 `bsdtar` 。
但我們仍然建議盡量不要使用這些程式，以方便在不同的平臺測試與產生清單。
檔案用途說明
~~~~~~~~~~~~
- `wspkg-mk/*.mk` - 各平臺共用的 Makefile。
- `wspkg-sh/*.sh` - 各平臺共用的 shell script。
- `wspkg-doc/*.txt` - 與平臺相關的文件。
- `debian/*` - Debian 後端，由共用 Makefile 使用 `debian/debian.mk` 引入。
- `freebsd/*` - FreeBSD 後端，由共用 Makefile 使用 `freebsd/freebsd.mk` 引入。
待改進事項
~~~~~~~~~~
- 希望能有自動檢查是否有打錯字功能的方法。目前 FreeBSD 已經
透過搜尋 INDEX 檔案解決。Debian 這邊可藉由讀取產生的清單檔，
用 `apt-cache show` 檢查是否每個套件都存在，但是這項檢查工
作還沒寫成 script，必須手動執行。
- 希望能自動檢查目前的清單中是否有互相衝突的套件。如果可以的
話，也希望能有顯示完整相依清單的功能。目前 FreeBSD 是用
poudriere 打包 meta-package 結果是否成功來檢查衝突，但這過程
會花費超過一小時的時間，也會用掉大量硬碟空間。
- 對於像是 perl 與 python 這類的套件，各發行版常有固定的取名
方法，但我們目情仍然是全部手動列表，維護時有些麻煩。不過要
解決這問題，我們可能就不能再用 cpp 了，得改用較強的 macro
系統，例如 m4。但改用 m4 代表著維護者需要多學一種語言。
- 實作其他常見發行版的支援，像是 Fedora、Arch、Gentoo 之類的。
當然這就和工作站關係不大了，和拿去自行使用的使用者比較有關。
