更新說明文件

3 files changed, 223 insertions, 132 deletions

diff --git a/README.txt b/README.txt
index a179b43..b11df87 100644
--- a/README.txt
+++ b/README.txt
@@ -1,116 +1,198 @@
-wspkg - 用 cpp 管理工作站軟體清單
-=================================
+wspkg - 工作站軟體清單與 meta-package 管理工具
+==============================================
 217 工作站實驗室 <217ta@csie.ntu.edu.tw>
 
-wspkg 嘗試用簡單的工具，同時管理多個平臺的軟體清單，並製作 meta-package。
-我們的主要目標是替換掉工作站上原有與平臺相關、手動生成的 meta-package。
+我們系上的工作站使用了兩種以上的作業系統（目前是 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 Makefile.<platform> all`            | 產生 meta-package 和文件
-| `make -f Makefile.<platform> clean`          | 清除產生的套件檔
-| `make -f Makefile.<platform> clean-exe`      | 清除產生的可執行檔
-| `make -f Makefile.<platform> clean-doc`      | 清除產生的文件
-| `make -f Makefile.<platform> distclean`      | 清除所有產生的檔案
+| `make -f <list>.mk all`            | 產生處理過的清單和 meta-package
+| `make -f <list>.mk install`        | 產生可用於安裝的套件庫
+| `make -f <list>.mk clean`          | 清除整個輸出目錄
+| `make -f <list>.mk show`           | 顯示所有重要變數的值
 |=========================================================================
-`<platform>` 請自行替換成要使用的平臺名稱，例如 `debian` 或 `freebsd` 。
 
-目前簡單的架構
+`<list>` 請自行替換成要使用的清單名稱，例如 `wslinux` 和 `wsbsd` 。我們也提供了
+輔助用的 `build.sh` 工具，用於在執行 `make` 前檢查環境變數並提供適當的提示。
+
+為了避免遇到難解的錯誤訊息，我們建議使用 `build.sh` 代替 `make` 。
+執行 `./build.sh <list>` 和 `make -f <list>.mk` 的結果是相同的。
+
+
+清單處理流程
+------------
+
+目前大致的流程
 ~~~~~~~~~~~~~~
+以下以工作站使用的清單 `wslinux` 和 `wsbsd` 為例：
+
 -----------------------------------------------------------------------------
 
-           +--------------------------+
-           | 主要的清單與對應的對照表 |
-           |        packages.h        |
-           |        debian.pkg        |
-           |        freebsd.pkg       |
-           +--------------------------+
-                       |
-                       | cpp 與其他簡單的處理
-                       v
-           +--------------------------+
-           |     不同系統的軟體清單   |
-           |        debian.list       |
-           |        freebsd.list      |
-           +--------------------------+
-                    /     \
-                   /       \   轉換成各平臺所需格式的 script
-                  /         \
-  +---------------------+  +-----------------------------+
-  | Debian meta-package |  | FreeBSD meta-ports Makefile |
-  +---------------------+  +-----------------------------+
+           +------------------------------------------------+
+           | 共用清單：                 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:debian.doc/debian.html[Debian (HTML)]
-link:debian.doc/debian.pdf[Debian (PDF)] 與
-link:freebsd.doc/freebsd.html[FreeBSD (HTML)]
-link:freebsd.doc/freebsd.pdf[FreeBSD (PDF)]
-的支援。為了避免讓 README 內容太多導致重點太過混亂，所以我們將個別平臺的文件
-放到獨立的檔案中。
+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 內容太多，所以我們將個別平臺的文件放到獨立的檔案中。
 
 
-實作
-----
+清單編寫方式
+------------
 
-為什麼要做這個東西
-~~~~~~~~~~~~~~~~~~
-我們系上的工作站使用了兩種以上的作業系統（目前是 Debian 和 FreeBSD），但是因為
-不同系統安裝軟體的方法不同，且並非每個軟體都跨平臺，使得以往不同作業系統的軟體
-清單不同步，累積了不少差異。
-我們希望能藉由簡單的方法，讓不同作業系統的工作站上安裝的軟體能夠同步。當然，我
-們也希望這個軟體能用於管理其他系統，並不限於系上的工作站。
+基本設定
+~~~~~~~~
+每份清單，不論是否與其他清單共用檔案，都必須有自己的 Makefile。以下以 `wslinux`
+為例說明 Makefile 中必須指定的變數。注意 `include` 指令非常重要，不可以任意改變
+位置，也不可以省略，否則設定值可能會失效。
 
-如何達成這個目標
-~~~~~~~~~~~~~~~~
-產生一個簡單、已排序、不重複的清單，再藉由編寫 platform-dependent 的 script
-來產生各平臺的 meta-package。
+-----------------------------------------------------------------------------
+# 五項必要的設定
+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
+-----------------------------------------------------------------------------
 
- . 主要的軟體列表： `packages.h` ，由大家熟悉的 C 語言前處理器（cpp）指令組成。
-   如果軟體在各平臺的名稱相同，那麼就直接寫在這個檔案中；如果不同，那可以
-   定一個 macro，再到各平臺的對照表將這個 macro 對應到真正的軟體名稱。注意
-   這檔案有對軟體分類，新增或修改軟體清單時記得要寫在 `#ifdef` 和 `#endif` 中。
+填寫完成以後即可執行 `make show` 來查看目前各個變數的值。除了前五項必須寫在最
+前面以外，其他的變數值如果想要修改，都必須放在兩行 `include` 指令的中間。
 
