mool

portupgrade是提供由ports/packages來升級/安裝新軟件的功能的工具，portinstall等價於portupgrade –N。
在閱讀該說明書之前，請務必理解每個port/package都有兩種不同類型的ports/packages：
required（必需的）：一個port/package構成、運行所必須的ports/packages，在Makefiles中分別以宏 BUILD_DEPENDS 和RUN_DEPENDS指定。
dependent（依賴的）：一個port/package需要的ports/packages。
警告：
o  請仔細閱讀本手冊並了解你用portupgrade要做什麼。
o  建議先執行pkgdb –F，一次升級大量的有不一致的package數據庫的packages必然會導致壞的結果。o  portupgrade允許你不重新編譯、安裝依賴的packages，因此可能會導致二進制的兼容問題，必要時別忘了使用-f、-r 、-R 參數。o  當portupgrade執行中請勿中斷，否則你將得到一個修改了一部分、不完整的package數據庫，即使你什麼也沒做錯，package數據庫也可能被破壞，這個時候你需要執行pkgdb –fu重建數據庫，把它從coredumping中營救回來。
o  切勿偷懶，務必備份先前的數據及配置文檔，包括在/var/db/pkg 的package數據庫。
 
參數：
portupgrade支持以下參數：
pkgname_glob
定義一個pkgname，支持通配符（名字是pkg_info顯示的內容，不帶版本號）。更進一步的細節參看pkg_glob(1)。。
－h
--help顯示幫助選項
－a
--all   
升級所有已安裝的過時的ports，相當於pkgname_glob中的*
-A CMD
--afterinstall CMD
在每次安裝以後以root身份執行CMD代替的命令
-b
--backup-packages       
備份老版本的ports，這些數據會暫存於PKG_TMPDIR 及 TMPDIR定義的位置。
-B CMD
--beforebuild CMD
在每次安裝之前執行CMD代替的命令，如果命令執行失敗，則跳過該安裝。
下面是一些典型應用：
portupgrade -B 'cvs update' 'gnome*'
portupgrade -B 'ports_glob -M $(pwd) | (cd ../..; xargs cvs up)' slave/port
portupgrade -aB 'test ! `make –V IS_INTERACTIVE`'
-c
--clean
每次編譯前執行make clean，這是默認值，參看下面的-w選項。
-C
--cleanup
每次安裝後執行make clean，這是默認值，參看下面的-W選項。
-D
--distclean如果checksum失敗就刪除錯誤的文件並重試。在每次fetch或是build之前執行 make distclean。
-f
--force
強制執行，即使是降級或同一版本，或者用戶在pkgtools.conf裡面用HOLD_PKGS指定保留的。
-F
--fetch-only
僅僅獲取文件或packages（如果指定了-P選項），而不做upgrade、install等操作。該參數對於一次取得所有需要的文件很有用。
默認情況下，當一個port/package安裝失敗的話，依賴於它的ports/packages將被忽略。
-i
--interactive
打開互動模式，在進行安裝或升級前會徵求你的同意。該選項包含了-v選項。
-k
--keep-going
即使某些依賴的package更新失敗也繼續執行。
-l FILE
--results-file FILE  
將更新結果以FILE文件名保存，默認情況下portupgrade是不保存的。
-L FORMAT
--log-file FORMAT
為每個port保存一個記錄文件，格式為printf(3)中規定的，如果FORMAT中沒有包含一個%，則默認是%s::%s，類別和port名字作為變量。
-m
--make-args
在每次make(1)命令後加額外的參數。
-M
--make-env
在每次make(1)命令前加額外的參數。
-n
--noexecute
不實際執行安裝或升級動作，只顯示會有何變化。該選項包含了-v，否定-i和-y。
-N
--new
當指定的package沒有安裝的情況下，安裝一個新的port/package，它所依賴的ports/packages也一起安裝/升級。
如果該選項被指定，可以像pkgname glob 參數一樣定義一個portorigin glob來說明要安裝哪個port，更多信息參看portsdb(1)。
-o ORIGIN
--origin ORIGIN
定義一個port在某個package之後升級。
-O
--omit-check
忽略依賴性檢測，默認情況下，portupgrade會花費大量的時間去計算所有packages的依賴性關係。如果之前已經執行了pkgdb –F，那麼可以用該參數來忽略它。-p
--package
每個指定的port都安裝/升級以後建立一個package，如果在命令行指定了它依賴的包（包括指定了-r選項的情況），也為它們建立package。 -P
-use-packages  
使用預編譯的 package 而不是 ports 來進行安裝， 首先搜索 PKG_PATH 中指定的本地目錄，如果沒有找到，則調用pkg_fetch(1)從遠程站點下載。如果本地沒有找到，而且遠程站點也沒有成功地下載預編譯包，則使用 ports。
-PP
--use-packages-only  
即使在本地目錄和遠程站點上都找不到也不用port方式。此時仍然需要保持ports tree到最新的。
-q
--noconfig
不去讀取配置文件：$PREFIX/etc/pkgtools.conf
-r
--recursive
升級所有依賴該package的packages
-R
--upward-recursive
升級所有該package依賴的packages。如果同時指定了-F，將遞歸的下載所有的packages，包括全新未安裝過的packages，然後卸載升級這些port時需要的ports。
-s
--sudo
需要的時候以sudo(8)狀態執行命令
S CMD
--sudo-command CMD     為sudo指定一個可選的命令，例如：'su root -c %s '默認情況下是sudo-u--uninstall-shlibs     不保留舊的共享庫，默認情況下為了安全portupgrade保留舊的共享庫，更多細節參看pkg_deinstall(1) 幫助頁中的-P選項。
-v
--verbose
開啟verbose輸出。
-w
--noclean
每次編譯前不做make clean操作，參看上面的-c選項。
-W
--nocleanup
每次安裝後不做make clean操作，參看上面的-C選項。
-x GLOB
--exclude GLOB
將符合glob樣式的packages排除在外，在響應-r或-R時生效。例如升級所有依賴於Xfree86的除了Xfree86之外的 packages：portupgrade -rx XFree86 XFree86
-y
--yes
對所有問題都回答yes。該選項包含了-v，否定-n。
 