- . 各平臺的對應表： `*.in/*.pkg` ，同樣由 cpp 指令組成。這個檔案中要定義（#define）
-   在 packages.h 中的使用的 macro 所對應的真正軟體名稱。一般情況下，這個檔
-   案中只會出現 #define 指令。
+編寫共用清單
+~~~~~~~~~~~~
+共用清單是 macro 處理工具（例如 cpp）真正讀入的清單檔，這也代表著這個檔案必須
+使用 macro 語言中的指令（例如 `#include` ）將不同平臺的套件對應表載入。這個檔
+案的名稱是 Makefile 中的 `$(WSPKG_IN_COMMON)` 。我們繼續以 `wslinux` 為例說明
+共用清單檔中必要的項目。
 
-現在可以執行 `make` 來產生 meta-package 了！
+-----------------------------------------------------------------------------
+// 載入對應目前平臺的套件對應表
+#if   (defined WSLINUX)  // wspkg 會自動將清單名稱轉為大寫並定義同名的 macro
+# include "wslinux/wslinux.pkg"
+#elif (defined WSBSD)    // 當另一份清單也使用這個共用清單時會定義不同的 macro
+# include "wsbsd/wsbsd.pkg"
+#endif
 
-各個目錄與檔案的用途
-~~~~~~~~~~~~~~~~~~~~
+// 這些是在各平臺都使用相同名稱的套件
+bash            vim             screen          mutt            lftp
 
-主要的檔案和目錄
-^^^^^^^^^^^^^^^^
- - `packages.h` - 主要的軟體列表，可說是最重要的資料檔。
- - `*.doc` - 放置與平臺相關的文件。
- - `*.in` - 放置與平臺相關的輸入檔案。
- - `*.out` - 放置與平臺相關的輸出檔案。
- - `*.files` - 放置與平臺相關，但產生 meta-package 過程中用不到的檔案。
-   這裡可以放各種準備環境用的檔案。
+// 這些是在各平臺名稱不同的套件
+IMAGEMAGICK     XSLTPROC        PHP_CLI         PANDOC          MENUMAKER
+-----------------------------------------------------------------------------
 
-一些重要的資料檔
-^^^^^^^^^^^^^^^^
- - `*.in/*.pkg` - 各平臺套件名稱不同時使用的對照表。
- - `*.in/*.sed` - 臨時修改套件清單用的 sed 指令檔，通常用於暫時刪除目前無法使用
-   但以後仍然可能用到的套件。
- - `*.out/*.list` - 輸出的已排序而不重複的套件清單。
+編寫套件對應表
+~~~~~~~~~~~~~~
+現在我們已經有一份可在不同平臺共用的套件清單，接著我們寫一份對應表，將各平臺
+名稱不同的套件對應到真正可以使用的名稱。這個檔案的名稱是 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)` 。
 
 
 開發
@@ -119,10 +201,11 @@ link:freebsd.doc/freebsd.pdf[FreeBSD (PDF)]
 基本原則
 ~~~~~~~~
  . 用簡單易懂的格式。
- . 一個小程式只做好一件事情。
+ . 一個 script 只做好一件事情。
  . 除 `/bin/sh` 和 `/usr/bin/env` 外，不要使用絕對路徑。
  . 用 shell script 寫大部分的小程式，用 Makefile 組合這些小程式。
- . 只有在其他工具效能太差時，才考慮改用 C / C++ 。
+ . 只有在其他工具效能太差時，才考慮改用 C 或 C++ ，目前我們並不接受
+   Perl、Python、Ruby 這類未在 POSIX 規範內的語言。
 
 可攜性要求
 ~~~~~~~~~~
@@ -135,32 +218,40 @@ link:freebsd.doc/freebsd.pdf[FreeBSD (PDF)]
  . POSIX shell (`/bin/sh`) 與基本的系統指令。
  . POSIX sed (`/usr/bin/sed`)
  . POSIX awk (`/usr/bin/awk`)
- . POSIX make (`/usr/bin/make`)，我們的 Makefile 不依賴 GNU 或 BSD make 提供的。
+ . 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` 。
+ . 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 這邊還沒實作。
+   透過搜尋 INDEX 檔案解決。Debian 這邊可藉由讀取產生的清單檔，
+   用 `apt-cache show` 檢查是否每個套件都存在，但是這項檢查工
+   作還沒寫成 script，必須手動執行。
  - 希望能自動檢查目前的清單中是否有互相衝突的套件。如果可以的
-   化，也希望能有顯示完整相依清單的功能。
+   話，也希望能有顯示完整相依清單的功能。目前 FreeBSD 是用
+   poudriere 打包 meta-package 結果是否成功來檢查衝突，但這過程
+   會花費超過一小時的時間，也會用掉大量硬碟空間。
  - 對於像是 perl 與 python 這類的套件，各發行版常有固定的取名
    方法，但我們目情仍然是全部手動列表，維護時有些麻煩。不過要
    解決這問題，我們可能就不能再用 cpp 了，得改用較強的 macro
    系統，例如 m4。但改用 m4 代表著維護者需要多學一種語言。
- - 網頁檢視、瀏覽支援。可能可以整合
-   link:http://esystem.csie.ntu.edu.tw/[CSIE Esystem]
-   並利用 SSO 功能讓擁有系上帳號的人可以評論或要求加入新套件。
- - 我們希望可以在完全不影響 wspkg 的 source tree 的情況下使用
-   其他與工作站無關、自行維護的清單。
  - 實作其他常見發行版的支援，像是 Fedora、Arch、Gentoo 之類的。
    當然這就和工作站關係不大了，和拿去自行使用的使用者比較有關。
diff --git a/wspkg-doc/debian.txt b/wspkg-doc/debian.txt
index 43ac595..1e8d5bc 100644
--- a/wspkg-doc/debian.txt
+++ b/wspkg-doc/debian.txt
@@ -3,25 +3,25 @@ wspkg - Debian 支援：dpkg 與 apt
 217 工作站實驗室 <217ta@csie.ntu.edu.tw>
 
 -------------------------------------------------------------------------------