技術細節
portuupgrade可以通過ports或packages升級已經安裝過的packages，不需要重新安裝必需或依賴的packages。
下面是portupgrade的工作流程：1：如果沒有指定-P選項，跳到4；否則搜索 PKG_PATH 中指定的本地目錄中十分有更新的package tarball，如果找到，跳到5。
2：通過pkg_fetch(1)從遠程站點下載最新的包，如果下載的是最新的包，跳到5；如果-P出現兩次（例如-PP）並且下載的包雖然不是最新的但比本機的新，跳到5。
3：如果-P出現兩次（例如-PP），任務結束。
4：編譯指定的已安裝包響應的port。
5：更新那些依賴於指定包的packages的依賴信息（個人理解為版本等信息）。
6：通過pkg_create(1).備份命令中指定包當前的版本。注意如果是像XFree86這樣的大妖怪，備份的包會很大，請確定有足夠的空間（查看環境變量ENVIRONMENT就知道在哪了）來保存它，也許不久的將來會有個新的選項來忽略這個操作。
7：備份命令中指定的包當前安裝的版本註冊的文件（個人理解為那些配置文件）。
8：強制卸載命令中指定的包，保存共享庫除非-u選項被指定。
9：根據1、2、3步驟決定的方式通過ports或package來安裝新版本。
10：如果安裝失敗：
10.1恢復在步驟6里面備份的包    10.2恢復在步驟7里面備份的註冊文件
10.3恢復在步驟5里面的包依賴信息
11：刪除舊的依賴信息
12：運行portsclean –L刪除重複的依賴信息數據庫，備份老的數據庫。
13：運行pkgdb –aF更新舊的依賴信息，重建+REQUIRED_BY文件。
 