-
-  +---------------------+
-  | Debian package list |
-  |     debian.list     |-+
-  +---------------------+ | debian.control.sh    +-------------------+
-                          +------------------>>>>| dpkg control file |
-+-----------------------+ |                      |   debian.control  |
-| dpkg control template |-+                      +-------------------+
-|   debian.control.in   |
-+-----------------------+
-
+  +------------------------+
+  |   Debian package list  |
+  | <list>/out/<list>.list |--+ debian/debian.mk
+  +------------------------+  | debian/debian.deps.sh
+                              +------------------------+
+ +--------------------------+ |                        |
+ |  dpkg control template   |-+                        v
+ | <list>/<list>.control.in |                +---------------------------+
+ +--------------------------+                |     dpkg control file     |
+                                             | <list>/out/<list>.control |
+                                             +---------------------------+
 -------------------------------------------------------------------------------
 
 產生 dpkg control 檔案
 ----------------------
 由於 dpkg control 檔案有很多欄位，如果全部用 script 產生，那麼 script 會很亂。
-所以我們改為編寫一個簡單的 template 檔案，即 debian.control.in，再由簡單的
-script 將 template 檔案中的空格，依照 debian.list 中的列表填上，產生真正的
-dpkg control 檔案，即 debian.control。
+所以我們改為編寫一個簡單的 template 檔案，即 debian.control.in，再使用 sed 將
+template 檔案中的空格填入對應的值。其中 `@DEPS@` 會替換清單中指定的所有套件，
+由於格式較為複雜，這樣功能獨立放在 debian.deps.sh 中。
 
 產生 meta-package
 -----------------
diff --git a/wspkg-doc/freebsd.txt b/wspkg-doc/freebsd.txt
index d98c8b3..953ebda 100644
--- a/wspkg-doc/freebsd.txt
+++ b/wspkg-doc/freebsd.txt
@@ -3,24 +3,24 @@ wspkg - FreeBSD 支援：ports 與 pkgng
 217 工作站實驗室 <217ta@csie.ntu.edu.tw>
 
 -------------------------------------------------------------------------------
-  +----------------------+
-  | FreeBSD package list |
-  |    freebsd.list      |
-  +----------------------+
-            | freebsd.ports.sh
-            | freebsd.ports.find
+  +------------------------+
+  |  FreeBSD package list  |
+  | <list>/out/<list>.list |
+  +------------------------+
+            | freebsd/freebsd.ports.sh
+            | freebsd/freebsd.ports.find
             v
-  +---------------------+
-  | FreeBSD ports list  |
-  |    freebsd.ports    |-+
-  +---------------------+ |  freebsd.makefile.sh    +------------------------+
-                          +--------------------->>>>| FreeBSD ports Makefile |
-                          |                         |    freebsd.makefile    |
-+-------------------------+-------+                 +------------------------+
-| FreeBSD ports Makefile template |
-|       freebsd.makefile.in       |
-+---------------------------------+
-
+  +-------------------------+
+  |   FreeBSD ports list    |
+  | <list>/out/<list>.ports +--+ freebsd/freebsd.mk
+  +-------------------------+  | freebsd/freebsd.deps.sh
+                          +------------------------------+
+                          |                              |
++-------------------------+------+                       v
+| FreeBSD port Makefile template |             +----------------------------+
+|   <list>/<list>.makefile.in    |             |   FreeBSD port Makefile    |
++--------------------------------+             | <list>/out/<list>.makefile |
+                                               +----------------------------+
 -------------------------------------------------------------------------------
 
 產生 ports 目錄清單
@@ -29,6 +29,6 @@ wspkg - FreeBSD 支援：ports 與 pkgng
 所在的目錄。freebsd.ports.sh 會幫忙找到系統的 ports tree 及 index file，再執行
 freebsd.ports.find 從 index file 產生清單。
 
-產生 meta-ports Makefile
-------------------------
+產生 meta-port Makefile
+-----------------------
 freebsd.makefile.sh 會根據 template 填上版本號以及 RUN_DEPENDS 以產生 Makefile。