例子
o 升級glib:portupgrade glib
如你所見，可以忽略版本號。如果安裝了多個版本，則所有的都將被更新，除非他們共享一個port源（大概有如下兩種情況，見下），例如你可能有foo- 1.02和foo-1.03兩個版本的軟件，這個時候需要先運行pkgdb –F。例子一：一個用ports安裝，一個是源代碼編譯安裝的，這個時候portupgrade會提示是否卸載那個編譯安裝的。
例子二：隨著時間的演進，不同時間安裝的軟體會有不同版本的釋出，而且不同軟體相依的版本號也不同，所以往往會造成同一個軟體安裝過多版本的情形發生。這裡我必須聲明的是，雖然套件名稱相同，可是可能沒辦法上下兼容，因此造成有些軟體必須依賴比較舊的版本，而有些軟體必須依賴比較新的版本，如果有這種情形發生的話，那麼二個版本的存在是正常的。
Q：portsupgrade過程中,對於"共享同一ports源" 應該將所有不同版本都升級為統一版本.那麼"不同ports源"是,他怎麼去判斷是否要升級?不太理解了.
A：我的理解：不同port源的東東可以認為是兩個東西，所以portupgrade的時候可能只跟某一個有關聯，另外一個只不過也叫那個名字而已。
 
o升級Xfree86和Mesa，並且以-DWANT_GGI來編譯Mesa：portupgrade XFree86 -m '-DWANT_GGI' Mesa
當portupgrade處理多個包的時候，會自動地按依賴順序挑選packages。
-m / --make-args是指定的傳遞給make(1)的選項。
 
O 升級所有GNOME的packages，並將build日誌記錄在文件：/var/tmp/portupgrade- _category_::_portname_.log中portupgrade -L /var/tmp/portupgrade-%s::%s.log '*gnome*'
既可以如同sh(1)那樣使用通配符，也可以使用perl的擴展正則表達式。擴展正則表達式的使用方法是在表達式之前加":"，上面的例子可以寫成這樣：:gnome。
-L / --log-prefix是告訴portupgrade為每個port保存一個記錄文件，不管是否有這個選項，portupgrade都會觀察每個 port的build過程，當某個失敗的時候會分析產生的原因。
 
O採用verbose模式升級sawfish和它所依賴的packages，升級之後建立binary packages。
portupgrade -Rpv sawfish-R / --upward-recursive告訴portupgrade根據依賴信息遞歸的升級所有依賴的packages。在上面的例子中，rep-gtk, librep,imlib, gnomelibs, XFree86等都會被升級。
-p / --package告訴portupgrade升級以後建立個package。
-v / --verbose是開啟verbose輸出的選項。
 
O升級glib和依賴與它的packages，每個upgrade都會要求確認。portupgrade -ri glib
-r / --recursive升級所有依賴該package的packages，在上例中，gtk和所有GNOME有關的packages都會被升級。
-i / --interactive告訴portupgrade在進行操作前徵求你的同意。
 
O重新編譯、安裝所有依賴與sdl的ports，但sdl除外portupgrade -rfx sdl sdl
-f / --force即使根據版本比較不需要升級也強制執行。
-x / --exclude指定了排除需要符合的模式。
 
O重新編譯、安裝在2001-09-20之前安裝的ports
portupgrade -f '<2001-09-20'
還可以選擇一個時間範圍。
 
O重新編譯、安裝依賴與png且安裝在它之前的packages
portupgrade -fr png -x '>=png'
你可以選擇一個package去指定時間。
 
O立即下載升級所有已安裝packages所需的文件，但是並不執行升級操作。
portupgrade -aFR
-a / --all等於指定了*
-F / --fetch告訴portupgrade僅獲取文件，而不做upgrade操作。
除了-a之外，指定-R選項是很有必要的，因為有些被upgrade的ports會需要一些新的未曾安裝過的ports。
 
O用ghostscript-afpl替換ghostscript-gnu
portupgrade -o print/ghostscript-afpl ghostscript-gnu
-o / --origin最初是用在那些FreeBSD4.2之前的缺少了源的過時package，這個例子顯示了另外一種有用的功能，像這樣用，可以讓那些依賴與老的package（ghostscript-gnu）替換為新的package（ghostscript-afpl），不會有任何的問題。
 
O採用packages方式升級glib，如有必要，從遠程ftp站點上下載。
portupgrade -P glib
-P / --use-packages告訴portupgrade使用 packages 而不是 ports。
 
O用光盤裡的packages升級大量的程序，但在這之前，我們先看看什麼會有變化：
env PKG_PATH=/mnt/cdrom/packages/All portupgrade -anPP
-n / --noexecute告訴portupgrade不實際執行安裝或升級動作，只顯示會有何變化。
兩個-P告訴portupgrade只用packages方式；如果升級它需要的packages（*.tgz）找不到就不升級。
如果你不想portupgrade在光盤上找不到文件就去下載的話，把PKG_FETCH設置為/bin/false。
 
小技巧
 
O執行完升級操作以後，強烈建議執行pkgdb –F修復由新裝的packages引起的被破壞的依賴性。
O大量升級時使用：
portupgrade -aPPR
O有疑惑的時候，使用portupgrade的-n和-i選項看看會產生什麼效果，或者使用pkg_glob(1)來看它是如何擴展patter的。
O 為了有效且正確的升級，請在必要時執行pkgdb –F以保持它們的依賴性關係。每次cvsup更新完ports以後要執行portsdb –Uu來更新ports INDEX資料庫。O可以嘗試用portversion(1)代替pkg_version(1)來確定是否可以升級，它和pkg_version使用方法大同小異，但速度要快。類似的，portversion –c也是利用portupgrade來升級。
O可以嘗試用pkg_deinstall(1)來代替pkg_delete(1)來卸載packages，它在pkg_delete基礎上增加了可遞歸的反安裝及共享庫的保存功能。
O要清理沒用的文件及編譯中的臨時文件、舊的共享庫，請使用portsclean(1)。
O要跟蹤一個port的變化過程，請使用portcvsweb(1)。
 
環境變量
 
PKG_DBDIR    已安裝的package的數據庫的位置，默認是/var/db/pkg
PORTSDIR         ports樹的位置，默認是/usr/ports
PORTS_INDEX         ports INDEX的位置，默認是$PORTSDIR/INDEXPORTS_DBDIR         ports數據庫的位置，默認是$PORTSDIRPKG_TMPDIR
TMPDIR            portupgrade更新的時候備份文件的臨時目錄，如果沒有設置的話使用/var/tmp，注意這個目錄必須要有足夠的空間，尤其是在更新一個大的 package時，參見上面的技術細節章節。
PACKAGES         portupgrade建立packages的基礎目錄，默認是$PORTSDIR/packages
PKG_PATH         portupgrade查詢packages的目錄列表，以冒號分割，默認是$PACKAGES/All
PKG_SUFX         packages的後綴，默認是在bsd.port.mk 或 /etc/make.conf中定義的
PKGTOOLS_CONF       pkgtools的配置文件，默認是$PREFIX/etc/pkgtools.conf
PORTUPGRADE         portupgrade的默認選項（例如-v）
 
文件
 /var/tmp  創建備份文件的臨時目錄，如果環境變量PKG_TMPDIR 或者TMPDIR沒有指向一個合適的目錄。/var/db/pkg          默認的已安裝的package的數據庫的位置
/usr/ports            默認的ports樹和ports數據庫的位置
$PREFIX/etc/pkgtools.conf      默認的pkgtools的配置文件
 
其他相關
      pkg_add(1), pkg_deinstall(1), pkg_delete(1), pkg_glob(1), pkg_info(1),     pkg_sort(1), pkg_update(1), pkgdb(1), portcvsweb(1), ports_glob(1),     portsclean(1), portsdb(1), portversion(1), pkgtools.conf(5), ports(7)
 
作者
 
Akinori MUSHA <knu@iDaemons.org>
 
Bugs
 
在編譯/安裝的時候快捷鍵Ctrl+z不起作用。
 
有時數據庫會損壞，pkgtools命令因為segmentation fault錯誤而中斷，運行pkgdb –fu重建數據庫將解決此問題。
 
一些第三方或自己編譯的packages會有不合法的package名字令portupgrade和相關工具惱怒異常，要將它們隱藏，在它們的目錄下建一個名字叫+IGNOREME的文件（使用touch(1)）。