撰寫 R 擴充套件 ¶

1.1.1 DESCRIPTION 檔案 ¶

DESCRIPTION 檔案包含下列格式的套件基本資訊

Package: pkgname Version: 0.5-1 Date: 2015-01-01 Title: My First Collection of Functions Authors@R: c(person("Joe", "Developer", role = c("aut", "cre"), email = "Joe.Developer@some.domain.net"), person("Pat", "Developer", role = "aut"), person("A.", "User", role = "ctb", email = "A.User@whereever.net")) Author: Joe Developer [aut, cre], Pat Developer [aut], A. User [ctb] Maintainer: Joe Developer <Joe.Developer@some.domain.net> Depends: R (>= 3.1.0), nlme Suggests: MASS Description: A (one paragraph) description of what the package does and why it may be useful. License: GPL (>= 2) URL: https://www.r-project.org, http://www.another.url BugReports: https://pkgname.bugtracker.url

格式為「Debian 控制檔案」版本（請參閱「read.dcf」和 https://www.debian.org/doc/debian-policy/ch-controlfields.html 的說明：R 不需要 UTF-8 編碼，也不支援以「#」開頭的註解）。欄位以 ASCII 名稱開頭，後接冒號：值從冒號和空格後開始。換行（例如，用於長度超過一行的描述）以空格或標籤開頭。欄位名稱區分大小寫：R 使用的所有欄位名稱均為大寫。

為了最大化可攜性，DESCRIPTION 檔案應完全以 ASCII 編寫，如果無法做到，則必須包含「編碼」欄位（請見下方）。

數個選用欄位採用 邏輯值：這些值可以指定為「yes」、「true」、「no」或「false」：大寫值也可以接受。

「套件」、「版本」、「授權」、「說明」、「標題」、「作者」和「維護者」欄位為強制欄位，所有其他欄位為選用欄位。「作者」和「維護者」欄位可以從「Authors@R」自動產生，如果提供了後者，則可以省略：但是，如果它們不是 ASCII，我們建議提供它們。

強制欄位「套件」提供套件名稱。這應僅包含 (ASCII) 字母、數字和句點，至少有兩個字元，且以字母開頭，不以句點結尾。如果需要說明，應在「說明」欄位（而非「標題」欄位）中說明。

強制欄位「版本」提供套件版本。這是一系列至少 兩個（通常為三個）非負整數，由單一的「.」或「-」字元分隔。正規形式如範例所示，而「0.01」或「0.01.0」等版本將會被視為「0.1-0」。這 不是小數，因此，例如 0.9 < 0.75，因為 9 < 75。

強制欄位「授權」將在下一小節中討論。

必填的「標題」欄位應提供套件的簡短說明。有些套件清單可能會將標題截斷為 65 個字元。它應使用標題大小寫（亦即，將主要字詞大寫：tools::toTitleCase 可以協助您執行此操作），不使用任何標記，沒有任何延續行，且不以句點結尾（除非是 … 的一部分）。請勿重複套件名稱：它通常會使用名稱為前綴。請使用單引號來指稱其他套件和外部軟體，並使用雙引號來指稱書籍標題（和類似標題）。

必填的「說明」欄位應提供套件功能的完整說明。可以使用多個（完整的）句子，但只能有一個段落。所有預期的讀者群都應能理解（例如，對於 CRAN 套件，所有 CRAN 使用者都應能理解）。良好的做法是不以套件名稱、「此套件」或類似字詞開頭。與「標題」欄位一樣，應使用雙引號來表示引文（包括書籍和文章標題），並使用單引號來表示非英文用法，包括其他套件和外部軟體的名稱。必要時，此欄位也應說明套件名稱。網址應以尖括號括起來，例如「<https://www.r-project.org>」：另請參閱指定網址。

必填的「作者」欄位說明撰寫套件的人員。它是一個純文字欄位，供人類讀者閱讀，但不用於自動處理（例如，萃取所有列出貢獻者的電子郵件地址：請使用「Authors@R」）。請注意，所有重要的貢獻者都必須納入：如果您為包含在 src 目錄中的其他人的作品撰寫 R 封裝程式，您並非唯一的（甚至可能不是主要的）作者。

強制性的「維護者」欄位應提供一個單一名稱，後接一個以尖括號括住的有效（RFC 2822）電子郵件地址。它不應以句點或逗號結尾。此欄位是maintainer函數所回報的，並由bug.report使用。對於CRAN套件，它應為個人，而非郵件清單或公司實體：請確保它有效且在套件的生命週期內保持有效。

請注意，如果顯示名稱（尖括號中地址之前的部分）包含逗號或句點等非字母數字字元，則應以雙引號括住。（目前的標準 RFC 5322 允許句點，但 RFC 2822 沒有。）

如果提供了適當的「Authors@R」欄位，則「Author」和「Maintainer」欄位都可以省略。這個欄位可以用來提供套件「作者」的精緻且機器可讀的描述（特別是明確指定其精確的角色），透過適當的 R 程式碼。它應該透過呼叫 person 或一系列呼叫（每個「作者」一個）再串接 c() 來建立類別 "person" 的物件：請參閱上述範例 DESCRIPTION 檔案。角色可以包括「"aut"」（作者）表示完整作者、「"cre"」（建立者）表示套件維護者、「"ctb"」（貢獻者）表示其他貢獻者、「"cph"」（版權持有者，應該是機構或法人團體的合法名稱）等。請參閱 ?person 以取得更多資訊。請注意，預設不會假設任何角色。自動產生的套件引文資訊會利用這個規格。在建置⁵或安裝時，如果需要，會從中自動產生「Author」和「Maintainer」欄位。

如果版權持有者不是作者，可以使用選用的「Copyright」欄位。如果需要，這可以參照已安裝的檔案：慣例是使用檔案 inst/COPYRIGHTS。

選用的「日期」欄位提供套件目前版本的發行日期。強烈建議⁶使用符合 ISO 8601 標準的「yyyy-mm-dd」格式。

「依賴」、「匯入」、「建議」、「加強」、「連結至」和「其他儲存庫」欄位會在後面的子區段中討論。

R 系統外部的依賴項應列在「系統需求」欄位中，並可能在獨立的 README 檔案中擴充說明。這包括指定非預設的 C++ 標準和需要 GNU make。

「網址」欄位可以提供一個 網址 清單，這些 網址 以逗號或空白分隔，例如作者的首頁或可以找到描述軟體的其他資訊的頁面。這些 網址 會轉換成 CRAN 套件清單中的主動超連結。請參閱 指定網址。

「錯誤回報」欄位可以包含一個 網址，用於提交有關套件的錯誤回報。這個 網址 將會由 bug.report 使用，而不是傳送電子郵件給維護人員。瀏覽器會開啟「http://」或「https://」網址。若要指定另一個電子郵件地址來接收錯誤回報，請改用「聯絡」：不過，bug.report 會嘗試從「錯誤回報」中擷取電子郵件地址（最好從「mailto:」網址或包含在尖括號中）。

基本和建議套件（即包含在 R 原始碼發行版中或可從 CRAN 取得，並建議包含在 R 的每個二進位發行版中的套件）有一個「優先順序」欄位，其值分別為「基本」或「建議」。其他套件不得使用這些優先順序。

當 R 程式碼檔案在套件安裝時進行處理時，可以使用「Collate」欄位來控制這些檔案的排序順序。預設會根據「C」地區設定進行排序。如果存在，排序規格必須列出套件中所有 R 程式碼檔案（考量到可能存在的作業系統特定子目錄，請參閱套件子目錄）作為相對於 R 子目錄的檔案路徑清單，清單中的項目以空白分隔。包含空白或引號的路徑需要加上引號。作業系統特定的排序欄位（「Collate.unix」或「Collate.windows」）會優先於「Collate」使用。

「LazyData」邏輯欄位控制 R 資料集是否使用延遲載入。在 2.14.0 之前的版本中使用「LazyLoad」欄位，但現在已忽略此欄位。

「KeepSource」邏輯欄位控制套件程式碼是否使用 keep.source = TRUE 或 FALSE 進行來源處理：對於專門設計為始終與 keep.source = TRUE 搭配使用的套件，可能需要例外地使用此欄位。

「ByteCompile」邏輯欄位控制套件 R 程式碼是否在安裝時進行位元組編譯：預設會進行位元組編譯。這可以使用旗標 --no-byte-compile 安裝來覆寫。

「UseLTO」邏輯欄位用於指出套件中的原始程式碼⁷是否要使用連結時間最佳化進行編譯（請參閱使用連結時間最佳化），前提是 R 已使用 --enable-lto（預設為 true）或 --enable-lto=R（預設為 false）安裝（或是在 Windows 上，如果 LTO_OPT 已在 MkRules 中設定）。這可以使用旗標 --use-LTO 和 --no-use-LTO 覆寫。據說 LTO 可以為大型且複雜（大量使用範本）的 C++ 專案提供最大的大小和效能改善。

「StagedInstall」邏輯欄位控制套件安裝是否為「分階段」，也就是安裝到暫時位置，並在成功完成後移到最終位置。此欄位在 R 3.6.0 中引入，且預設為 true：它被視為一項暫時措施，可能會在未來取消。

「ZipData」邏輯欄位自 R 2.13.0 起已被忽略。

「Biarch」邏輯欄位用於 Windows，以選取此套件的 INSTALL 選項 --force-biarch。

「BuildVignettes」邏輯欄位可以設定為 false 值，以停止 R CMD build 嘗試建置範例，並防止⁸ R CMD check 測試此範例。這只應在特殊情況下使用，例如 PDF 包含不屬於套件來源的大型圖形（因此僅限於沒有開放原始碼授權的套件）。

「VignetteBuilder」欄位名稱（以逗號分隔的清單）提供用於建立小插圖的引擎套件。這些套件可能包含目前的套件，或列於「Depends」、「Suggests」或「Imports」中的套件。utils 套件始終會隱含附加。有關詳細資訊，請參閱非 Sweave 小插圖。請注意，例如，如果小插圖的引擎為「knitr::rmarkdown」，則knitr 提供引擎，但使用它需要 knitr 和 rmarkdown，因此這兩個套件都需要在「VignetteBuilder」欄位中，且至少建議使用（因為 rmarkdown 僅由 knitr 建議使用，因此不會自動隨附）。許多使用 knitr 的套件也需要套件 formatR，它建議使用，因此使用者套件也需要這樣做，並將其包含在「VignetteBuilder」中。

如果 DESCRIPTION 檔案並非完全使用 ASCII，它應包含一個指定編碼的「Encoding」欄位。這用於 DESCRIPTION 檔案本身和 R 與 NAMESPACE 檔案的編碼，以及 .Rd 檔案的預設編碼。執行 R CMD check 時，範例假設使用此編碼，且此編碼用於 CITATION 檔案的編碼。已知只有 latin1 和 UTF-8 編碼名稱是可攜式的。（除非實際需要，否則請勿指定編碼：這樣做會讓套件 較不 可攜式。如果套件已指定編碼，您應在使用該編碼的區域設定中執行 R CMD build 等。）

如果套件包含需要編譯的原生程式碼，則「NeedsCompilation」欄位應設為 "yes"，否則設為 "no"（當套件可以在任何平台上從原始碼安裝，而無需其他工具時）。這由 R >= 2.15.2 中的 install.packages(type = "both") 在二進位套件為常態的平台上使用：通常由 R CMD build 或儲存庫設定，假設當且僅當套件具有 src 目錄時才需要編譯。

「OS_type」欄位指定套件的目標作業系統。如果存在，它應為 unix 或 windows 之一，並表示套件只能安裝在「.Platform$OS.type」具有該值的平台上。

「Type」欄位指定套件的類型：請參閱 套件類型。

可以使用欄位「分類/ACM」或「分類/ACM-2012」（使用電腦學會的電腦分類系統，https://www.acm.org/publications/class-2012；前者指 1998 年版本），「分類/JEL」（經濟文獻期刊分類系統，https://www.aeaweb.org/econlit/jelCodes.php），或「分類/MSC」或「分類/MSC-2010」（美國數學學會的數學主分類，https://mathscinet.ams.org/msc/msc2010.html；前者指 2000 年版本）為套件內容新增主題分類。主題分類應為各分類代碼的逗號分隔清單，例如「分類/ACM: G.4, H.2.8, I.5.1」。

可以使用「語言」欄位來表示套件文件不是英文：這應為標準（非私人使用或既得權益）IETF 語言標籤的逗號分隔清單，目前由 RFC 5646（https://www.rfc-editor.org/rfc/rfc5646）定義（另請參閱 https://en.wikipedia.org/wiki/IETF_language_tag），亦即，使用語言次標籤，其本質上為 2 個字母的 ISO 639-1（https://en.wikipedia.org/wiki/ISO_639-1）或 3 個字母的 ISO 639-3（https://en.wikipedia.org/wiki/ISO_639-3）語言代碼。

「RdMacros」欄位可用於儲存套件清單（以逗號分隔），目前套件將從中匯入 Rd 巨集定義。這些套件也應列在「Imports」（或「Depends」）中。這些套件中的巨集會在系統巨集之後匯入，順序依「RdMacros」欄位中所列，載入目前套件中的任何巨集定義之前。在 man 目錄中個別 .Rd 檔案中的巨集定義會在最後載入，且為該檔案後續部分的區域性定義。如有重複，將使用最後載入的定義。⁹ R CMD Rd2pdf 和 R CMD Rdconv 都有選用旗標 --RdMacros=pkglist。此選項也是套件名稱的逗號分隔清單，且優先於 DESCRIPTION 中所提供的值。使用 Rd 巨集的套件應相依於 R 3.2.0 或更新版本。

注意：不應有「Built」或「Packaged」欄位，因為這些欄位會由套件管理工具新增。

對於未在此處提及的其他欄位，並無使用限制（但使用這些欄位名稱的其他大小寫會造成混淆）。欄位 Note、Contact（用於聯絡作者/開發人員¹⁰）和 MailingList 為常見用法。部分儲存庫（包括 CRAN 和 R-forge）會新增自己的欄位。

1.1.2 授權 ¶

針對可能發布的套件進行授權是一項重要但可能複雜的主題。

包含授權資訊非常重要！否則，其他人甚至可能在法律上無法正確地散布套件的副本，更不用說使用它了。

套件管理工具使用「自由或開放原始碼軟體」(FOSS，例如，https://en.wikipedia.org/wiki/FOSS) 授權的概念：其想法是 R 及其套件的一些使用者想要將自己限制在這種軟體中。其他人需要確保沒有任何限制阻止他們使用套件，例如禁止商業或軍事用途。FOSS 軟體的核心原則是對使用者或使用沒有任何限制。

請勿使用「授權」欄位來提供有關著作權持有人的資訊：如有需要，請使用「著作權」欄位。

在 DESCRIPTION 檔案中的強制性「授權」欄位應以標準化格式指定套件的授權。可透過直線符號 via 來表示其他選項。個別規格必須為下列其中一項

• 「標準」簡短規格之一

  GPL-2 GPL-3 LGPL-2 LGPL-2.1 LGPL-3 AGPL-3 Artistic-2.0
  BSD_2_clause BSD_3_clause MIT
  

  如透過 https://www.R-project.org/Licenses/ via 提供，並包含在 R 來源或主目錄的 share/licenses 子目錄中。

• R 來源或主目錄中檔案 share/licenses/license.db 中授權資料庫中所包含的其他授權的名稱或縮寫，可能（對於版本化授權）後接「(op v)」形式的版本限制，其中「op」為其中一個比較運算子「<」、「<=」、「>」、「>=」、「==」或「!=」，而「v」為數字版本規格（由「.」分隔的非負整數字串），可能透過「,」結合（請參閱下方範例）。對於版本化授權，您也可以指定名稱後接版本，或將現有縮寫與版本結合「-」。

  縮寫 GPL 和 LGPL 含糊不清，通常¹¹表示任何版本的授權：但最好不要使用它們。

• 字串「file LICENSE」或「file LICENCE」之一，是指套件（來源和安裝）頂層目錄中名為 LICENSE 或 LICENCE 的檔案。
• 字串「Unlimited」，表示除了相關法律（包括著作權法）施加的限制之外，沒有任何關於發行或使用的限制。

多個授權可以使用「|」（由空格包圍）分隔指定，在這種情況下，使用者可以選擇任何替代方案。

如果套件授權限制基本授權（在允許的情況下，例如使用 GPL-3 或 AGPL-3 與歸屬條款），則應將附加條款放入檔案 LICENSE（或 LICENCE），並將字串「+ file LICENSE」（或「+ file LICENCE」，分別）附加到對應的個別授權規格（最好用空格包圍「+」）。請注意，幾個常用的授權不允許限制：這包括 GPL-2，因此任何包含它的規格。

標準化規格的範例包括

License: GPL-2
License: LGPL (>= 2.0, < 3) | Mozilla Public License
License: GPL-2 | file LICENCE
License: GPL (>= 2) | BSD_3_clause + file LICENSE
License: Artistic-2.0 | AGPL-3 + file LICENSE

請特別注意，「公共領域」不是有效的授權，因為它在某些司法管轄區不被承認。

請確保您選擇的授權也涵蓋套件的任何依賴項（包括系統依賴項）：特別重要的是，此類依賴項的使用限制應清楚顯示給正在閱讀您的 DESCRIPTION 檔案的人員。

欄位「License_is_FOSS」和「License_restricts_use」可以由無法從授權名稱計算資訊的儲存庫新增。「License_is_FOSS: yes」用於已知為 FOSS 的授權，「License_restricts_use」如果已知 LICENSE 檔案限制使用者或使用，或已知不限制，則其值可以為「yes」或「no」。例如，available.packages 篩選器會使用這些值。

選用的檔案 LICENSE/LICENCE 包含套件授權的副本。為避免混淆，僅在 DESCRIPTION 檔案的「License」欄位中參照到此類檔案時才包含此類檔案。

雖然您應該可以自由地在您的原始碼發行版中包含授權檔案，但請不要安排安裝 GNU COPYING 或 COPYING.LIB 檔案的另一個副本，而是參照 https://www.R-project.org/Licenses/ 上的副本，並包含在 R 發行版中（在目錄 share/licenses 中）。由於會安裝名為 LICENSE 或 LICENCE 的檔案，因此請勿將這些名稱用於標準授權檔案。若要包含有關授權的註解，而非授權主體，請使用類似 LICENSE.note 的檔案名稱。

一些「標準」授權書比較像是授權範本，需要額外的資訊才能透過「+ file LICENSE」（「+」前後有空格）完成。COPYRIGHT HOLDER 的附加資訊必須提供實際的法律實體（而非模糊的字眼，例如「套件作者姓名」）：如果有多個，應依貢獻度遞減順序列出。

1.1.3 套件相依性 ¶

「Depends」欄位提供此套件相依的套件名稱，以逗號分隔。當呼叫 library 或 require 時，這些套件會在目前套件之前附加。每個套件名稱後方可選擇加上括號內的註解，以指定版本需求。註解應包含比較運算子、空白和有效的版本號碼，例如「MASS (>= 3.1-20)」。

「Depends」欄位也可以指定對特定 R 版本的相依性，例如，如果套件只能使用 R 版本 4.0.0 或更新版本，請在「Depends」欄位中包含「R (>= 4.0)」（如範例所示，尾數 0 可省略，建議省略）。您也可以要求 R-devel 或 R-patched 的特定 SVN 修訂版，例如「R (>= 2.14.0), R (>= r56550)」需要 2011 年 7 月底的 R-devel 之後版本（包括 2.14.0 的已發布版本）。

未指定版本明細就宣告依賴 R，或依賴套件 base 沒有意義：這是 R 套件，而 base 套件總是可用。

套件或「R」可以在「Depends」欄位中出現多次，例如提供可接受版本的上下界限。

不建議使用補丁層級（第三位數）非零的 R 依賴關係。對其他依賴的套件執行此操作會導致其他套件在系列中較早版本中無法使用，例如版本 4.x.1 在北半球學年中廣泛使用。

library 和 R 套件檢查功能都使用此欄位：因此，使用不當語法或誤用「Depends」欄位來評論可能需要的其他軟體是錯誤的。R INSTALL 功能會檢查所使用的 R 版本是否足夠新以安裝套件，並且會在檢查版本需求後附加所指定的套件清單（在目前套件之前）。

「Imports」欄位列出從中匯入命名空間的套件（如 NAMESPACE 檔案中所指定），但不需要附加的套件。透過「::」和「:::」運算子存取的命名空間必須在此列出，或在「Suggests」或「Enhances」中列出（請見下方）。理想情況下，此欄位會包含所有使用的標準套件，且包含使用 S4 的套件非常重要（因為其類別定義可能會變更，而 DESCRIPTION 檔案用於決定在這種情況下重新安裝哪些套件）。在「Depends」欄位中宣告的套件不應同時出現在「Imports」欄位中。可以在載入命名空間時指定版本需求並進行檢查。

「Suggests」欄位使用與「Depends」相同的語法，並列出不一定要的套件。這包括僅在範例、測試或小插圖中使用的套件（請見 撰寫套件小插圖），以及在函式主體中載入的套件。例如，假設套件 foo 中的範例¹² 使用套件 bar 中的資料集。那麼，除非要執行所有範例/測試/小插圖，否則 bar 不需要使用 foo：擁有 bar 有用，但不是必要的。可以指定版本需求，但應由使用套件的程式碼進行檢查。

最後，「Enhances」欄位會列出由目前套件「增強」的套件，例如，提供這些套件中類別的方法，或處理這些套件中物件的方式（因此，許多套件會有「Enhances: chron」，因為即使它們偏好 R 的原生日期時間函式，它們也能處理 chron 中的日期時間物件）。可以指定版本需求，但目前並未使用。此類套件無法被要求檢查套件：任何使用它們的測試都必須以套件的存在為條件。（如果您的測試使用例如來自其他套件的資料集，它應該在「Suggests」中，而不是「Enhances」中。）

一般規則如下：

• 一個套件只能列在這些欄位中的其中一個。
• 僅需要其命名空間才能使用 library(pkgname) 載入套件的套件，應列在「Imports」欄位中，而不是「Depends」欄位中。在 NAMESPACE 檔案中 import 或 importFrom 指令中列出的套件，幾乎都應該在「Imports」中，而不是「Depends」中。
• 需要附加才能使用 library(pkgname) 成功載入套件的套件，必須列在「Depends」欄位中。
• 所有套件都必須列在「Depends」、「Suggests」或「Imports」中，才能成功在套件上執行 R CMD check¹³。有條件執行範例或測試的套件（例如 透過 if(require(pkgname))）應列在「Suggests」或「Enhances」中。（這讓檢查程式可以確保已安裝完整檢查所需的所有套件。）
• 使用套件中資料集所需的套件應在「Imports」中：這包括定義所使用的 S4 類別。

特別是，提供範例或小品文「僅」資料的套件應列在「Suggests」中，而不是「Depends」，以利精簡安裝。

當 library 載入套件時，「Depends」和「Imports」欄位中的版本相依性會被使用，而 install.packages 會檢查「Depends」、「Imports」和（對於 dependencies = TRUE）「Suggests」欄位的版本。

這些欄位中的資訊必須完整且正確非常重要：例如，它用於計算哪些套件相依於已更新的套件，以及哪些套件可以安全地並行安裝。

此架構是在所有套件都有命名空間之前（2011 年 10 月的 R 2.14.0）開發的，而一旦命名空間就位，良好的做法就改變了。

欄位「Depends」現今應少用，僅用於打算放置在搜尋路徑中，以提供其功能給最終使用者（而非套件本身）的套件：例如，套件 latticeExtra 的使用者會希望套件 lattice 的函數可用。

「Depends」中提到的套件幾乎都應該從 NAMESPACE 檔案中匯入：這可確保當其他套件匯入目前的套件時，這些套件的任何必要部分都可用。

「Imports」欄位不應包含未從 (經由 NAMESPACE 檔案或 :: 或 ::: 算子) 匯入的套件，因為該欄位中列出的所有套件都必須安裝，目前的套件才能安裝。（這會由 R CMD check 檢查。）

套件中的 R 程式碼應僅在例外情況下呼叫 library 或 require。對於列在「Depends」的套件，此類呼叫從不需要，因為它們已經在搜尋路徑中。過去常在使用其功能的函數中，對列在「Suggests」的套件使用 require 呼叫，但現今最好 經由 :: 呼叫存取此類功能。

希望使用其他套件中的標頭檔案來編譯其 C/C++ 程式碼的套件，需要在 DESCRIPTION 檔案的「LinkingTo」欄位中，將它們宣告為逗號分隔的清單。例如

LinkingTo: link1, link2

「LinkingTo」欄位可以有版本需求，這會在安裝時檢查。

如果「LinkingTo」中的套件是包含原始碼的 C/C++ 標頭，或在安裝時進行靜態連結，則指定「LinkingTo」中的套件就足夠了：這些套件不需要（而且通常不應該）列在「Depends」或「Imports」欄位中。這包括 CRAN 套件 BH，以及幾乎所有 RcppArmadillo 和 RcppEigen 的使用者。請注意，「LinkingTo」僅適用於安裝：如果套件希望使用標頭來編譯測試或範例中的程式碼，則提供這些標頭的套件需要列在「Suggests」或可能是「Depends」中。

有關「LinkingTo」的另一種用法，請參閱 連結到其他套件中的原生常式。

「Additional_repositories」欄位是一個逗號分隔的儲存庫 URL 清單，可以在其中找到其他欄位中命名的套件。目前 R CMD check 使用它來檢查是否可以找到這些套件，至少作為原始碼套件（可以在任何平台上安裝）。

• 建議的套件

   if (requireNamespace("rgl", quietly = TRUE)) {
      rgl::plot3d(...)
   } else {
      ## do something else not involving rgl.
   }

1.1.4 INDEX 檔案 ¶

選用的檔案 INDEX 包含套件中每個足夠有趣的物件的一行，提供其名稱和說明（通常不會明確呼叫的函式，例如列印方法，可能不會包含在內）。通常這個檔案不存在，而對應的資訊會在從原始碼安裝時自動從文件來源產生（使用 tools::Rdindex()）。

這個檔案是 library(help = pkgname) 提供的資訊的一部分。

與其編輯此檔案，建議將套件的客製化資訊放入概觀說明頁面（請參閱 套件文件）和/或小插圖（請參閱 撰寫套件小插圖）。

1.1.5 套件子目錄 ¶

R 子目錄僅包含 R 程式碼檔案。要安裝的程式碼檔案必須以 ASCII（小寫或大寫）字母或數字開頭，並具有下列其中一個副檔名¹⁴ .R、.S、.q、.r 或 .s。我們建議使用 .R，因為這個副檔名似乎不會被任何其他軟體使用。應該可以使用 source() 讀取檔案，因此 R 物件必須透過指定來建立。請注意，檔案名稱和它建立的 R 物件之間不需要有任何關聯。理想情況下，R 程式碼檔案應僅直接指定 R 物件，且絕對不應呼叫具有副作用的函數，例如 require 和 options。如果需要運算來建立物件，這些運算可以使用套件中「較早」的程式碼（請參閱「Collate」欄位）加上「Depends」套件中的函數，前提是建立的物件不依賴這些套件，但透過命名空間匯入除外。

如果頂層運算依賴於其他套件的可用性，則需要特別小心。這特別適用於 setMethods 和 setClass 呼叫。它們也不應該依賴於外部資源的可用性，例如下載。

允許兩個例外：如果 R 子目錄包含檔案 sysdata.rda（一個或多個 R 物件的儲存影像：請使用 tools::resaveRdaFiles 建議的適當壓縮，並參閱「SysDataCompression」DESCRIPTION 欄位。）這將延遲載入到名稱空間環境中 - 這是針對系統資料集，不打算透過 data 讓使用者存取 via。此外，以「.in」結尾的檔案將允許在 R 目錄中，以允許 configure 指令碼產生合適的檔案。

在程式碼檔案中，只應使用 ASCII 字元（和控制字元 tab、換頁、LF 和 CR）。其他字元會在註解中接受¹⁵，但註解可能無法在例如 UTF-8 區域設定中讀取。當套件安裝時，物件名稱中的非 ASCII 字元通常會¹⁶失敗。任何位元組都可以在引號的字串中允許，但應使用「\uxxxx」跳脫字元來處理非 ASCII 字元。然而，非 ASCII 字串可能無法在某些區域設定中使用，並可能在其他區域設定中顯示不正確。

封裝中可使用各種 R 函數來初始化和清理。請參閱 載入掛鉤。

man 子目錄應（僅）包含封裝中物件的說明文件，格式為 R 說明文件 (Rd)。說明文件檔名必須以 ASCII（小寫或大寫）字母或數字開頭，並使用擴充功能 .Rd（預設）或 .rd。此外，名稱必須在「file://」URL 中有效，表示¹⁷它們必須完全是 ASCII，且不包含「%」。請參閱 撰寫 R 說明文件，以取得更多資訊。請注意，封裝中的所有使用者層級物件都應有說明文件；如果封裝 pkg 包含僅供「內部」使用的使用者層級物件，則應提供文件 pkg-internal.Rd，說明所有此類物件，並清楚說明這些物件不應由使用者呼叫。例如，請參閱 R 發行版中封裝 grid 的來源。請注意，廣泛使用內部物件的封裝不應從其命名空間匯出這些物件，如果不需要說明文件（請參閱 封裝命名空間）。

如果 man 目錄不包含說明文件，可能會導致安裝錯誤。

man 子目錄可能包含名為 macros 的子目錄；其中會包含使用者定義 Rd 巨集的來源。（請參閱 使用者定義巨集。）這些巨集使用 Rd 格式，但可能僅包含巨集定義、註解和空白。

子目錄 R 和 man 可能包含名為 unix 或 windows 的特定作業系統子目錄。

編譯程式碼的原始碼和標頭檔位於 src 中，另外還有檔案 Makevars 或 Makefile（或在 Windows 上使用，副檔名為 .win 或 .ucrt）。當使用 R CMD INSTALL 安裝套件時，make 用於控制編譯和連結，以載入 R 中的共用物件。有預設的 make 變數和規則（在 R 設定並記錄在 R_HOME/etcR_ARCH/Makeconf 中時決定），提供對 C、C++、固定或自由格式 Fortran、Objective C 和 Objective C++¹⁸ 的支援，相關副檔名分別為 .c、.cc 或 .cpp、.f、.f90 或 .f95、¹⁹ .m 和 .mm。我們建議對標頭檔使用 .h，也可用於 C++²⁰ 或 Fortran 包含檔。（不再支援對 C++ 使用副檔名 .C。）src 目錄中的檔案不應隱藏（以點號開頭），某些 R 版本會忽略隱藏的檔案。

在單一套件中混合所有這些語言並非可攜式的（甚至可能完全不可行）。由於 R 本身使用它，我們知道 C 和固定格式 Fortran 可以一起使用，而混合 C、C++ 和 Fortran 通常適用於平台的原生編譯器。

如果您的程式碼需要依賴平台，則 C 或 C++ 中可以使用某些定義。在所有 Windows 組建（甚至 64 位元組組建）中，將定義「_WIN32」：在 64 位元組 Windows 組建中，也會定義「_WIN64」。在 macOS 中，定義「__APPLE__」²¹；對於「Apple Silicon」平台，請同時測試「__APPLE__」和「__arm64__」。

可以在檔案 src/Makevars 中設定巨集²² 來調整預設規則（請參閱 使用 Makevars）。請注意，此機制應足夠通用，以消除對特定於套件的 src/Makefile 的需求。如果要發行此類檔案，則需要非常小心，使其足夠通用，才能在所有 R 平台上執行。如果它有任何目標，它應具有適當的第一個目標，名為「all」，以及一個（可能是空的）目標「clean」，它會移除執行 make 所產生的所有檔案（供「R CMD INSTALL --clean」和「R CMD INSTALL --preclean」使用）。Windows 上有特定於平台的檔案名稱：src/Makevars.win 優先於 src/Makevars，並且必須使用 src/Makefile.win。自 R 4.2.0 起，src/Makevars.ucrt 優先於 src/Makevars.win，src/Makefile.ucrt 優先於 src/Makefile.win。src/Makevars.ucrt 和 src/Makefile.ucrt 將被早期版本的 R 忽略，因此可用於提供特定於 UCRT 或 Rtools42 及更新版本的內容，但 .ucrt 檔案的支援可能會在未來移除，屆時將不再需要從舊版 R 的原始碼組建套件，因此檔案可能會重新命名回 .win。有些 make 程式需要 makefile 具有完整的最後一行，包括換行符。

一些套件使用 src 目錄來進行建立共用物件以外的目的（例如建立可執行檔）。此類套件應具有 src/Makefile 和 src/Makefile.win 或 src/Makefile.ucrt 檔案（除非僅供類 Unix 系統或僅供 Windows 使用）。請注意，在 Unix 系統上，此類 makefile 會在 R_HOME/etc/R_ARCH/Makeconf 之後包含，因此所有常見的 R 巨集和 make 規則都可用，例如 C 編譯預設會使用 R 設定的 C 編譯器和旗標。從 R 4.3.0 開始，這也適用於 Windows：打算與較早版本一起使用的套件應自行包含該檔案。

對於 沒有 src/Makefile 檔案的套件，makefile 的包含順序為

對於有 src/Makefile 檔案的套件，包含順序為

大寫項目為環境變數：以逗號分隔的項目為以所示順序尋找的替代方案。

在非常特殊的情況下，套件可能會在 src 目錄中建立共用物件/DLL 以外的二進位檔。這些檔案不會安裝在多架構設定中，因為 R CMD INSTALL --libs-only 用於合併多個子架構，而且它只會複製共用物件/DLL。如果套件想要安裝其他二進位檔（例如可執行程式），它應該提供 R 腳本 src/install.libs.R，這會在 src 建置目錄中作為安裝的一部分執行，而不是複製共用物件/DLL。腳本會在包含下列變數的個別 R 環境中執行：R_PACKAGE_NAME（套件名稱）、R_PACKAGE_SOURCE（套件來源目錄路徑）、R_PACKAGE_DIR（套件目標安裝目錄路徑）、R_ARCH（路徑的架構相依部分，通常為空）、SHLIB_EXT（共用物件的副檔名）和 WINDOWS（在 Windows 上為 TRUE，在其他地方為 FALSE）。使用下列 src/install.libs.R 檔案可以複製近似於預設行為的行為

files <- Sys.glob(paste0("*", SHLIB_EXT))
dest <- file.path(R_PACKAGE_DIR, paste0('libs', R_ARCH))
dir.create(dest, recursive = TRUE, showWarnings = FALSE)
file.copy(files, dest, overwrite = TRUE)
if(file.exists("symbols.rds"))
    file.copy("symbols.rds", dest, overwrite = TRUE)

另一方面，可執行程式可以沿著下列方式安裝

execs <- c("one", "two", "three")
if(WINDOWS) execs <- paste0(execs, ".exe")
if ( any(file.exists(execs)) ) {
  dest <- file.path(R_PACKAGE_DIR,  paste0('bin', R_ARCH))
  dir.create(dest, recursive = TRUE, showWarnings = FALSE)
  file.copy(execs, dest, overwrite = TRUE)
}

注意在需要時使用 bin 的特定於架構的子目錄。（可執行檔應該安裝在 bin 目錄下，而不是 libs 下。建議檢查它們是否可以作為安裝腳本的一部分執行，這樣就不會安裝損壞的套件。）

data 子目錄是資料檔：請參閱 套件中的資料。

demo 子目錄是 R 範例腳本（用於透過 demo() 執行），用來示範套件的一些功能。範例可能是互動式的，而且不會自動檢查，所以如果要進行測試，請使用 tests 目錄中的程式碼來達成此目的。範例腳本檔必須以（大小寫）字母開頭，並具有 .R 或 .r 的其中一個副檔名。如果存在，demo 子目錄也應該有一個 00Index 檔，針對每個範例有一行，提供其名稱和說明，並以 tab 或至少三個空格分隔。（此索引檔不會自動產生。）請注意，範例沒有指定編碼，因此應該是 ASCII 檔（請參閱 編碼問題）。如果有一個套件編碼，函式 demo() 會使用該編碼，但這主要適用於非 ASCII 註解。

將 inst 子目錄的內容遞迴複製到安裝目錄中。 inst 的子目錄不應與 R 使用的目錄衝突（目前為 R、data、demo、exec、libs、man、help、html 和 Meta，而較早的版本使用 latex、R-ex）。inst 的複製發生在 src 建立之後，因此其 Makefile 可以建立要安裝的檔案。若要排除檔案不予安裝，可以在頂層原始碼目錄中的 .Rinstignore 檔案中指定排除模式清單。這些模式應為 Perl 式正規表示式（有關精確的詳細資訊，請參閱 R 中 regexp 的說明），每一行一個，不區分大小寫地與檔案和目錄路徑進行比對，例如 doc/.*[.]png$ 會根據副檔名排除 inst/doc 中的所有 PNG 檔案。

請注意，除了 INDEX、LICENSE/LICENCE 和 NEWS 之外，封裝頂層的資訊檔案不會安裝，因此 Windows 和 macOS 編譯封裝的使用者不會知道這些檔案（以及那些在 tarball 上使用 R CMD INSTALL 或 install.packages() 的使用者也看不到這些檔案）。因此，您希望最終使用者看到的任何資訊檔案都應包含在 inst 中。請注意，如果這些已命名的例外也出現在 inst 中，則 inst 中的版本將會出現在已安裝的封裝中。

您可能想要新增到 inst 的項目包括供 citation 函數使用的 CITATION 檔案，以及供 news 函數使用的 NEWS.Rd 檔案。請參閱其說明頁面，以取得 NEWS.Rd 檔案的特定格式限制。

在 inst 中有時需要的另一個檔案是 AUTHORS 或 COPYRIGHTS，用於指定作者或版權持有者，當這部分過於複雜而無法放入 DESCRIPTION 檔案時。

子目錄 tests 用於其他特定於套件的測試程式碼，類似於 R 發行版附帶的特定測試。測試程式碼可以透過 .R (或 .r，自 R 3.4.0 起) 檔案直接提供，或透過包含程式碼的 .Rin 檔案提供，該程式碼會進一步建立對應的 .R 檔案 (例如，透過收集套件中的所有函數物件，然後使用最奇怪的引數呼叫它們)。執行 .R 檔案的結果會寫入 .Rout 檔案。如果有一個對應的²³ .Rout.save 檔案，這兩個檔案會進行比較，並報告差異，但不會造成錯誤。目錄 tests 會複製到檢查區域，並以複製版本作為工作目錄，以及設定 R_LIBS 來執行測試，以確保在測試期間安裝的套件複製版本會被 library(pkg_name) 找到。請注意，特定於套件的測試會在沒有設定亂數種子的基本 R 會話中執行，因此使用亂數的測試需要設定種子才能取得可重製的結果 (而且在所有情況下這麼做都有幫助，以避免在執行測試時偶爾發生失敗)。

如果目錄 tests 有子目錄 Examples 包含檔案 pkg-Ex.Rout.save，這會與執行範例的輸出檔案進行比較，後者在檢查時會被檢查。參考輸出應在未設定 --timings 選項的情況下產生（並注意 --as-cran 會設定它）。

如果範例、測試或小插圖包含參考輸出，請務必確保它完全可重製，因為它會與檢查執行中產生的輸出逐字比較，除非使用「IGNORE_RDIFF」標記。讓維護人員絆倒的事情包括從載入其他套件顯示的版本號碼、將數值結果列印到無法重製的高精度，以及列印計時。另一個陷阱是實際上從零捨入錯誤的小值：考慮使用 zapsmall。

子目錄 exec 可能包含套件需要的其他可執行腳本，通常是殼層、Perl 或 Tcl 等直譯器的腳本。注意：只有 exec 下的檔案（而不是目錄）會被安裝（而名稱以點開頭的檔案會被忽略），而且它們在 POSIX 平台上都被標記為可執行（模式 755，由「umask」調整）。另請注意，這不適用於可執行 程式，因為某些平台（包括 Windows）使用相同的已安裝套件目錄支援多種架構。

子目錄 po 用於與 在地化 相關的檔案：請參閱 國際化。

子目錄 tools 是組態期間所需輔助檔案的首選位置，也是重新建立腳本所需的來源（例如 autoconf 的 M4 檔案：有些人喜歡將它們放在 tools 的 m4 子目錄中）。

1.1.6 套件中的資料 ¶

data 子目錄用於資料檔案，可透過延遲載入取得，或使用 data() 載入。（選擇方式為 DESCRIPTION 檔案中的「LazyData」欄位：預設為不這麼做。）它不應使用於套件所需的其它資料檔案，而慣例是使用 inst/extdata 目錄來存放這些檔案。

資料檔案可以有下列三種類型，由其副檔名表示：純 R 程式碼 (.R 或 .r)、表格 (.tab、.txt 或 .csv，檔案格式請參閱 ?data，請注意 .csv 並非 標準²⁴ CSV 格式) 或 save() 影像 (.RData 或 .rda)。這些檔案不應隱藏（名稱以點號開頭）。請注意，R 程式碼應盡可能「自給自足」，且不使用套件提供的額外功能，以便資料檔案也可以在未載入套件或其命名空間的情況下使用：它應盡可能靜默執行，且不透過附加套件或其它環境來變更 search() 路徑。

影像（副檔名 .RData²⁵ 或 .rda）可以包含用於建立它們的套件命名空間的參考。資料檔案中最好不要有這些參考，而且在任何情況下，它們只能是 Depends 和 Imports 欄位中所列的套件，否則可能無法安裝套件。若要檢查這些參考，請將所有影像載入到原始 R 會話中，對所有資料集執行 str()，並查看 loadedNamespaces() 的輸出。

當資料集或其元件之一為 S4 類別時，需要特別注意，特別是如果類別是在不同的套件中定義的。首先，包含類別定義的套件必須可用才能對資料集執行有用的操作，因此該套件必須列在 Imports 或 Depends 中（即使這會產生關於未使用的匯入的檢查警告）。其次，S4 類別的定義可能會改變，而且通常在具有不同作者的套件中不會被注意到。因此，使用 .R 形式並在需要時使用它來建立資料集物件可能會比較明智（載入套件名稱空間，但不要透過使用 requireNamespace(pkg, quietly = TRUE) 和使用 pkg:: 來參照名稱空間中的物件）。

如果您沒有使用「LazyData」，而且您的資料檔案很大，或者您使用 data/foo.R 腳本來產生資料，載入您的名稱空間，您可以透過在 data 子目錄中提供 datalist 檔案來加速安裝。這應該針對 data() 會找到的主題，每行一個，格式為「foo」，如果 data(foo) 提供「foo」，或者「foo: bar bah」，如果 data(foo) 提供「bar」和「bah」。R CMD build 會自動將 datalist 檔案新增到超過 1Mb 的 data 目錄，使用函式 tools::add_datalist。

表格（.tab、.txt 或 .csv 檔案）可以用 gzip、bzip2 或 xz 壓縮，也可以選擇使用額外的副檔名 .gz、.bz2 或 .xz。

如果您的套件要進行散布，請考慮大型資料集對您的使用者所造成的資源影響：它們會讓套件下載非常緩慢，並使用大量儲存空間，而且載入時會花費數秒。一般來說，最好將大型資料集散布為 .rda 映像，由 save(, compress = TRUE)（預設值）準備。使用 bzip2 或 xz 壓縮通常會縮小套件 tarball 和已安裝套件的大小，在某些情況下會縮小兩倍以上。

套件 tools 有幾個函式可以協助處理資料映像：checkRdaFiles 會報告映像儲存的方式，而 resaveRdaFiles 會使用不同的壓縮類型重新儲存，包括為特定映像選擇最佳類型。

許多使用「LazyData」的套件會受益於在已安裝的延遲載入資料庫中使用 gzip 以外的壓縮形式。這可以使用 R CMD INSTALL 的 --data-compress 選項或使用 DESCRIPTION 檔案中的「LazyDataCompression」欄位來選擇。有用的值包括 bzip2、xz 和預設值 gzip：值 none 也被接受。找出哪個值最佳的方法是全部嘗試看看，並查看 pkgname/data/Rdata.rdb 檔案的大小。一個可以做到這件事的函式（以 KB 為單位引述大小）是

CheckLazyDataCompression <- function(pkg)
{
    pkg_name <- sub("_.*", "", pkg)
    lib <- tempfile(); dir.create(lib)
    zs <- c("gzip", "bzip2", "xz")
    res <- integer(3); names(res) <- zs
    for (z in zs) {
        opts <- c(paste0("--data-compress=", z),
                  "--no-libs", "--no-help", "--no-demo", "--no-exec", "--no-test-load")
        install.packages(pkg, lib, INSTALL_opts = opts, repos = NULL, quiet = TRUE)
        res[z] <- file.size(file.path(lib, pkg_name, "data", "Rdata.rdb"))
    }
    ceiling(res/1024)
}

(應用於沒有任何「LazyDataCompression」欄位的原始套件)。如果 R CMD check 發現一個超過 5MB 的 pkgname/data/Rdata.rdb 檔案，且未設定「LazyDataCompression」，就會發出警告。如果看到此警告，請執行 CheckLazyDataCompression() 並設定欄位，在不太可能的情況下²⁶，設定為 gzip 是最佳選擇。

sysdata.rda 的類比是「SysDataCompression」欄位：預設值為檔案大於 1MB 時為 xz，否則為 gzip。

對於非常大的資料集（序列化時超過 2GB，也就是 32 位元平台格式的限制），不支援延遲載入。

1.1.7 套件中的非 R 腳本 ¶

需要編譯的程式碼 (C、C++、Fortran …) 包含在 src 子目錄中，並在本文檔的其他地方討論。

子目錄 exec 可用於殼層、BUGS、JavaScript、Matlab、Perl、php (amap)、Python 或 Tcl (Simile) 或甚至是 R 的腳本。不過，使用 inst 目錄似乎更為常見，例如 WriteXLS/inst/Perl、NMF/inst/m-files、RnavGraph/inst/tcl、RProtoBuf/inst/python 以及 emdbook/inst/BUGS 和 gridSVG/inst/js。

Java 程式碼是一個特殊案例：除了非常小的程式外，.java 檔案應編譯成位元組碼（編譯成 .class 檔案），並作為 .jar 檔案的一部分進行發布：.jar 檔案的慣例位置是 inst/java。最好（且在開放原始碼授權下是必要的）讓 Java 原始檔可用：這最適合在套件中的頂層 java 目錄中進行，不應安裝原始檔。

如果您的套件需要這些解釋器或延伸模組之一，則應在 DESCRIPTION 檔案的「SystemRequirements」欄位中宣告這一點。（Java 使用者最常透過 rJava 進行，當依賴/匯入時，除非套件中的 Java 程式碼有版本需求，否則這就足夠了。）

Windows 和 Mac 使用者應注意 Tcl 擴充套件「BWidget」和「Tktable」（有時會包含在 Windows²⁷ 和 macOS R 安裝程式中）是擴充套件，需要宣告（而且「Tktable」的取得管道比以前少，包括不在主要 Linux 散佈版的存放庫中）。「BWidget」需要使用者在其他作業系統中安裝。這很容易：首先找到 Tcl 搜尋路徑

library(tcltk)
strsplit(tclvalue('auto_path'), " ")[[1]]

然後從 https://sourceforge.net/projects/tcllib/files/BWidget/ 下載原始程式碼，並在終端機執行類似下列指令

tar xf bwidget-1.9.14.tar.gz
sudo mv bwidget-1.9.14 /usr/local/lib

如果需要，請將 Tcl 搜尋路徑中的位置替換為 /usr/local/lib。（如果搜尋路徑中沒有可寫入的位置，您每次使用 BWidget 搭配 tcltk::addTclPath() 時，都需要新增一個。）

要（無聲地）測試「Tktable」是否存在，可以使用

library(tcltk)
have_tktable <- !isFALSE(suppressWarnings(tclRequire('Tktable')))

安裝「Tktable」需要 C 編譯器和 Tk 標頭檔（不一定會與 Tcl/Tk 一起安裝）。在撰寫本文時，最新的原始程式碼（2008 年）可從 https://sourceforge.net/projects/tktable/files/tktable/2.10/Tktable2.10.tar.gz/download 取得，但需要為目前的 Tk（8.6.11，但不是 8.6.10）進行修補，可以在 https://www.stats.ox.ac.uk/pub/bdr/Tktable/ 找到修補程式。對於 Tk 的系統安裝，您可能需要以「root」安裝 Tktable，因為在例如 Fedora 中，auto_path 上的所有位置都屬於「root」所有。

1.1.8 指定 URL ¶

套件文件中的許多位置的 URL 會在至少部分的呈現中轉換為可按一下的超連結。因此，需要小心它們的形式是否正確且可攜式。

應提供完整的 URL，包括 scheme（通常為「http://」或「https://」）和目錄參考的最後一個「/」。

URL 中的空格不可攜式，其處理方式會因 HTTP 伺服器和用戶端而異。在「http://」URL 的主機部分不應有空格，且其餘部分的空格應編碼，每個空格都替換為「%20」。

其他字元可能受益於編碼：請參閱 URLencode() 的說明。

CRAN 套件的標準 URL 為

https://r-cran.dev.org.tw/package=pkgname

而不是從「https://r-cran.dev.org.tw/web/packages/pkgname」開頭的版本。

1.2.1 使用 Makevars ¶

有時，可以透過提供檔案 Makevars 來避免撰寫自己的 configure 程式碼：configure 程式碼最常見的用途之一也是從 Makevars.in 建立 Makevars。

一個 Makevars 檔案是一個 makefile，且由 R CMD SHLIB（由 R CMD INSTALL 呼叫以編譯 src 目錄中的程式碼）當作多個 makefile 之一使用。它應該盡可能以可攜式的方式撰寫，特別是（除了 Makevars.win 和 Makevars.ucrt）不使用 GNU 擴充功能。

Makevars 檔案最常見的用法是設定 C/C++ 檔案的額外預處理器選項（例如包含路徑和定義），透過 PKG_CPPFLAGS，以及透過設定 PKG_CFLAGS、PKG_CXXFLAGS 或 PKG_FFLAGS，分別針對 C、C++ 或 Fortran 設定額外的編譯器旗標（請參閱 建立共用物件）。

注意：包含路徑是預處理器選項，而不是編譯器選項，且必須在 PKG_CPPFLAGS 中設定，否則特定於平台的路徑（例如「-I/usr/local/include」）將優先。 PKG_CPPFLAGS 應包含「-I」、「-D」、「-U」，以及（在支援的情況下）「-include」和「-pthread」選項：其他所有內容都應該是編譯器旗標。旗標的順序很重要，且在 PKG_CFLAGS 或 PKG_CXXFLAGS 中使用「-I」已導致難以偵錯的特定於平台的錯誤。

Makevars 也可用於設定連結器的旗標，例如「-L」和「-l」選項，透過 PKG_LIBS。

撰寫套件的 Makevars 檔案時，請務必確保它並非針對您的編譯器：例如 -O2 -Wall -pedantic（以及所有其他 -W 旗標：對於 Oracle 編譯器，這些旗標用於將參數傳遞給編譯器階段）等旗標都是針對 GCC（以及目標選項相容於它的編譯器，例如 clang）。

此外，請勿設定變數，例如 CPPFLAGS、CFLAGS 等：這些變數應允許使用者（網站）透過適當的個人（全站）Makevars 檔案設定。請參閱 R 安裝與管理 中的 自訂套件編譯。

有一些巨集³⁵是在設定 R 本身的建置時設定的，並儲存在 R_HOME/etcR_ARCH/Makeconf 中。該 makefile 會在 Makevars[.win] 之後 以 Makefile 的形式包含，而且它定義的巨集可以在後者的巨集指定和 make 命令列中使用。這些巨集包括

FLIBS ¶

一個包含連結 Fortran 程式碼所需的函式庫集合的巨集。這可能需要包含在 PKG_LIBS 中：如果套件在 src 目錄中包含 Fortran 原始檔，通常會自動包含它。

BLAS_LIBS ¶

在建置 R 時使用的 BLAS 函式庫的巨集。這可能需要包含在 PKG_LIBS 中。請注意，如果它是空的，則 R 可執行檔將包含所有雙精度和雙複數 BLAS 常式，但沒有單精度或複數常式。如果包含 BLAS_LIBS，則 FLIBS 也需要³⁶包含在後面，因為大多數 BLAS 函式庫至少部分是用 Fortran 編寫的。不過，如果套件包含 Fortran 原始碼，則可以省略它，因為那會將 FLIBS 加入連結線中。

LAPACK_LIBS ¶

建置 R 時使用的 LAPACK 函式庫（以及適當的路徑）的巨集。這可能需要包含在 PKG_LIBS 中。它可能會指向包含主要雙精度 LAPACK 常式以及建置 R 所需的雙複數 LAPACK 常式的動態函式庫 libRlapack，或者它可能會指向外部 LAPACK 函式庫，或者如果外部 BLAS 函式庫也包含 LAPACK，則可能是空的。

[libRlapack 包含 2003 年現有的所有雙精度 LAPACK 常式和一些較新的常式：包含哪些常式的清單在檔案 src/modules/lapack/README 中。請注意，外部 LAPACK/BLAS 函式庫不必這麼做，因為有些常式在 2015 年底的 LAPACK 3.6.0 中已「不建議使用」（且預設不編譯）。]

為了可攜性，巨集 BLAS_LIBS 和 FLIBS 應始終包含在 之後 LAPACK_LIBS（並按此順序）。

SAFE_FFLAGS ¶

包含迴避過度最佳化 FORTRAN 程式碼所需的旗標的巨集：在使用 gfortran 的 ix86 平台上，它可能是 '-g -O2 -ffloat-store' 或 '-g -O2 -msse2 -mfpmath=sse'。請注意，這 不是 要用作 PKG_FFLAGS 一部分的附加旗標，而是 FFLAGS 的替換。請參閱本節後面的範例。

在 Makevars 中設定某些巨集將防止 R CMD SHLIB 設定它們：特別是如果 Makevars 設定 'OBJECTS'，它將不會在 make 命令列上設定。這可以與隱式規則結合使用，以允許編譯其他類型的原始碼並包含在共用物件中。它也可以用來控制已編譯的檔案集，方法是排除 src 中的一些檔案或包含子目錄中的某些檔案。例如

OBJECTS = 4dfp/endianio.o 4dfp/Getifh.o R4dfp-object.o

請注意，Makevars 通常不應包含目標，因為它包含在預設 makefile 之前，而 make 將呼叫第一個目標，預計在預設 makefile 中為 all。如果您真的需要迴避這個問題，請在 Makevars.[win] 中的任何實際目標之前使用合適的（虛假的）目標 all：例如套件 fastICA 曾經有

PKG_LIBS = @BLAS_LIBS@

SLAMC_FFLAGS=$(R_XTRA_FFLAGS) $(FPICFLAGS) $(SHLIB_FFLAGS) $(SAFE_FFLAGS)

all: $(SHLIB)

slamc.o: slamc.f
        $(FC) $(SLAMC_FFLAGS) -c -o slamc.o slamc.f

需要確保 LAPACK 常式在沒有無限迴圈的情況下找到一些常數。Windows 等效項為

all: $(SHLIB)

slamc.o: slamc.f
        $(FC) $(SAFE_FFLAGS) -c -o slamc.o slamc.f

(由於其他巨集在該平台上都是空的，且未曾使用 R 的內部 BLAS)。請注意，Makevars 中的第一個目標將被呼叫，但為了向後相容性，最好將其命名為 all。

如果您想要建立並連結至函式庫，例如使用子目錄中的程式碼，請使用類似下列的內容

.PHONY: all mylibs

all: $(SHLIB)
$(SHLIB): mylibs

mylibs:
        (cd subdir; $(MAKE))

請務必建立所有必要的相依性，因為無法保證 all 的相依性將會以特定順序執行 (且部分 CRAN 建置機器使用多個 CPU 和平行建置)。特別是

all: mylibs

並 不足夠。GNU make 允許建構

.NOTPARALLEL: all
all: mylibs $(SHLIB)

但這並不可移植。dmake 和 pmake 允許類似的 .NO_PARALLEL，同樣不可移植：部分 pmake 變體接受 .NOTPARALLEL 作為 .NO_PARALLEL 的別名。

請注意，在 Windows 上，Makevars[.win, .ucrt] 必須建立 DLL：這是必要的，因為這是確保建立 DLL 成功唯一的可靠方式。如果您想要將 src 目錄用於建立 DLL 以外的其他目的，請使用 Makefile.win 或 Makefile.ucrt 檔案。

有時在 Makevars、Makevars.win 或 Makevars.ucrt 中有一個目標「clean」會很有用：R CMD build 會使用它來清除套件來源（的副本）。當它由 build 執行時，它會設定較少的巨集，特別是沒有 $(SHLIB)，也沒有 $(OBJECTS)，除非在檔案本身中設定。也可以將任務新增到目標「shlib-clean」，它會由 R CMD INSTALL 和 R CMD SHLIB 執行，並加上選項 --clean 和 --preclean。

避免在 makefile 中使用預設（也稱為「隱含」規則），因為它們是 make 特有的。即使 POSIX 規定，GNU make 也不會遵守，這會導致套件安裝中斷。

一個很常見的錯誤是

all: $(SHLIB) clean

它要求 make 在編譯程式碼的同時進行清除。這不僅會導致難以偵錯的安裝錯誤，還會清除所有錯誤的證據（無論是否為並行 make）。最好讓最終使用者使用前一段中的功能來進行清除。

如果您要在 Makevars 中執行 R 程式碼，例如尋找組態資訊，請務必使用正確的 R 或 Rscript 副本：路徑中可能完全沒有副本，或者可能是錯誤的版本或架構。正確的方法是透過

"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" filename
"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" -e ‘R expression’

其中 $(R_ARCH_BIN) 目前只在 Windows 上需要。

環境或 make 變數可用於為 32 位元和 64 位元程式碼選擇不同的巨集，例如（GNU make 語法，Windows 上允許）

ifeq "$(WIN)" "64"
PKG_LIBS = value for 64-bit Windows
else
PKG_LIBS = value for 32-bit Windows
endif

在 Windows 中，通常可以在連結至匯入函式庫或直接連結至 DLL 之間進行選擇。在可能的情況下，後者會可靠許多：匯入函式庫會繫結至特定工具鏈，特別是在 64 位元 Windows 中，通常會使用兩種不同的慣例。因此，例如，可以使用

PKG_LIBS = -L$(XML_DIR)/lib -lxml2

來取代

PKG_LIBS = -L$(XML_DIR)/bin -lxml2

因為在 Windows 中，-lxxx 會依序尋找

libxxx.dll.a
xxx.dll.a
libxxx.a
xxx.lib
libxxx.dll
xxx.dll

其中第一個和第二個慣例上是匯入函式庫，第三個和第四個通常是靜態函式庫（.lib 專門用於 Visual C++），但可能是匯入函式庫。例如，請參閱 https://sourceware.org/binutils/docs-2.20/ld/WIN32.html#WIN32。

美中不足的是，DLL 可能不會命名為 libxxx.dll，而且事實上在 32 位元 Windows 中有一個 libxml2.dll，而在 64 位元 Windows 的其中一個建置中，DLL 稱為 libxml2-2.dll。使用匯入函式庫可以涵蓋這些差異，但可能會造成相等的困難。

如果可以使用靜態函式庫，它們可以解決許多 DLL 執行時期尋找的問題，特別是在要散布二進位套件時，更是在這些套件支援兩種架構時。在無法避免使用 DLL 的情況下，我們通常會安排（透過 configure.win 或 configure.ucrt）將它們與套件 DLL 放在同一個目錄中。

• OpenMP 支援
• 使用 pthreads
• 在子目錄中編譯

SHLIB_OPENMP_CFLAGS
SHLIB_OPENMP_CXXFLAGS
SHLIB_OPENMP_FFLAGS

PKG_CFLAGS = $(SHLIB_OPENMP_CFLAGS)
PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)

PKG_FFLAGS = $(SHLIB_OPENMP_FFLAGS)
PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)

USE_FC_TO_LINK =
PKG_FFLAGS = $(SHLIB_OPENMP_FFLAGS)
PKG_LIBS = $(SHLIB_OPENMP_FFLAGS)

use omp_lib

  undefined symbol: __atomic_compare_exchange
  undefined symbol: __atomic_load

#pragma omp parallel for num_threads(nthreads) ...

PKG_CPPFLAGS = -pthread
PKG_LIBS = -pthread

PKG_CPPFLAGS = -D_REENTRANT
PKG_LIBS = -lpthread

SOURCES = $(wildcard data/*.cpp network/*.cpp utils/*.cpp model/*.cpp model/*/*.cpp model/*/*/*.cpp)

OBJECTS = siena07utilities.o siena07internals.o siena07setup.o siena07models.o $(SOURCES:.cpp=.o)

OBJECTS.samplers = samplers/ExpandableArray.o samplers/Knots.o \
  samplers/RJumpSpline.o samplers/RJumpSplineFactory.o \
  samplers/RealSlicerOV.o samplers/SliceFactoryOV.o samplers/MNorm.o
OBJECTS.distributions = distributions/DSpline.o \
  distributions/DChisqrOV.o distributions/DTOV.o \
  distributions/DNormOV.o distributions/DUnifOV.o distributions/RScalarDist.o
OBJECTS.root = RJump.o

OBJECTS = $(OBJECTS.samplers) $(OBJECTS.distributions) $(OBJECTS.root)

PKG_LIBS = -LCsdp/lib -lsdp $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)

$(SHLIB): Csdp/lib/libsdp.a

Csdp/lib/libsdp.a:      
        @(cd Csdp/lib && $(MAKE) libsdp.a \
          CC="$(CC)" CFLAGS="$(CFLAGS) $(CPICFLAGS)" AR="$(AR)" RANLIB="$(RANLIB)")

1.2.2 設定範例 ¶

提供使用 configure 指令碼建立 src/Makevars 檔案的延伸範例可能有所幫助：這基於 RODBC 套件中的範例。

configure.ac 檔案如下：configure 是透過在頂層套件目錄（包含 configure.ac）中執行 autoconf 而建立的。

AC_INIT([RODBC], 1.1.8) dnl package name, version

dnl A user-specifiable option
odbc_mgr=""
AC_ARG_WITH([odbc-manager],
            AC_HELP_STRING([--with-odbc-manager=MGR],
                           [specify the ODBC manager, e.g. odbc or iodbc]),
            [odbc_mgr=$withval])

if test "$odbc_mgr" = "odbc" ; then
  AC_PATH_PROGS(ODBC_CONFIG, odbc_config)
fi

dnl Select an optional include path, from a configure option
dnl or from an environment variable.
AC_ARG_WITH([odbc-include],
            AC_HELP_STRING([--with-odbc-include=INCLUDE_PATH],
                           [the location of ODBC header files]),
            [odbc_include_path=$withval])
RODBC_CPPFLAGS="-I."
if test [ -n "$odbc_include_path" ] ; then
   RODBC_CPPFLAGS="-I. -I${odbc_include_path}"
else
  if test [ -n "${ODBC_INCLUDE}" ] ; then
     RODBC_CPPFLAGS="-I. -I${ODBC_INCLUDE}"
  fi
fi

dnl ditto for a library path
AC_ARG_WITH([odbc-lib],
            AC_HELP_STRING([--with-odbc-lib=LIB_PATH],
                           [the location of ODBC libraries]),
            [odbc_lib_path=$withval])
if test [ -n "$odbc_lib_path" ] ; then
   LIBS="-L$odbc_lib_path ${LIBS}"
else
  if test [ -n "${ODBC_LIBS}" ] ; then
     LIBS="-L${ODBC_LIBS} ${LIBS}"
  else
    if test -n "${ODBC_CONFIG}"; then
      odbc_lib_path=`odbc_config --libs | sed s/-lodbc//`
      LIBS="${odbc_lib_path} ${LIBS}"
    fi
  fi
fi

dnl Now find the compiler and compiler flags to use
: ${R_HOME=`R RHOME`}
if test -z "${R_HOME}"; then
  echo "could not determine R_HOME"
  exit 1
fi
CC=`"${R_HOME}/bin/R" CMD config CC`
CFLAGS=`"${R_HOME}/bin/R" CMD config CFLAGS`
CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`

if test -n "${ODBC_CONFIG}"; then
  RODBC_CPPFLAGS=`odbc_config --cflags`
fi
CPPFLAGS="${CPPFLAGS} ${RODBC_CPPFLAGS}"

dnl Check the headers can be found
AC_CHECK_HEADERS(sql.h sqlext.h)
if test "${ac_cv_header_sql_h}" = no ||
   test "${ac_cv_header_sqlext_h}" = no; then
   AC_MSG_ERROR("ODBC headers sql.h and sqlext.h not found")
fi

dnl search for a library containing an ODBC function
if test [ -n "${odbc_mgr}" ] ; then
  AC_SEARCH_LIBS(SQLTables, ${odbc_mgr}, ,
      AC_MSG_ERROR("ODBC driver manager ${odbc_mgr} not found"))
else
  AC_SEARCH_LIBS(SQLTables, odbc odbc32 iodbc, ,
      AC_MSG_ERROR("no ODBC driver manager found"))
fi

dnl for 64-bit ODBC need SQL[U]LEN, and it is unclear where they are defined.
AC_CHECK_TYPES([SQLLEN, SQLULEN], , , [# include <sql.h>])
dnl for unixODBC header
AC_CHECK_SIZEOF(long, 4)

dnl substitute RODBC_CPPFLAGS and LIBS
AC_SUBST(RODBC_CPPFLAGS)
AC_SUBST(LIBS)
AC_CONFIG_HEADERS([src/config.h])
dnl and do substitution in the src/Makevars.in and src/config.h
AC_CONFIG_FILES([src/Makevars])
AC_OUTPUT

其中 src/Makevars.in 會很簡單地

PKG_CPPFLAGS = @RODBC_CPPFLAGS@
PKG_LIBS = @LIBS@

然後可以建議使用者透過選項（斷行以方便閱讀）指定 ODBC 驅動程式管理員檔案的位置

R CMD INSTALL \
  --configure-args='--with-odbc-include=/opt/local/include \
  --with-odbc-lib=/opt/local/lib --with-odbc-manager=iodbc' \
  RODBC

或透過設定環境變數 ODBC_INCLUDE 和 ODBC_LIBS。

1.2.3 使用 F9x 程式碼 ¶

R 假設副檔名為 .f 的原始檔是固定格式的 Fortran 90（包含 Fortran 77），並將它們傳遞給巨集 ‘FC’ 所指定的編譯器。Fortran 編譯器也會接受副檔名為 .f90 或（大多數⁴⁶）.f95 的自由格式 Fortran 90/95 程式碼。

固定格式和自由格式 Fortran 程式碼（具有不同的副檔名和可能不同的旗標）使用相同的編譯器。巨集 PKG_FFLAGS 可用於特定套件的旗標：對於未遇到的情況，兩個都包含在單一套件中，且兩種格式需要不同的旗標，巨集 PKG_FCFLAGS 也可用於自由格式 Fortran。

用於建置 R 的程式碼允許選擇 ‘Fortran 90’ 編譯器為 ‘FC’，因此可能會遇到僅支援 Fortran 90 的平台。但是，所有已知的平台都支援 Fortran 95。

「FC」指定的編譯器大多會接受 Fortran 2003、2008 或 2018 程式碼：此類程式碼仍應使用檔案副檔名 .f90。大多數目前的平台使用 gfortran，您可能需要在 PKG_FFLAGS 或 PKG_FCFLAGS 中包含 -std=f2003、-std=f2008 或（從版本 8 開始）-std=f2018：預設為「GNU Fortran」，目前為 Fortran 2018（但在 gfortran 8 之前為 Fortran 95），並帶有非標準擴充功能。目前使用的其他編譯器（LLVM 的 flang-new 和 Intel 的 ifx）預設為 Fortran 2018。

建議在 DESCRIPTION 的「SystemRequirements」欄位中描述 Fortran 版本需求。

Fortran 的現代版本支援模組，編譯一個原始檔會建立一個模組檔，然後包含在其他檔案中。（模組檔通常具有 .mod 副檔名：它們取決於所使用的編譯器，因此絕不應包含在套件中。）這會建立一個 make 不會知道的依賴關係，而且通常會導致並行 make 安裝失敗。因此，有必要在 src/Makevars 中新增明確的依賴關係，以告知 make 編譯順序的限制。例如，如果檔案 iface.f90 建立一個由檔案 cmi.f90 和 dmi.f90 使用的模組「iface」，則 src/Makevars 需要包含類似下列內容

cmi.o dmi.o: iface.o

請注意，在多個原始檔中定義同名的模組並非可攜式的（儘管有些平台接受它）。

1.2.4 使用 C++ 程式碼 ¶

R 可以不使用 C++ 編譯器進行建置，儘管在所有已知的 R 平台上都提供 C++ 編譯器（但不一定已安裝）。從 R 4.0.0 開始，只有符合 2011 年標準（「C++11」）的 C++ 編譯器才會被選取。2014 年 12 月發布了一個次要更新⁴⁷（「C++14」），如果支援的話，從 R 4.1.0 開始預設使用。自此之後，又陸續發布了「C++17」（2017 年 12 月）和「C++20」（2020 年 12 月，新增許多新功能）。預計下一個版本「C++23」將於 2023/4 年推出，目前已有許多編譯器已廣泛支援目前的草案。

如果支援的話，R 4.3.0 中編譯 R 套件的預設標準已變更為 C++17（對於較舊的編譯器，預設會使用 C++14 甚至 C++11）。

很難確定 C++ 編譯器旨在支援哪個標準：__cplusplus 的值⁴⁸ 可能有所幫助，但有些編譯器使用它來表示部分支援的標準，有些則表示（幾乎）完全支援的最新標準。在類 Unix 系統上，configure 會嘗試為每個標準識別編譯器和旗標：這在很大程度上依賴於 __cplusplus 的報告值。

網頁 https://en.cppreference.com/w/cpp/compiler_support 提供了一些關於已知支援最新 C++ 功能的編譯器的資訊。

C++ 標準已棄用並移除了一些功能。請注意，一些目前的編譯器在 C++17 模式下仍接受已移除的功能，例如 std::unary_function（在 C++11 中已棄用，在 C++17 中已移除）。

不同版本的 R 使用不同的預設 C++ 標準，因此為了最大可攜性，套件應指定其所需的標準。若要使用 Makevars 檔案（或 Windows 上的 Makevars.win 或 Makevars.ucrt）在套件中指定 C++14 程式碼，應包含下列程式碼行

CXX_STD = CXX14

然後將使用 C++14 編譯器（如果有）進行編譯和連結。其他標準亦同（詳情如下）。另一方面，當程式碼在 C++14 或 C++17 下有效時，指定 C++11⁴⁹ 會降低未來的可攜性。

沒有 src/Makevars 或 src/Makefile 檔案的套件可以在 DESCRIPTION 檔案的「SystemRequirements」欄位中包含類似「C++14」的內容，為 src 目錄中的程式碼指定 C++ 標準，例如：

SystemRequirements: C++14

如果套件確實有 src/Makevars[.win] 檔案，建議同時設定 make 變數「CXX_STD」，因為它允許 R CMD SHLIB 在套件的 src 目錄中正確運作。

C++17 或更新版本的必要條件應始終在「SystemRequirements」欄位（以及 src/Makevars 或 src/Makefile）中宣告，因此這會顯示在 CRAN 或類似網站上的套件摘要頁面。這對於 C++14 的必要條件來說也是個好習慣。請注意，只有 R 3.4.0 才支援 C++14 或 C++17，因此如果套件有 R 版本必要條件，則需要考慮這一點。

基本上，GCC 5、LLVM clang 3.4 和目前使用的 Apple clang 版本提供完整的 C++14 支援。

需要 C++14 功能的程式碼可以透過「SD-6 功能測試」⁵⁰來檢查它們是否存在。這樣的檢查可以是

#include <memory> // header where this is defined
#if defined(__cpp_lib_make_unique) && (__cpp_lib_make_unique >= 201304)
using std::make_unique;
#else
// your emulation
#endif

C++17（從 R 3.4.0 開始）、C++20（從 R 4.0.0 開始）和 C++23（從 R 4.3.0 開始）可以用類似的方式指定（用 17、20 或 23）取代 14），但編譯器/作業系統支援取決於平台。從 R 4.0.0 開始，macOS 和 Windows 上的 R 預設建置提供了一些 C++17 和 C++20 支援。g++ 對 C++17 的大部分支援需要 7 或更新的版本：這比一些仍然是目前版本的 Linux 發行版更新，但通常可以取得更新編譯器的套件：對於 RHEL/Centos 7，請尋找「devtoolset」。

請注意，C++17 或更新的「支援」並不表示完整的支援：請使用功能測試以及 https://en.cppreference.com/w/cpp/compiler_support、https://gcc.gnu.org/projects/cxx-status.html 和 https://clang.llvm.org/cxx_status.html 等資源，以查看您想要使用的功能是否廣泛實作。

嘗試指定未知的 C++ 標準會被靜默忽略：最近版本的 R 會為 C++98 以及未偵測到編譯器+旗標的已知標準擲回錯誤。

如果使用 C++ 的套件有 configure 指令碼，則指令碼必須透過類似下列內容來選擇正確的 C++ 編譯器和標準

CXX17=`"${R_HOME}/bin/R" CMD config CXX17`
if test -z "$CXX17"; then
  AC_MSG_ERROR([No C++17 compiler is available])
fi
CXX17STD=`"${R_HOME}/bin/R" CMD config CXX17STD`
CXX="${CXX17} ${CXX17STD}"
CXXFLAGS=`"${R_HOME}/bin/R" CMD config CXX17FLAGS`
## for an configure.ac file
AC_LANG(C++)

如果指定了 C++17，但使用

CXX=`"${R_HOME}/bin/R" CMD config CXX`
CXXFLAGS=`"${R_HOME}/bin/R" CMD config CXXFLAGS`
## for an configure.ac file
AC_LANG(C++)

如果未指定標準。

如果您要在子目錄中編譯 C++ 程式碼，請務必傳遞巨集來指定適當的編譯器，例如在 src/Makevars 中

sublibs:
         @(cd libs && $(MAKE) \
            CXX="$(CXX17) $(CXX17STD)" CXXFLAGS="$(CXX17FLAGS) $(CXX17PICFLAGS)")

上述討論是關於編譯 C++ 的標準 R 方式：它不適用於使用 src/Makefile 的套件，或是在未設定 C++ 標準的子目錄中建置。而且編譯器的預設 C++ 標準差異很大，而且供應商經常變更，例如 Apple clang 14 預設為 C++98，LLVM clang 14–15 為 C++14，LLVM clang 16 為 C++17，g++ 11–13 為 C++17。

對於具有 src/Makefile（或 Windows 類比）的套件，可以透過包含類似以下內容來選擇非預設 C++ 編譯器

CXX14 = `"${R_HOME}/bin/R" CMD config CXX14`
CXX14STD = `"${R_HOME}/bin/R" CMD config CXX14STD`
CXX = ${CXX14} ${CXX14STD}
CXXFLAGS = `"${R_HOME}/bin/R" CMD config CXX14FLAGS`
CXXPICFLAGS = `"${R_HOME}/bin/R" CMD config CXX14PICFLAGS`
SHLIB_LD = "${R_HOME}/bin/R" CMD config SHLIB_CXX14LD`
SHLIB_LDFLAGS = "${R_HOME}/bin/R" CMD config SHLIB_CXX14LDFLAGS`

並確保在相關編譯中使用這些值，在檢查它們是否非空後。 src/Makefile 的常見用途是編譯可執行檔，例如（例如對於 C++14）

CXX14 = `"${R_HOME}/bin/R" CMD config CXX14`
CXX14STD = `"${R_HOME}/bin/R" CMD config CXX14STD`
CXX = ${CXX14} ${CXX14STD}
CXXFLAGS = `"${R_HOME}/bin/R" CMD config CXX14FLAGS`

就夠了。在 Unix（以及從 R 4.3.0 開始的 Windows）上，這可以簡化為

CXX = ${CXX14} ${CXX14STD}
CXXFLAGS = ${CXX14FLAGS}

在類 Unix 的 C++ 編譯中，從 R 3.6.0 預設為 C++11，從 R 4.1.0 預設為 C++14，從 R 4.3.0 預設為 C++17。然而，僅在「可用時」，因此使用非常舊版作業系統的平台可能已使用先前的預設值。甚至更舊版本的 R 預設為編譯器的預設值，對於同年代的編譯器來說幾乎可以確定是 C++98。

在 Windows 上，預設值已從 R 3.6.2 中的 C++98 變更為 R 4.2.3 中的 C++11，再變更為 R 4.3.0 中的 C++17。

C++11 標準可以從 R 3.1.0 指定，C++14 或 C++17 可以從 R 3.4.0 指定，C++20 可以從 R 4.0.0 指定，C++23 可以從 R 4.3.0 指定（儘管它們可能不受使用的編譯器支援）。C++11 支援在 R 4.0.0 中已成為強制性。

套件中的 .so/.dll 可能需要由 C++ 編譯器連結，如果它或任何它連結的函式庫包含已編譯的 C++ 程式碼。動態連結通常會引入 C++ 執行時期函式庫（通常為 libstdc++，但也可以是 libc++ 等），但靜態連結（如用於 Windows 和 macOS 的外部函式庫）則不會。R CMD INSTALL 會在 src 中有任何頂層 C++ 檔案時使用 C++ 編譯器連結，但如果這些檔案都在子目錄中，則不會。強制使用 C++ 編譯器連結的最簡單方法是在 src 中包含一個空的 C++ 檔案。

1.2.5 C 標準 ¶

C 已有 C89/C90、C99、C11、C17（也稱為 C18）標準，而 C23 處於最後草案階段，預計將於 2024 年初發布。C11 是對 C99 的小幅變更，引入了幾個新功能並使其他功能變為選用，而 C17 是對 C11 的「錯誤修正」更新。另一方面，C23 進行了廣泛的變更，包括將 bool、true 和 false 設為保留字，最終不允許使用 K&R 風格的函式宣告，並澄清以前已棄用的函式宣告含空參數清單的含意，表示零個參數。（還有許多其他新增功能：例如，請參閱 https://en.cppreference.com/w/c/23。）

最近版本的 R 中的 configure 程式碼旨在選擇支援 C11 的 C 編譯器：由於 gcc、LLVM clang 和 Apple clang 的最新版本中預設為 C17，因此可能會選擇 C17。另一方面，直到 R 4.3.0 為止，Windows 建置的 makefile 指定 C99。它們現在使用建議編譯器的編譯器預設值，即 C17。

套件可能想要避免或採用 C23 中的變更，並且可以透過在套件的 DESCRIPTION 檔案的「SystemRequirements」欄位中指定「USE_Cnn」來達成，其中 nn 為 17、23、90 或 99，視「R (>= 4.3.0)」而定。使用 configure 程式碼的人員應設定對應的編譯器和旗標，例如使用

CC=`"${R_HOME}/bin/R" CMD config CC23`
CFLAGS=`"${R_HOME}/bin/R" CMD config C23FLAGS`
CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`
LDFLAGS=`"${R_HOME}/bin/R" CMD config LDFLAGS`

巨集 __STDC_VERSION__ 可以檢查正在使用的（宣稱的）C 標準。這在 C89/C90 中未定義，並且對於 C99、C11 和 C17 應具有值 199901L、201112L 和 201710L。由於 C23 尚未發布，因此尚未有明確的值：編譯器目前使用 202000L。C23 具有類似於 C++「功能測試」的巨集，可針對其許多變更使用，例如 __STDC_VERSION_LIMITS_H__。

不過，請注意「宣稱的」一詞，因為沒有任何編譯器具有 100% 的相容性，而且最好使用 configure 來測試您想要使用的功能，而不是以 __STDC_VERSION__ 的值為條件。特別是，C11 對齊功能（例如 _Alignas 和 aligned_alloc）並未在 Windows 上實作。

使用者可以透過類似 R CMD INSTALL --use-C17 的指令來指定標準。這會覆寫「SystemRequirements」欄位，但不會對任何 configure 檔案生效。

1.2.6 使用 cmake ¶

套件通常會希望包含其他軟體的原始碼，並編譯以包含在他們的 .so 或 .dll 中，這通常是透過包含（或解壓縮）原始碼在 src 的子目錄中來完成，如上所述。

當外部軟體使用其他建置系統（例如 cmake）時，會產生進一步的問題，主要是為了確保編譯器、包含和載入路徑等的所有設定都已完成。本節已經提到至少需要設定

CC CFLAGS CXX CXXFLAGS CPPFLAGS LDFLAGS

CFLAGS 和 CXXFLAGS 將需要分別包含 CPICFLAGS 和 CXXPICFLAGS，除非（如下所示）要求 cmake 產生 PIC 程式碼。

將這些（和更多）設定為環境變數會控制 cmake 的行為（https://cmake.dev.org.tw/cmake/help/latest/manual/cmake-env-variables.7.html#manual:cmake-env-variables(7)），但可能需要將這些轉換為原生設定，例如

CMAKE_C_COMPILER
CMAKE_C_FLAGS
CMAKE_CXX_COMPILER
CMAKE_CXX_FLAGS
CMAKE_INCLUDE_PATH
CMAKE_LIBRARY_PATH
CMAKE_SHARED_LINKER_FLAGS_INIT
CMAKE_OSX_DEPLOYMENT_TARGET

而且通常需要透過

-DBUILD_SHARED_LIBS:bool=OFF
-DCMAKE_POSITION_INDEPENDENT_CODE:bool=ON

來確保建置 PIC 程式碼的靜態函式庫。

為了修正想法，考慮一個套件，其原始碼為 myLib 函式庫，位於 src/libs 下。已使用兩種方法。通常最方便的做法是在目錄中建置外部軟體，而不是其原始碼（特別是在開發期間，可以在建置之間移除建置目錄，而不是嘗試清理原始碼） – 這在第一種方法中說明。

1. 使用套件的 configure 腳本建立靜態函式庫 src/build/libmyLib.a。然後可以像對待外部軟體一樣處理它，例如在 src/Makevars 中

   PKG_CPPFLAGS = -Ilibs/include
   PKG_LIBS = build/libmyLib.a
   

   (-Lbuild -lmyLib 也可以使用，但此明確指定可以避免與同名的動態函式庫混淆。)

   configure 腳本需要包含類似以下內容（對於 C 程式碼）

   : ${R_HOME=`R RHOME`}
   if test -z "${R_HOME}"; then
     echo "could not determine R_HOME"
     exit 1
   fi
   CC=`"${R_HOME}/bin/R" CMD config CC`
   CFLAGS=`"${R_HOME}/bin/R" CMD config CFLAGS`
   CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`
   LDFLAGS=`"${R_HOME}/bin/R" CMD config LDFLAGS`
   
   cd src
   mkdir build && cd build
   cmake ../libs \
     -DCMAKE_BUILD_TYPE=Release \
     -DBUILD_SHARED_LIBS:bool=OFF \
     -DCMAKE_POSITION_INDEPENDENT_CODE:bool=ON
   ${MAKE}
   

2. 使用 src/Makevars（或 src/Makevars.win 或 Makevars.ucrt）在子目錄中建置。它可以類似以下內容（對於 C 程式碼）

   PKG_CPPFLAGS = -Ilibs/include
   PKG_LIBS = libs/libmyLib.a
   
   $(SHLIB): mylibs
   
   mylibs:
           (cd libs; \
             CC="$(CC)" CFLAGS="$(CFLAGS)" \
             CPPFLAGS="$(CPPFLAGS)" LDFLAGS="$(LDFLAGS)" \
   	  cmake . \
   	    -DCMAKE_BUILD_TYPE=Release \
   	    -DBUILD_SHARED_LIBS:bool=OFF \
   	    -DCMAKE_POSITION_INDEPENDENT_CODE:bool=ON; \
   	  $(MAKE))
   
   

   編譯器和其他設定已由 INSTALL 在 src/Makevars 之前包含的 R makefile 設定為 Make 變數。

一個複雜的情況是，在 macOS 上 cmake（如果已安裝）通常不在路徑中，而是在 /Applications/CMake.app/Contents/bin/cmake。解決此問題的方法之一是讓套件的 configure 腳本包含

if test -z "$CMAKE"; then CMAKE="`which cmake`"; fi
if test -z "$CMAKE"; then CMAKE=/Applications/CMake.app/Contents/bin/cmake; fi
if test -f "$CMAKE"; then echo "no ‘cmake’ command found"; exit 1; fi

並讓第二種方法將 CMAKE 替換為 src//Makevars。

1.3.1 檢查套件 ¶

使用 R 套件檢查器 R CMD check，可以測試原始碼 R 套件是否運作正常。可以在一個或多個目錄，或壓縮套件 tar 檔案（副檔名為 .tar.gz、.tgz、.tar.bz2 或 .tar.xz）上執行。

強烈建議在由 R CMD build 準備的 tar 檔案上執行最後檢查。

這會執行一系列檢查，包括

1. 安裝套件。這會針對說明檔案中遺失的交叉參照和重複別名發出警告。
2. 檢查檔案名稱在不同檔案系統和支援作業系統平台上是否有效。
3. 檢查檔案和目錄的權限是否足夠（僅限類 Unix 系統）。
4. 檢查檔案是否有二進位執行檔，如果可用，會使用適當版本的 file⁵²。（可能會出現罕見的誤判。）
5. 會檢查 DESCRIPTION 檔案是否完整，並檢查部分條目是否正確。除非略過安裝測試，否則如果在執行時間無法解決套件相依性，檢查會中止。（如果相依套件在個別的函式庫樹中，您可能需要在環境中設定 R_LIBS。）其中一項檢查是套件名稱不能是標準套件的名稱，也不能是已廢止的標準套件的名稱（「ctest」、「eda」、「lqs」、「mle」、「modreg」、「mva」、「nls」、「stepfun」和「ts」）。另一項檢查是 library 或 require 中提到的所有套件，或 NAMESPACE 檔案從中匯入或 透過 :: 或 ::: 呼叫的套件，都必須列出（在「Depends」、「Imports」、「Suggests」中）：這並非對實際匯入的完整檢查。
6. 會檢查可用的索引資訊（特別是針對示範和範例）是否完整。
7. 檢查套件子目錄是否具有適當的檔案名稱且不為空。檔案名稱的檢查由選項 --check-subdirs=值 控制。預設為「預設」，僅在檢查 tarball 時執行檢查：預設值可透過指定值為「是」或「否」來覆寫。此外，僅在套件不包含 configure 程式碼（對應於值「是-可能」）且沒有 src/Makefile 或 src/Makefile.in 時，才會執行 src 目錄的檢查。

   若要允許 configure 程式碼產生適當的檔案，將允許 R 目錄中以「.in」結尾的檔案。

   對於看起來像 R 套件檢查目錄的目錄名稱，會發出警告，許多已提交至 CRAN 的套件都包含這些目錄。

8. 檢查 R 檔案是否有語法錯誤。非 ASCII 的位元組會報告為警告，但除非已知套件將始終在相同地區使用，否則應將這些視為錯誤。
9. 檢查套件是否可以載入，先使用一般的預設套件，然後僅在已載入套件 base 的情況下載入。檢查是否可以在僅載入 base 命名空間的空工作階段中載入命名空間。（命名空間和套件可以在工作階段的非常早期載入，在預設套件可用之前，因此套件應該在那時運作。）
10. 檢查 R 檔案是否正確呼叫 library.dynam。檢查套件啟動函數的引數清單是否正確，以及是否 (不正確地) 呼叫會修改搜尋路徑或不適當地產生訊息的函數。使用 codetools 檢查 R 程式碼是否有潛在問題。此外，檢查 S3 方法是否具有對應泛函的所有引數，以及替換函數的最後一個引數是否稱為「value」。測試所有外部函數呼叫 (.C、.Fortran、.Call 和 .External 呼叫) 是否有 PACKAGE 引數，如果沒有，是否可以從套件的命名空間推斷出適當的 DLL。報告任何其他呼叫。(檢查很寬鬆，使用者可能想要透過檢查 tools::checkFF("mypkg", verbose=TRUE) 的輸出結果來補充這一點，特別是在打算總是使用 PACKAGE 引數的情況下)
11. 檢查 Rd 檔案的語法和元資料是否正確，包括是否存在強制欄位 (\name、\alias、\title 和 \description)。檢查 Rd 名稱和標題是否非空，並檢查是否有遺失的交叉參照 (連結)。
12. 檢查是否有遺失的說明文件項目，例如套件中未記錄的使用者層級物件。
13. 檢查函數、資料集和 S4 類別的說明文件是否與對應的程式碼一致。
14. 檢查 Rd 檔案的 \usage 區段中給定的所有函數引數是否在對應的 \arguments 區段中記錄。
15. 檢查 data 目錄是否有非 ASCII 字元，以及是否使用合理的壓縮層級。
16. C、C++ 和 Fortran 原始碼和標頭檔⁵³ 經過測試，以確保可攜式（僅 LF）行尾。如果 src 目錄下有 Makefile 或 Makefile.in 或 Makevars 或 Makevars.in 檔案，則會檢查其可攜式行尾，以及是否正確使用「$(BLAS_LIBS)」和「$(LAPACK_LIBS)」

    已編譯的程式碼會檢查對應於函數的符號，這些函數可能會終止 R 或寫入 stdout/stderr，而不是寫入主控台。請注意，後者可能會產生誤報，因為符號可能會透過外部函式庫引入，但永遠不會被呼叫。Windows⁵⁴ 使用者應注意，Fortran 和 C++ 執行時期函式庫就是此類外部函式庫的範例。

17. 會對 inst/doc 目錄的內容進行一些檢查。這些檢查通常包括檢查看起來像是殘留檔案的檔案，以及如果可以使用合適的工具（例如 qpdf），則會檢查 PDF 文件的最小大小。
18. 會執行套件文件提供的範例。（請參閱 撰寫 R 文件，以取得有關如何使用 \examples 建立可執行範例程式碼的資訊。）如果有一個檔案 tests/Examples/pkg-Ex.Rout.save，則會將執行範例的輸出與該檔案進行比較。

    當然，已發佈的套件應該至少能夠執行自己的範例。每個範例都會在「乾淨的」環境中執行（因此無法假設已執行較早的範例），而且會重新定義變數 T 和 F，以產生錯誤，除非它們在範例中已設定：請參閱 R 簡介 中的 邏輯向量。

19. 如果套件來源包含 tests 目錄，則會執行該目錄中指定的測試。（通常會包含一組 .R 來源檔案和目標輸出檔案 .Rout.save。）請注意，比較會在最終使用者的區域設定中執行，因此目標輸出檔案應盡可能為 ASCII。（命令列選項 --test-dir=foo 可用於指定非標準位置的測試。例如，異常緩慢的測試可以放置在 inst/slowTests 中，然後使用 R CMD check --test-dir=inst/slowTests 來執行它們。其他建議的名稱例如，需要安裝 Oracle 的測試為 inst/testWithOracle，使用隨機值且偶爾可能會因機率而失敗的測試為 inst/randomTests，等等。）
20. 套件範例中的 R 程式碼（請參閱 撰寫套件範例）會執行，並且範例會從其來源重新製作，以檢查來源的完整性（除非套件的 DESCRIPTION 檔案中有具有 false 值的「BuildVignettes」欄位）。如果範例來源目錄中有目標輸出檔案 .Rout.save，則會將執行該範例中程式碼的輸出與目標輸出檔案進行比較，並報告任何差異（但不會記錄在記錄檔中）。（如果範例來源位於已棄用的位置 inst/doc，請標記此類目標輸出檔案，以不安裝在 .Rinstignore 中。）

    如果在範例 foo.ext 中執行 R 程式碼時發生錯誤⁵⁵，則會在檢查目錄中建立記錄檔 foo.ext.log。範例會在檢查目錄的 vign_test 子目錄中套件來源的副本中重新製作，因此有關錯誤的進一步資訊請查看目錄 pkgname/vign_test/vignettes。（僅在有錯誤或環境變數 _R_CHECK_CLEAN_VIGN_TEST_ 設為 false 值時才會保留。）

21. 套件手冊的 PDF 版本已建立（用來檢查 Rd 檔案是否能順利轉換）。這需要安裝 LaTeX 和合適的字型與 LaTeX 套件。請參閱 R 安裝與管理 中的 建立手冊。
22. 手冊的 HTML 版本（包含 R CMD check --as-cran）可選擇建立並檢查是否符合 HTML5 標準。這需要「HTML Tidy」的最新版本⁵⁶，可放在路徑中或由環境變數 R_TIDYCMD 指定位置。可從 http://binaries.html-tidy.org/ 安裝最新版本。

所有這些測試都會在校對設定為 C 區域設定的情況下執行，範例和測試則使用環境變數 LANGUAGE=en：這是為了將不同平台之間的差異降到最低。

使用 R CMD check --help 來取得有關 R 套件檢查器用法的更多資訊。可透過新增命令列選項來選取檢查步驟的子集。它也允許透過設定環境變數 _R_CHECK_*_ 來自訂，如 R 內部 中的 工具 所述：可透過選項 --as-cran 來選取一組自訂設定，類似 CRAN 所使用的設定（如果可使用網際網路，效果最佳）。某些 Windows 使用者可能需要將環境變數 R_WIN_NO_JUNCTIONS 設定為非空值。循環宣告⁵⁷ 的測試在 DESCRIPTION 檔案中需要設定儲存庫（包含 CRAN）：在 ~/.Rprofile 中執行此動作，例如：

options(repos = c(CRAN="https://r-cran.dev.org.tw"))

一個可能揭露問題的檢查自訂設定是

_R_CHECK_CODETOOLS_PROFILE_="suppressLocalUnused=FALSE"

報告未使用的區域指派。這不僅指出因結果未使用的計算是不必要的，還能揭露錯誤。（例如，兩個這樣的錯誤是打算透過指派值來更新物件，但錯打名稱或在錯誤的範圍內指派，例如使用 <-，而打算使用 <<-。）這可能會產生假陽性，最常見的原因是公式的非標準評估，以及打算在函數的環境中傳回物件以供稍後使用。

要完整檢查包含檔案 README.md 的套件，需要安裝相當新的 pandoc 版本：請參閱 https://pandoc.org/installing.html。

如果您包含非 ASCII 字元，則需要確保在適當的區域設定中檢查套件。此類套件可能會在 C 區域設定中無法通過某些檢查，而 R CMD check 會在發現問題時發出警告。您應該可以在 UTF-8 區域設定中檢查任何套件（如果有的話）。請注意，儘管 C 區域設定很少在主控台中使用，但如果遠端登入或進行批次作業，它可能是預設值。

通常 R CMD check 需要諮詢 CRAN 儲存庫來檢查已解除安裝套件的詳細資料。這通常預設為 CRAN 主要網站，但可以透過將環境變數 R_CRAN_WEB 和（很少需要）R_CRAN_SRC 設定為 CRAN 鏡像網站的 URL，來指定鏡像網站。

1.3.2 建立套件 tarball ¶

套件可以「tarball」（.tar.gz 檔案）的形式以原始碼形式發行，或以二進制形式發行。原始碼形式可以使用適當的工具安裝在所有平台上，而且是類 Unix 系統的常見形式；二進制形式是特定於平台的，而且是 Windows 和 macOS 平台較常見的發行形式。

使用 R 套件建構器 R CMD build，可以從其原始碼（例如，供後續發行）建立 R 套件 tarball。建議使用 R 的目前發行版本或「r-patched」來建立套件以供發行，以避免無意間選取 R 開發版本的新功能。

在標準的 gzip 壓縮 tar 檔案格式中實際建立套件之前，會執行一些診斷檢查和清理。特別會測試物件索引是否存在，以及是否可以假設為最新，並測試 src 目錄中的 C、C++ 和 Fortran 原始碼檔案以及相關的 makefile，並在必要時將其轉換為 LF 行尾。

在呼叫最後的建立程序之前，應該使用 R CMD check 執行執行時間檢查，以檢查套件是否正確運作。

若要排除檔案不放入套件中，可以在頂層原始碼目錄的 .Rbuildignore 檔案中指定一列排除模式。這些模式應為 Perl 式正規表示法（有關精確的詳細資訊，請參閱 R 中 regexp 的說明），每行一個，以不分大小寫的方式與頂層套件原始碼目錄相對應的檔案和目錄名稱進行比對。此外，預設會排除來自原始碼控制系統⁵⁸ 或 eclipse⁵⁹ 的目錄，名稱為 check、chm 或結尾為 .Rcheck、Old 或 old 的目錄，以及檔案 GNUMakefile⁶⁰、Read-and-delete-me 或基本名稱以「.#」開頭，或以「#」開頭和結尾，或以「~」、「.bak」或「.swp」結尾的檔案⁶¹。此外，同一個套件的 tarball（來自先前的建置）及其二進位形式會從頂層目錄中排除，而 R、demo 和 man 目錄中的那些檔案會被 R CMD check 標記為名稱無效。

使用 R CMD build --help 以取得有關 R 套件建置器的使用方式的更多資訊。

除非使用 --no-build-vignettes 選項呼叫 R CMD build（或套件的 DESCRIPTION 含有「BuildVignettes: no」或類似內容），否則它會嘗試（重新）建置套件中的範例（請參閱 撰寫套件範例）。為此，它會將目前的套件安裝到暫時函式庫樹狀結構中，但任何相依套件都需要安裝到可用的函式庫樹狀結構中（請參閱本節最上方的附註：）。

類似地，如果 .Rd 文件包含任何 \Sexpr 巨集（請參閱 動態頁面），套件將暫時安裝以執行它們。包含建置時間巨集的那些頁面的執行後二進位副本將儲存在 build/partial.rdb 中。如果存在任何安裝時間或呈現時間巨集，套件手冊的 .pdf 版本將建置並安裝在 build 子目錄中。（這允許 CRAN 或其他儲存庫顯示手冊，即使它們無法安裝套件。）這可以透過選項 --no-manual 或如果套件的 DESCRIPTION 包含 ‘BuildManual: no’ 或類似內容來取消。

R CMD build 執行的其中一項檢查是針對空的來源目錄。在大多數（但並非全部）情況下，這些都是無意的，如果它們是有意的，請使用選項 --keep-empty-dirs（或將環境變數 _R_BUILD_KEEP_EMPTY_DIRS_ 設定為 ‘TRUE’，或在 DESCRIPTION 檔案中有一個具有真值的 ‘BuildKeepEmpty’ 欄位）。

選項 --resave-data 允許在 data 目錄中儲存的影像（.rda 和 .RData 檔案）針對大小進行最佳化。它也會壓縮表格檔案，並將 .R 檔案轉換為儲存的影像。它可以接受的值為 no、gzip（如果未提供此選項，則為預設值，可透過設定環境變數 _R_BUILD_RESAVE_DATA_ 來變更）和 best（等於不提供值，會選擇最有效的壓縮方式）。如果任何檔案選用 bzip2 或 xz 壓縮，則使用 best 會在 DESCRIPTION 檔案中加入對 R (>= 2.10) 的依賴關係。如果這被認為是不理想的，--resave-data=gzip（如果未提供該選項，則為預設值）將使用 gzip 執行它所能執行的壓縮。套件可以透過在 DESCRIPTION 檔案中提供「BuildResaveData」欄位（包含本段落前面提到的其中一個值）來控制其資料的重新儲存方式。

選項 --compact-vignettes 會對 inst/doc（及其子目錄）中的 PDF 檔案執行 tools::compactPDF 以無損失地壓縮它們。這並非預設啟用（可透過環境變數 _R_BUILD_COMPACT_VIGNETTES_ 選擇），且需要 qpdf (https://qpdf.sourceforge.io/) 可用。

在已建置的 tarball 上執行 R CMD check --check-subdirs=yes 作為對內容的最終檢查會很有用。

如果使用不使用執行權限的非 POSIX 檔案系統，則需要小心處理權限。這適用於 Windows 和例如 FAT 格式化磁碟機和 SMB 掛載的其他作業系統上的檔案系統。tarball 中記錄的檔案「模式」將會是 file.info() 回傳的任何內容。在 Windows 上，這只會將目錄記錄為具有執行權限，而在其他作業系統上，所有檔案可能會報告「模式」0777。一個特殊的問題是在 Windows 上建置的套件，其中包含可執行腳本，例如 configure 和 cleanup：R CMD build 確保這兩個檔案以執行權限記錄。

套件來源的目錄 build 保留供 R CMD build 使用：它包含在安裝套件時可能無法輕鬆建立的資訊，包括小冊子的索引資訊，以及較少見的說明頁面資訊，可能還有 PDF 參考手冊的副本（請參閱上方）。

1.3.3 建置二進位套件 ¶

二進位套件是已安裝套件版本的壓縮副本。它們包含已編譯的共用函式庫，而不是 C、C++ 或 Fortran 原始碼，且 R 函式包含在它們已安裝的形式中。格式和檔名取決於平台；例如，Windows 的二進位套件通常提供為 .zip 檔案，而 macOS 平台的預設二進位套件檔案副檔名為 .tgz。

建置二進位套件的建議方式是使用

R CMD INSTALL --build pkg

其中 pkg 是原始 tarball 的名稱（採用一般的 .tar.gz 格式）或要建置的套件原始碼目錄的位置。這會先安裝套件，然後將已安裝的二進位檔打包到特定平台適用的二進位套件檔案中。

預設情況下，R CMD INSTALL --build 會嘗試將套件安裝到 R 本機安裝的預設函式庫樹狀結構中。這有兩個含意

• 如果安裝成功，它會覆寫同一個套件的任何現有安裝。
• 預設函式庫樹狀結構必須具有寫入權限；如果沒有，套件將不會安裝，而且不會建立二進位檔。

若要防止變更目前的作業安裝，或提供具有寫入存取權限的安裝位置，請建立一個具有寫入存取權限的適當位置目錄，並使用 -l 選項在所選位置建置套件。用法如下

R CMD INSTALL -l location --build pkg

其中 location 是具有寫入存取權限的所選目錄。套件會安裝為 location 的子目錄，而且套件二進位檔會在目前的目錄中建立。

使用 R CMD INSTALL --help 可以找到 R CMD INSTALL 的其他選項，而且特定案例的平台特定詳細資料會在平台特定的常見問答集中討論。

最後，至少有一項網路服務可用於從（已檢查的）原始碼建置二進位套件：WinBuilder（請參閱 https://win-builder.R-project.org/）能夠建置 Windows 二進位檔。請注意，這是針對其他平台上沒有 Windows 存取權限，但希望提供 Windows 平台二進位檔的開發人員。

1.4.1 編碼和範例 ¶

範例通常會包含說明性文字、R 輸入、R 輸出和數字、LaTeX 包含檔案和書目參考。由於其中任何一個都可能包含非 ASCII 字元，因此編碼的處理可能會變得非常複雜。

範例來源檔案應撰寫為 ASCII 或包含編碼宣告（請參閱下方）。這甚至適用於來源檔案內的註解，因為範例引擎會處理註解以尋找選項和元資料行。當引擎的編織和糾纏函數在範例來源上被呼叫時，它會被轉換為當前 R 工作階段的編碼。

Stangle() 會產生一個 R 程式碼檔案，使用目前區域設定的編碼：對於非 ASCII 的範例，會在檔案最上方的一則註解中記錄編碼。

Sweave() 會產生一個 .tex 檔案，使用目前的編碼，或是在宣告時使用 UTF-8。非 ASCII 編碼需要透過類似下列的程式碼宣告給 LaTeX

\usepackage[utf8]{inputenc}

（也可以使用較新的 LaTeX 套件「inputenx」。）對於不需要這行程式碼的檔案（例如包含在較大型文件主體中的章節，或非 Sweave 範例），可以使用類似下列的註解宣告編碼

%\VignetteEncoding{UTF-8}

如果編碼是 UTF-8，也可以使用下列宣告

%\SweaveUTF8

如果範例中沒有給定宣告，會假設使用套件宣告的編碼。如果在任一位置都沒有宣告編碼，則在範例中使用非 ASCII 字元會產生錯誤。

無論如何，請注意 LaTeX 可能需要「usepackage」宣告。

Sweave() 也會解析並評估每個區塊中的 R 程式碼。R 輸出也會使用目前的區域設定（或在宣告時使用 UTF-8），並且應該包含在「inputenc」宣告中。人們常忘記的一件事是，R 輸出可能不是 ASCII，即使對於 ASCII R 來源也是如此，原因可能有很多。一個常見的原因是使用「花俏」的引號：請參閱 R 說明中的 sQuote：請仔細注意，宣告 UTF-8 或 CP1252 來涵蓋此類引號並不可移植，因為其編碼會取決於用於執行 Sweave() 的區域設定：這可以用在範例中設定 options(useFancyQuotes="UTF-8") 來解決。

最後一個問題是圖形的編碼，這只適用於 PDF 圖形，不適用於 PNG 等。PDF 圖形會包含其編碼的宣告，但 Sweave 選項 pdf.encoding 可能需要適當地設定：請參閱 pdf() 圖形裝置的說明。

作為複雜性的實際範例，請考慮 fortunes 套件版本「1.4-0」。該套件沒有宣告編碼，且其範例在 ASCII 中。不過，它顯示的資料會從 UTF-8 CSV 檔讀取，並假設使用目前的編碼，因此 fortunes.tex 在任何區域設定中都將使用 UTF-8。如果已告知 read.table 資料是 UTF-8，則 fortunes.tex 將會使用區域設定的編碼。

1.4.2 非 Sweave 範例 ¶

以 Sweave 以外格式呈現的範例透過「範例引擎」獲得支援。例如 knitr 版本 1.1 或更新版本可以從 Sweave 格式的變體建立 .tex 檔，並從「標記」格式的變體建立 .html 檔。這些引擎會將 Sweave() 函式替換為其他函式，以將範例原始檔轉換成 LaTeX 檔，以便處理成 .pdf，或直接轉換成 .pdf 或 .html 檔。 Stangle() 函式會替換為從範例中擷取 R 原始碼的函式。

R 使用引擎指定的檔名副檔名來辨識非 Sweave 範例。例如，knitr 套件支援副檔名 .Rmd（代表「R 標記」）。使用者在範例原始碼中使用 \VignetteEngine 行來指出範例引擎，例如

%\VignetteEngine{knitr::knitr}

這會指定一個套件和一個引擎的名稱，用於處理範例中的 Sweave。由於 Sweave 是 R 散佈中提供的唯一引擎，因此提供任何其他引擎的套件必須在套件 DESCRIPTION 檔案的「VignetteBuilder」欄位中指定，並在「Suggests」、「Imports」或「Depends」欄位中指定（因為它的命名空間必須可用於建置或檢查您的套件）。如果指定多個套件作為建置器，它們將按照指定的順序進行搜尋。utils 套件始終會隱含附加到建置器套件清單中，但可能會在前面包含以變更搜尋順序。

請注意，具有非 Sweave 範例的套件應始終在 DESCRIPTION 檔案中有一個「VignetteBuilder」欄位，因為這是 R CMD check 辨識有範例需要檢查的方式：檢查套件時需要列出的套件。

範例引擎可以產生 .tex、.pdf 或 .html 檔案作為輸出。如果它產生 .tex 檔案，R 將呼叫 texi2pdf 將它們轉換為 .pdf 以供使用者顯示（除非 vignettes 目錄中有 Makefile）。

想要提供範例引擎的套件撰寫人員需要在套件 .onLoad 函式中註冊這些引擎。例如，該函式可以呼叫

tools::vignetteEngine("knitr", weave = vweave, tangle = vtangle,
                      pattern = "[.]Rmd$", package = "knitr")

（knitr 中的實際註冊比較複雜，因為它支援其他輸入格式。）有關引擎註冊的詳細資訊，請參閱 ?tools::vignetteEngine 說明主題。

1.5.1 指定匯入和匯出 ¶

使用 NAMESPACE 檔案中的 export 指令指定匯出。格式為

export(f, g)

指定變數 f 和 g 要匯出。（請注意變數名稱可以加上引號，保留字和非標準名稱（例如 [<-.fractions）必須加上引號。）

對於具有許多要匯出變數的套件，使用 exportPattern 搭配正規表示式來指定要匯出的名稱可能會更方便。指令

exportPattern("^[^\\.]")

匯出所有不以句點開頭的變數。但是，不建議在生產程式碼中使用如此廣泛的模式：最好列出所有匯出或使用定義範圍較窄的群組。（此模式適用於 S4 類別。）小心包含以句點開頭的名稱的模式：其中一些是僅限內部的變數，且不應匯出，例如「.__S3MethodsTable__.」（且載入會排除已知案例）。

套件會隱含匯入基礎名稱空間。需要從具有名稱空間的其他套件匯出的變數，必須使用指令 import 和 importFrom 明確匯入。import 指令會從指定的套件匯入所有匯出的變數。因此，指令

import(foo, bar)

指定要從套件 foo 和 bar 匯入所有匯出的變數。如果只需要的匯出變數只有幾個，則可以使用 importFrom 匯入。指令

importFrom(foo, f, g)

指定要從套件 foo 匯入匯出的變數 f 和 g。有選擇性地使用 importFrom 而不是 import 是良好的做法，特別是在從匯出超過十幾個變數的套件（尤其是別人寫的套件，因為它們的匯出內容未來可能會變更）匯入時建議這麼做。

若要從套件匯入每個符號，但有少數例外，請將 except 參數傳遞給 import。指令

import(foo, except=c(bar, baz))

從 foo 匯入每個符號，但 bar 和 baz 除外。except 的值應評估為可強制轉換為字元向量的內容，在將每個符號替換為其對應的字串後。

可以從已從其他名稱空間匯入的名稱空間匯出變數：這必須明確執行，而不是 透過 exportPattern。

如果套件僅需要其他套件中的幾個物件，它可以在程式碼中使用完全限定的變數參照，而不是正式匯入。套件 foo 中函數 f 的完全限定參照形式為 foo::f。這比正式匯入稍微沒那麼有效率，而且也失去了在 NAMESPACE 檔案中記錄所有依賴項的優點（但它們仍需要記錄在 DESCRIPTION 檔案中）。評估 foo::f 將導致套件 foo 被載入，但未附加，如果它尚未載入，這可能是延遲載入很少使用的套件的優點。但是，如果 foo 僅列在「Suggests」或「Enhances」中，這也延遲了檢查它是否已安裝：建議有條件地使用此類匯入（例如 via requireNamespace("foo", quietly = TRUE)）。

當套件需要使用多個命名空間中同名的函數時，將需要使用 foo::f 形式。

使用 foo:::f 而不是 foo::f 可以存取未匯出的物件。通常不建議這樣做，因為未匯出物件的存在或語意可能會在例行維護中被套件作者變更。

1.5.2 註冊 S3 方法 ¶

S3 類型的 UseMethod 調度標準方法可能無法找到已匯入但未附加至搜尋路徑的套件中定義的方法。為確保這些方法可用，定義方法的套件應確保已匯入泛型，並使用 S3method 指令註冊方法。如果套件定義函式 print.foo，打算用作類別 foo 的 print 方法，則指令

S3method(print, foo)

確保已註冊方法並可供 UseMethod 調度使用，且函式 print.foo 不需要匯出。由於泛型 print 定義於 base 中，因此不需要明確匯入。

（請注意，函式和類別名稱可以加上引號，保留字和非標準名稱（例如 [<- 和 function）必須加上引號。）

可以為 S3method 指定第三個引數，作為方法使用的函式，例如

S3method(print, check_so_symbols, .print.via.format)

當不需要 print.check_so_symbols 時。

從 R 3.6.0 開始，也可以使用 S3method() 指令執行延遲註冊。使用

if(getRversion() >= "3.6.0") {
    S3method(pkg::gen, cls)
}

函式 gen.cls 將僅在載入 pkg 的命名空間時，註冊為類別 cls 和泛型 gen 的 S3 方法。這可用於處理不需要「立即」使用的方法的情況，並且為了執行立即註冊而必須預先載入 pkg（及其所有強依賴項）的命名空間，這被認為太過繁瑣。

1.5.3 載入掛鉤 ¶

在載入、附加、分離和卸載套件時，會呼叫許多掛鉤。請參閱 help(".onLoad") 以取得更多詳細資料。

由於載入和附加是不同的操作，因此會為每個操作提供個別的掛鉤。這些掛鉤函數稱為 .onLoad 和 .onAttach。它們都接受參數⁶⁷ libname 和 pkgname；它們應該定義在命名空間中，但不要匯出。

當對套件呼叫 detach 時，套件可以使用 .onDetach 或 .Last.lib 函數（如果後者從命名空間匯出）。它會呼叫一個單一參數，即已安裝套件的完整路徑。還有一個掛鉤 .onUnload，它會在命名空間卸載時呼叫（經由呼叫 unloadNamespace，可能由 detach(unload = TRUE) 呼叫）參數為已安裝套件目錄的完整路徑。函數 .onUnload 和 .onDetach 應該定義在命名空間中，但不要匯出，但 .Last.lib 需要匯出。

套件不太可能需要 .onAttach（除了可能用於啟動橫幅）；設定選項和載入共用物件的程式碼應該放在 .onLoad 函數中，或使用下面說明的 useDynLib 指令。

使用者層級的掛鉤也可用：請參閱函數 setHook 的說明。

這些掛鉤通常使用不正確。人們忘記匯出 .Last.lib。編譯的程式碼應該載入到 .onLoad（或經由 useDynLb 指令：請參閱下方）並在 .onUnload 中卸載。請記住，套件的命名空間可以在未附加命名空間的情況下載入（例如，由 pkgname::fun），而且套件可以在其命名空間保持載入的狀態下卸載並重新附加。

這些函數保持安靜是很好的做法。任何訊息都應該使用 packageStartupMessage，以便使用者（包括檢查腳本）可以在需要時抑制它們。

1.5.4 useDynLib ¶

NAMESPACE 檔案可以包含一個或多個 useDynLib 指令，允許載入需要共用物件。⁶⁸ 指令

useDynLib(foo)

註冊共用物件 foo⁶⁹ 以 library.dynam 載入。註冊物件的載入會在套件程式碼載入後、執行載入掛勾函數前發生。只需要載入掛勾函數來載入共用物件的套件可以使用 useDynLib 指令。

useDynLib 指令也接受要透過 .C、.Call、.Fortran 和 .External 介面函數在 R 中使用的原生常式的名稱。這些名稱會作為指令的附加引數提供，例如：

useDynLib(foo, myRoutine, myOtherRoutine)

在 useDynLib 指令中指定這些名稱時，原生符號會在載入套件時解析，而且識別這些符號的 R 變數會以這些名稱新增到套件的命名空間。這些變數可以在 .C、.Call、.Fortran 和 .External 呼叫中用來取代常式的名稱和 PACKAGE 引數。例如，我們可以使用程式碼從 R 呼叫常式 myRoutine

 .Call(myRoutine, x, y)

而不是

 .Call("myRoutine", x, y, PACKAGE = "foo")

這種方法至少有兩個好處。首先，符號查詢僅對每個符號執行一次，而不是每次呼叫常式時執行。其次，這消除了解析可能存在於多個 DLL 中的符號的任何歧義。但是，這種方法現在已被棄用，取而代之的是提供註冊資訊（見下文）。

在某些情況下，套件中已經有一個 R 變數與原生符號同名。例如，我們可能在套件中有一個名為 myRoutine 的 R 函數。在這種情況下，有必要將原生符號對應到不同的 R 變數名稱。這可以在 useDynLib 指令中透過使用命名參數來完成。例如，要將原生符號名稱 myRoutine 對應到 R 變數 myRoutine_sym，我們將使用

useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)

然後，我們可以使用指令從 R 呼叫該常式

 .Call(myRoutine_sym, x, y)

沒有明確名稱的符號會指定給具有該名稱的 R 變數。

在某些情況下，最好不要在套件的命名空間中建立識別原生常式的 R 變數。如果許多這些常式不太可能被使用，則在載入套件時，為許多常式計算這些常式可能會太昂貴。在這種情況下，仍然可以使用 DLL 正確執行符號解析，但在每次呼叫常式時執行此操作。假設 DLL 作為 R 變數（例如 dll）被引用，我們可以使用表達式呼叫常式 myRoutine

 .Call(dll$myRoutine, x, y)

$ 函數會使用對 getNativeSymbol 的呼叫，在 DLL 中解析具有指定名稱的常式。這是與上述相同的運算，我們在套件載入時解析符號。唯一的不同是，在 dll$myRoutine 的情況中，每次都會執行此操作。

為了使用此動態方法（例如，dll$myRoutine），需要將 DLL 的參照作為套件中的 R 變數。可以透過使用上述用於將符號對應到 R 變數的 variable = dllName 格式，將 DLL 指定給變數。例如，如果我們想要將上述範例中 DLL foo 的 DLL 參照指定給變數 myDLL，我們會在 NAMESPACE 檔案中使用下列指令

myDLL = useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)

然後，R 變數 myDLL 會在套件的命名空間中，而且可以使用呼叫（例如 myDLL$dynRoutine）來存取在載入時未明確解析的常式。

如果套件有註冊資訊（請參閱 註冊原生常式），則我們可以直接使用它，而不用在 NAMESPACE 檔案的 useDynLib 指令中再次指定符號清單。註冊資訊中的每個常式會透過提供常式要指定的符號名稱，以及常式的位址和任何有關參數數量和類型的資訊，來指定。使用 useDynLib 的 .registration 參數，我們可以指示命名空間機制為這些符號建立 R 變數。例如，假設我們有下列針對名為 myDLL 的 DLL 的註冊資訊

static R_NativePrimitiveArgType foo_t[] = {
    REALSXP, INTSXP, STRSXP, LGLSXP
};

static const R_CMethodDef cMethods[] = {
   {"foo", (DL_FUNC) &foo, 4, foo_t},
   {"bar_sym", (DL_FUNC) &bar, 0},
   {NULL, NULL, 0, NULL}
};

static const R_CallMethodDef callMethods[] = {
   {"R_call_sym", (DL_FUNC) &R_call, 4},
   {"R_version_sym", (DL_FUNC) &R_version, 0},
   {NULL, NULL, 0}
};

然後，NAMESPACE 檔案中的指令

useDynLib(myDLL, .registration = TRUE)

會導致載入 DLL，而且也會在套件的命名空間中定義 R 變數 foo、bar_sym、R_call_sym 和 R_version_sym。

請注意，R 變數的名稱取自註冊資訊中的項目，不需要與原生例程的名稱相同。這允許註冊資訊的建立者將原生符號對應到 R 中不衝突的變數名稱，例如 R_version 對應到 R_version_sym，以便在 R 函數中使用，例如

R_version <- function()
{
  .Call(R_version_sym)
}

使用參數 .fixes 可以將自動前綴新增到已註冊的符號，這在使用現有套件時很有用。例如，套件 KernSmooth 有

useDynLib(KernSmooth, .registration = TRUE, .fixes = "F_")

這會建立對應到 Fortran 符號 F_bkde 等的 R 變數，並避免與命名空間中的 R 程式碼衝突。

注意：對於未註冊原生符號的套件，使用這些參數只會減慢套件的載入速度（儘管許多 CRAN 套件都已這麼做）。一旦符號註冊後，請檢查對應的 R 變數是否不會意外地透過 NAMESPACE 檔案中的模式匯出。

1.5.5 一個範例 ¶

舉例來說，考慮兩個名為 foo 和 bar 的套件。套件 foo 在檔案 foo.R 中的 R 程式碼為

x <- 1 f <- function(y) c(x,y) foo <- function(x) .Call("foo", x, PACKAGE="foo") print.foo <- function(x, ...) cat("<a foo>\n")

一些 C 程式碼定義一個 C 函數，編譯到 DLL foo（具有適當的副檔名）。此套件的 NAMESPACE 檔案為

useDynLib(foo) export(f, foo) S3method(print, foo)

第二個套件 bar 擁有程式碼檔案 bar.R

c <- function(...) sum(...) g <- function(y) f(c(y, 7)) h <- function(y) y+9

以及 NAMESPACE 檔案

import(foo) export(g, h)

呼叫 library(bar) 會載入 bar 並將其外銷附加至搜尋路徑。套件 foo 也會載入，但不會附加至搜尋路徑。呼叫 g 會產生

> g(6)
[1]  1 13

這與兩個設定中 c 的定義一致：在 bar 中，函式 c 定義為等同於 sum，但在 foo 中，變數 c 參考 base 中的標準函式 c。

1.5.6 具有 S4 類別和方法的命名空間 ¶

對於使用正式 (S4 風格) 類別和方法的套件，需要一些額外的步驟 (除非這些純粹是內部使用)。套件應在其 DESCRIPTION 中具有 Depends: methods 以及 import(methods) 或 importFrom(methods, ...)，加上需要外銷的任何類別和方法，需要在 NAMESPACE 檔案中宣告。例如，stats4 套件具有

export(mle) # exporting methods implicitly exports the generic
importFrom("stats", approx, optim, pchisq, predict, qchisq, qnorm, spline)
## For these, we define methods or (AIC, BIC, nobs) an implicit generic:
importFrom("stats", AIC, BIC, coef, confint, logLik, nobs, profile,
           update, vcov)
exportClasses(mle, profile.mle, summary.mle)
## All methods for imported generics:
exportMethods(coef, confint, logLik, plot, profile, summary,
              show, update, vcov)
## implicit generics which do not have any methods here
export(AIC, BIC, nobs)

所有在套件外使用的 S4 類別都需要列在 exportClasses 指令中。或者，它們可以使用 exportClassPattern⁷⁰ 指定，其樣式與 exportPattern 相同。若要從其他套件匯出泛型的函式，可以使用 exportMethods 指令。

請注意，在命名空間中匯出泛型函式也會匯出泛型，而在命名空間中匯出泛型也會匯出其函式。如果泛型函式不屬於此套件，可能是因為它作為泛型函式匯入，或因為非泛型版本已變成泛型，僅為了新增 S4 函式（例如上述範例中的 coef 函式），它可以透過 export 或 exportMethods（或兩者）宣告，但後者較為清楚（且用於上述 stats4 範例中）。特別是，對於原始函式，沒有泛型函式，因此 export 會匯出原始函式，這沒有意義。另一方面，如果泛型屬於此套件，使用 export() 匯出函式本身較為自然，而且必須執行此動作，如果建立隱含泛型而未設定任何函式（例如 stats4 中的 AIC）。

非本機泛型函式僅匯出以確保呼叫函式會從此套件調度函式（當函式為原始函式時，不會執行或不需要此動作）。因此，您不需要記錄此類隱含建立的泛型函式，而套件 tools 中的 undoc 也不會報告它們。

如果套件使用 S4 類別和從其他套件匯出的方法，但未匯入其他套件的整個命名空間⁷¹，則需要使用指令明確匯入類別和方法

importClassesFrom(package, ...)
importMethodsFrom(package, ...)

分別列出類別和具有方法的函數。假設我們有兩個小型套件 A 和 B，其中 B 使用 A。然後它們可以有 NAMESPACE 檔案

export(f1, ng1) exportMethods("[") exportClasses(c1)

和

importFrom(A, ng1) importClassesFrom(A, c1) importMethodsFrom(A, f1) export(f4, f5) exportMethods(f6, "[") exportClasses(c1, c2)

分別。

請注意，importMethodsFrom 也會匯入在這些方法的命名空間中定義的任何泛型。

如果您匯出 S4 方法，則對應的泛型可用非常重要。例如，您可能需要從 stats 匯入 coef，以顯示要轉換為其隱式泛型的函數。但建議使用 stats4 匯出的泛型，因為這允許多個套件在這些泛型上明確設定方法。

1.6.1 PDF 大小 ¶

有許多工具可供縮小 PDF 檔案大小：通常可以大幅縮小檔案大小，品質幾乎沒有損失或損失極小。大型檔案不僅佔用空間：它們會對 PDF 檢視器造成負擔，而且列印時可能需要花費好幾分鐘（如果它們可以列印的話）。

qpdf (https://qpdf.sourceforge.io/) 可以無失真壓縮。它相當容易取得（例如它有 Windows 的二進制檔和 Debian/Ubuntu/Fedora 的套件，並作為 R 的 CRAN macOS 發行版的一部分安裝）。R CMD build 有個選項可以在 inst/doc 下對 PDF 檔案執行 qpdf，如果節省至少 10Kb 和 10%，就取代它們。可以使用環境變數 R_QPDF 提供 qpdf 命令的完整路徑（並在 R 的 CRAN macOS 二進制檔中）。MiKTeX 似乎不使用 PDF 物件壓縮，因此 qpdf 可以大幅縮小其輸出的檔案大小：MiKTeX 的預設值可以透過 Sweave 或 LaTeX 檔案的前言中的程式碼覆寫 — 參閱 R 參考手冊在 https://svn.r-project.org/R/trunk/doc/manual/refman.top 中是如何執行的。

其他工具可以縮小含有過高解析度點陣圖影像的 PDF 檔案大小。這些影像通常最好重新產生（例如 Sweave 預設為 300 ppi，而 100–150 比較適合套件手冊）。這些工具包括 Adobe Acrobat（不是 Reader）、Apple 的 Preview⁹³ 和 Ghostscript（透過

ps2pdf options -dAutoRotatePages=/None -dPrinted=false in.pdf out.pdf

而適當的選項可能是

-dPDFSETTINGS=/ebook
-dPDFSETTINGS=/screen

請參閱 https://ghostscript.readthedocs.io/en/latest/VectorDevices.html 以取得更多資訊，並考量所有影像降採樣選項）。CRAN 套件中有一些範例，而 Ghostscript 的目前版本所產生的縮減幅度遠大於早期版本（例如從 9.50 升級到 9.52、從 9.55 升級到 9.56，再升級到 10.00.0）。

我們偶爾會遇到包含使用 PDF 向量圖形過於複雜圖形的超大型 PDF 檔：此類圖形通常最好重新設計，或若無法重新設計，則輸出為 PNG 檔。

選項 --compact-vignettes 至 R CMD build 的預設值為 ‘qpdf’：若要盡可能縮小檔案大小，請使用 ‘both’，前提是您有 Ghostscript 可用（請參閱 tools::compactPDF 的說明）。

1.6.2 檢查計時 ¶

有數種方法可找出檢查程序中花費時間的地方。首先將環境變數 _R_CHECK_TIMINGS_ 設為 ‘0’。這將報告總 CPU 時間（非 Windows）和安裝、執行範例、測試和範例的經過時間，若適當，則會在每個子架構下報告。對於測試和範例，它會報告每個測試和範例的時間，以及總時間。

將 _R_CHECK_TIMINGS_ 設定為正值會設定一個閾值（以秒為單位經過時間）以報告計時。

如果您需要更詳細地查看範例的計時，請使用選項 --timings 至 R CMD check（這由 --as-cran 設定）。這會為 CPU 或經過時間超過 5 秒的所有範例新增摘要至檢查輸出。它會產生一個包含每個說明檔案計時的檔案 mypkg.Rcheck/mypkg-Ex.timings：這是一個可以讀入 R 以進行進一步分析的 tab 分隔檔案。

測試和範例執行摘要會提供在對應日誌檔案的底部：請注意，只有在環境變數 _R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_ 設定為 true 值時，才會保留成功範例執行的日誌檔案。

1.6.3 編碼問題 ¶

此小節中的問題已經透過 R 4.2.0 中的變更大幅改善，在可用的地方以 UTF-8 區域設定執行 R 的 Windows 埠。然而，Windows 使用者可能會在較早版本的 Windows 上執行較早版本的 R，而不支援 UTF-8 區域設定。

如果您的套件包含非 ASCII 文字，則需要小心，特別是在打算在多個區域設定中使用時。可以在 DESCRIPTION 檔案和 .Rd 檔案中標記所使用的編碼，如本手冊的其他地方所討論。

首先，仔細考慮你是否真的需要非ASCII文字。有些 R 使用者只能正確查看其母語群組（例如西歐、東歐、簡體中文）和ASCII的文字。⁹⁴。其他字元可能根本無法呈現、呈現不正確，或導致你的 R 程式碼產生錯誤。對於.Rd文件，標記編碼並包含ASCII音譯可能可以做得很好。普遍支援的字元集比 2000 年左右更廣泛，但非拉丁字母（希臘文、俄文、喬治亞文等）仍然經常有問題，而那些具有雙寬字元（中文、日文、韓文、表情符號）的字元通常需要專業字型才能正確呈現。

幾個CRAN套件在其 R 程式碼中有法文訊息（少數有德文）。要解決這個問題，更好的方法是使用本手冊其他地方討論的國際化功能。

套件tools中的函式showNonASCIIfile可以協助在檔案中尋找非ASCII位元組。

在 R 程式碼中，有一個可攜式的方法可以在字元串（僅限）中放入任意文字，就是以 Unicode 的形式提供，例如「\uxxxx」跳脫字元（或較少需要，除了表情符號之外，「\Uxxxxxxxx」跳脫字元）。如果目前編碼中沒有任何字元，剖析器會將字元串編碼為 UTF-8，並標記為 UTF-8。這也適用於資料集中的字元串：它們可以使用「\uxxxx」跳脫字元準備，或在 UTF-8 區域設定中以 UTF-8 編碼，甚至可以透過 iconv() 轉換為 UTF-8。如果您這樣做，請確定您在 DESCRIPTION 檔案的「Depends」欄位中具有「R (>= 2.10)」（或更新版本）。

在非 UTF-8 區域設定中執行的 R 工作階段，如果可能，會重新編碼此類字串以顯示（例如，較舊版本的 Windows 中的 RGui 會執行此動作）。主控台/終端機和「X11()」與「windows()」等圖形裝置都需要選取或提供合適的字型⁹⁵。使用「postscript」或「pdf」會根據 UTF-8 區域設定的語言選擇預設的 8 位元編碼，而您的使用者需要知道如何選取「encoding」引數。

請注意，前兩段僅適用於 R 程式碼中的字元字串。非 ASCII 字元特別容易出現在註解中（套件的 R 程式碼、範例、測試、範例說明，甚至在 NAMESPACE 檔案中），但應避免在這些地方出現。最常見的情況是人們使用拉丁文-1 的 Windows 延伸字元（通常是單引號和雙引號、省略號、項目符號以及連字號和破折號），這些字元在嚴格的拉丁文-1 區域設定或 Windows 上的 CJK 區域設定中不受支援。一個令人意外的常見錯誤是用法是在「don't」中使用右引號，而不是正確的撇號。

資料集可以包含標記的 UTF-8 或拉丁文-1 字元字串。由於 R 現在不太可能在拉丁文-1 或 Windows 的 CP1252 區域設定中執行，因此基於效能考量，應將這些字元字串轉換為 UTF-8。

如果您要在類 Unix 系統上對套件執行 R CMD check，而該套件在其 DESCRIPTION 檔案中設定套件編碼 且未使用 UTF-8 區域設定，您可能需要 透過 環境變數 R_ENCODING_LOCALES 指定適當的區域設定。預設值等於值

"latin1=en_US:latin2=pl_PL:UTF-8=en_US.UTF-8:latin9=fr_FR.iso885915@euro"

（這適用於基於 glibc 的系統：macOS 需要 latin9=fr_FR.ISO8859-15），但如果目前的區域設定是 UTF-8，套件程式碼會轉譯為 UTF-8 以進行語法檢查，因此強烈建議在 UTF-8 區域設定中檢查。

1.6.4 可攜式 C 和 C++ 程式碼 ¶

撰寫可攜式 C 和 C++ 程式碼主要是遵守標準（C99、C++14 或宣告的 C++11/17/20）並測試是否支援擴充功能（例如 POSIX 函式）。請充分利用編譯器診斷功能，這通常表示對 C 和 C++ 使用標記 -Wall 和 -pedantic，並對 C 使用 -Werror=implicit-function-declaration 和 -Wstrict-prototypes（在某些平台和編譯器版本中，這些標記是 -Wall 或 -pedantic 的一部分）。

C++ 標準：從 3.6.0 版（Windows 上為 3.6.2 版）開始，R 預設為 C++11（如果可用）⁹⁶；從 R 4.1.0 版開始為 C++14，從 R 4.3.0 版開始為 C++17（如果可用）。然而，在較早的版本中，預設標準是所用編譯器的標準，通常為 C++98 或 C++14，而且預設標準可能會在未來更改。為了最大程度地提高可攜性，套件應指定標準（請參閱 使用 C++ 程式碼）或在 C++11、C++98、C++14 和 C++17 下進行測試。（指定 C++14 或更新版本會限制可攜性。）

請注意，「TR1」C++ 擴充功能不屬於任何這些標準，而且某些用於 R 的編譯器（包括 macOS 上的編譯器）未提供 <tr1/name> 標頭。（請改用 C++11 版本。）

一個常見的錯誤是假設編譯器或作業系統的版本較新。在生產環境中，「長期支援」版本的作業系統可能會使用多年，⁹⁷而且其編譯器在那段時間內可能不會更新。例如，GCC 4.8 在 2022 年仍在使用，並且可以在（RHEL 7 中）使用到 2028 年：這既不支援 C++14 也不支援 C++17。

POSIX 標準僅要求宣告最近定義的函式，如果某些巨集定義為足夠大的值，而且在某些編譯器/作業系統組合中，⁹⁸否則不會宣告函式。因此，您可能需要包含類似下列其中一個的內容

#define _XOPEN_SOURCE 600

或

#ifdef __GLIBC__
# define _POSIX_C_SOURCE 200809L
#endif

在任何標頭之前 (strdup、strncasecmp 和 strnlen 是此類函式 - 有幾個較舊的平台沒有 POSIX 2008 函式 strnlen。)

不過，有些常見錯誤值得在此指出。在 https://cplusplus.com/reference/ 或 https://en.cppreference.com/w/ 查詢函式並比較各種標準中定義的內容會很有幫助。

對於未由任何這些標準指定的函式（例如 mallinfo），需要更小心 - 希望系統上的 man 頁面會告訴您。在線上搜尋各種作業系統的此類頁面（最好至少包含 Linux 和 macOS，以及 https://man.freebsd.org/cgi/man.cgi 上的 FreeBSD 手冊頁面，讓您能選擇許多作業系統）應會揭露有用的資訊，但可能需要 configure 指令碼來檢查可用性和功能性。

編譯器和作業系統（透過系統標頭檔，即使對於名義上相同的作業系統，也會因架構而異）都會影響 C/C++ 程式碼的可編譯性。GCC、LLVM（clang 和 flang）、Intel 和 Oracle Developer Studio 套件的編譯器已與 R 搭配使用，LLVM clang 和 Oracle 都有一個以上的 C++ 標頭和函式庫實作。各種可能性使得全面的經驗檢查不可能，而且遺憾的是，編譯器在警告非標準程式碼方面充其量只是零星。

• 數學函式（例如 sqrt）在 C++11 中定義為浮點數引數：float、double、long double，可能還有更多。標準指定了整數型引數會發生什麼情況，但這並不總是實作的，導致報告「重載歧義」：這在 Solaris 上很常見，但對於 pow 也出現在 macOS 和使用 clang++ 的其他平台上。

  一個並不少見的問題是錯誤地呼叫 floor(x/y) 或 ceil(x/y) 對於 int 參數 x 和 y。由於 x/y 執行整數除法，結果的類型為 int，且可能回報「重載歧義」。有些人（徒勞無功地）呼叫 floor 和 ceil 針對整數類型的參數，這可能會產生「重載歧義」。

  一個令人驚訝的常見誤用是類似 pow(10, -3) 的東西：這應該是常數 1e-3。請注意，有常數（例如 M_SQRT2）定義 via Rmath.h⁹⁹ 針對 sqrt(2.0)，經常錯誤編碼為 sqrt(2)。

• 函數 fabs 僅定義於浮點類型，但 C++11 及更新版本例外，它們在 <cmath> 中針對 std::fabs 有針對整數類型的重載。函數 abs 定義於 C99 的 <stdlib.h> 針對 int，以及 C++ 的 <cstdlib> 針對整數類型，在 <cmath> 中針對浮點類型重載。C++11 在 <cmath> 中針對 std::abs 有針對整數類型的額外重載。呼叫 abs 搭配浮點類型的效果取決於實作：它可能會截斷為整數。為了清楚起見並避免編譯器警告，請對整數類型使用 abs，對雙精度值使用 fabs，且在使用 C++ 時包含 <cmath> 並使用 std:: 前綴。
• 呼叫巨集/函式 isnan、isinf 和 isfinite 對於整數引數來說是個錯誤（而且不太有意義，儘管已經看過），一些編譯器會給出編譯錯誤。函式 finite 已過時，一些編譯器會警告其使用¹⁰⁰。
• GNU C/C++ 編譯器支援大量的非可攜式擴充。例如，INFINITY（在 C99 和 C++11 中是一個 浮點 值），R 為其提供可攜式雙精度值 R_PosInf（以及 R_NegInf 表示 -INFINITY）。NAN¹⁰¹ 僅僅是一個 NaN 浮點 值：對於 R 的使用，NA_REAL 通常是預期的，但 R_NaN 也可用。

  一些（但不是全部）擴充列於 https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html 和 https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Extensions.html。

  其他讓套件撰寫者感到困擾的 GNU 擴充是使用非可攜式字元，例如識別碼中的 ‘$’ 和在 ext 下使用 C++ 標頭。

  項目在 C++ 程式碼中包含 C 式標頭並非可攜式。在 C++ 程式碼中包含舊式標頭¹⁰² math.h 可能會與 cmath 衝突，而後者可能由其他標頭包含。在 C++11 中，例如 sqrt 和 isnan 的函式定義於 math.h 中的 double 參數，以及 cmath 中包括 double 在內的範圍類型。對於 stdlib.h 和 cstdlib 也看過類似的問題。優先包含 C++ 標頭曾經是足夠的解決方法，但對於某些 2016 編譯器，只能包含其中一個。

• 請小心包含定義您所使用函式的標頭。某些編譯器/作業系統在其標頭中包含標準中未要求的其他系統標頭，因此程式碼可能在這些系統上編譯，但在其他系統上則不行。（一個顯著的範例是 C++ 標頭 <random>，它是由 g++ 間接包含在 <algorithm> 中。另一個問題是 C 標頭 <time.h>，它在 Linux 和 Windows 上由其他標頭包含，但在 macOS 上則不然。）g++ 11 通常需要明確包含 C++ 標頭 <limits>（對於 numeric_limits）或 <exception>（對於 set_terminate 和類似函式），而較早版本則將這些包含在其他標頭中。g++ 13 需要明確包含 <cstdint> 以取得類型，例如 uint32_t，而這以前是隱含包含的。（更多此類資訊，請參閱 https://gcc.gnu.org/gcc-13/porting_to.html。）

  請注意，malloc、calloc、realloc 和 free 由 C99 在標頭 stdlib.h 中定義，並由 C++ 標頭 cstdlib（在 std:: 命名空間中）定義。一些較早的實作使用標頭 malloc.h，但這不可移植，且在 macOS 上不存在。

  這也適用於 ssize_t 等類型。POSIX 標準表示在標頭 unistd.h 和 sys/types.h 中宣告，後者通常會在某些系統（但並非所有系統）中由其他標頭間接包含。

  常數也類似：例如 SIZE_MAX 與 size_t 一起在 stdint.h 中定義。

• 有些標頭不可移植：我們剛剛提到 malloc.h，而且 CRAN 提交通常會嘗試使用 endian.h。後者是 glibc 延伸：有些作業系統有 machine/endian.h 或 sys/endian.h，但有些作業系統兩個都沒有。
• 對於套件中的標頭，請使用 #include "my.h"，而非 #include <my.h>。第二種形式是針對系統標頭，而且此類標頭的搜尋順序與平台相關（且可能不包含目前目錄）。為了更安全，請以不會與系統標頭混淆的方式命名標頭，因此不要使用 types.h 等。
• 對於 C++ 程式碼，請小心在需要時指定命名空間。許多函式由標準定義在 std 命名空間中，但 g++ 也將許多此類函式放入 C++ 主命名空間中。一種執行此動作的方式是使用宣告，例如

  using std::floor;
  

  但通常較好的是在程式碼中使用明確的命名空間前置詞。

  CRAN 套件中看到的範例包括

  abs acos atan bind calloc ceil div exp fabs floor fmod free log malloc
  memcpy memset pow printf qsort round sin sprintf sqrt strcmp strcpy
  strerror strlen strncmp strtol tan trunc
  

  這個問題比以前少見，但 2019 年的 LLVM clang 在主命名空間中沒有 bind。也曾見過僅在 std 命名空間中定義的類型 size_t。

  注意：這些函式僅保證在包含正確的 C++ 標頭時才會出現在 std 命名空間中，例如 <cmath> 而不是 <math.h>。

  如果您在 C++ 中定義受後續標準啟發的函式，請將它們放在命名空間中，並使用命名空間來參照它們。我們已經看到 C++14 中的 std::make_unique 與 C++17 中的 std::byte、std::data、std::sample 和 std::size 發生衝突。

• 在 C++ 程式碼中

  using namesapace std; 
  

  並非良好的實務，且如果在標頭之前包含，特別是系統標頭（可能由其他標頭包含），則會導致與平台相關的錯誤。最佳實務是對 C++ 標準宣告在該命名空間中的所有函式使用明確的 std:: 前置詞。

• 有些 C++ 編譯器拒絕編譯類似於

        if(ptr > 0) { ....}
  

  的建構，它將指標與整數 0 進行比較。這可以使用 if(ptr)（指標位址不能為負值）來使用，但如果需要，可以針對 nullptr（C++11）或 NULL 測試指標。

• 編譯器/作業系統定義的巨集可能會造成問題。以底線開頭，後接大寫字母或另一個底線的識別碼是保留給系統巨集的，不應在可攜式程式碼中使用（包括不作為 C/C++ 標頭中的防護）。其他巨集，通常是大寫，可能會由編譯器或系統標頭定義，並可能造成問題。其中一些問題可以透過在包含任何系統標頭之前定義 _POSIX_C_SOURCE 來避免，但最好只使用具有唯一前置詞（例如套件名稱）的全大寫名稱。
• OS 標頭中的 typedef 可能會與套件中的 typedef 衝突：範例包括 ulong、index_t、single 和 thread。（請注意，這些可能會與其他用途作為識別碼衝突，例如定義稱為 single 的 C++ 函數。）POSIX 標準（在 §2.2.2 中）保留所有以 _t 結尾的識別碼。
• 有些編譯器不允許 -D 和要定義的巨集之間有空格。-U 也類似。
• 如果您使用 OpenMP，請仔細檢查您是否已遵循 OpenMP 支援 小節中的建議。特別是，在 C/C++ 程式碼中使用 OpenMP 將需要使用

  #ifdef _OPENMP
  # include <omp.h>
  #endif
  

  任何使用 OpenMP 函數（例如 omp_set_num_threads）也需要加上條件。為避免不斷出現以下警告，例如

  warning: ignoring #pragma omp parallel [-Wunknown-pragmas]
  

  此類指令的用途也應加上條件（或是在套件中不啟用任何平台上的 OpenMP 的程式碼中將其註解掉）。

  不要硬編碼 -lgomp：這不僅限於 GCC 編譯器系列，使用正確的連結器旗標通常會設定執行時期路徑至函式庫。

• 套件作者通常假設某些內容是 C/C++ 的一部分，但事實並非如此：最常見的範例是 POSIX¹⁰³ 函數 strdup。Linux 上最常見的 C 函式庫 glibc 會隱藏此類延伸的宣告，除非在包含（幾乎）任何系統標頭 之前 定義「功能測試巨集」。因此，對於 strdup，您需要

  #define _POSIX_C_SOURCE 200809L
  ...
  #include <string.h>
  ...
  strdup call(s)
  

  適當的值可以在 Linux 上透過 man strdup 找到。（strncasecmp 的用法類似。）

  然而，具有「GNU 擴充功能」的 gcc 模式（預設為 -std=gnu99 或 -std=gnu11）宣告足夠的巨集，以確保很少會看到遺漏的宣告。

  這也適用於常數，例如 M_PI 和 M_LN2，它們是 X/Open 標準的一部分：若要使用這些定義，請在包含任何標頭之前定義 _XOPEN_SOURCE，或包含 R 標頭 Rmath.h。

• 可攜式地使用 alloca 很棘手：它既不是 ISO C/C++，也不是 POSIX 函式。充分可攜式的序言為

  #ifdef __GNUC__
  /* Includes GCC, clang and Intel compilers */
  # undef alloca
  # define alloca(x) __builtin_alloca((x))
  #elif defined(__sun) || defined(_AIX)
  /* this was necessary (and sufficient) for Solaris 10 and AIX 6: */
  # include <alloca.h>
  #endif
  

• 編譯器撰寫者可以自由實作比指定標準更新的功能，因此例如當指定 C++11 時，他們可能會實作或警告 C++14/17/20 功能。可攜式程式碼不會使用此類功能——很難知道它們是什麼，但最常見的警告為

  'register' storage class specifier is deprecated and incompatible with C++17
  
  ISO C++11 does not allow conversion from string literal to ‘char *’
  

  （其中轉換應為 const char *）。關鍵字 register 未在 C++98 中提及，在 C++11 中已棄用，並在 C++17 中移除。

  在 C++11 中已棄用並在 C++17 中移除的 C++98 功能還有很多，而 LLVM clang 9 及更新版本會對它們發出警告（自版本 16 起已移除）。範例包括 bind1st/bind2nd（使用 std::bind 或 lambda¹⁰⁴）std::auto_ptr（已由 std::unique_ptr 取代）、std::mem_fun_ref 和 std::ptr_fun。

• 後續版本的標準可能會新增保留字：例如 bool、false 和 true 在 C23 中已成為關鍵字，不再可用作變數名稱。如上所述，C++17 使用 byte、data、sample 和 size。

  因此，請避免使用其他程式語言中的常見字詞和關鍵字。

• 小心在 C++ 程式碼中包含 C 標頭。問題包括
  • 使用 register 儲存類別指定詞（請參閱前一個項目）。
  • C99 關鍵字 restrict 不是任何 C++ 標準的一部分¹⁰⁵，且會遭某些 C++ 編譯器拒絕。
  • 透過此類標頭包含 C 風格標頭，例如 math.h（請參閱上方）。

  與具有 C API 的其他軟體介接的最可移植方式是使用 C 程式碼（通常可以在套件中與 C++ 程式碼混合使用）。

• C++ 中的 reinterpret_cast 對指標不安全：例如，類型可能有不同的比對需求。使用 memcpy 將內容複製到目標類型的全新變數。
• 如果可能，請避免使用特定於平台的程式碼，但如果您需要測試平台，請確保涵蓋所有平台。例如，__unix__ 並未定義在所有類 Unix 系統上，特別是在 macOS 上沒有定義。為類 Unix 系統設定條件程式的合理可移植方式為

  #if defined (__unix__) || (defined (__APPLE__) && defined (__MACH__))
  #endif
  

  但

  #ifdef _WIN32
  // Windows-specific code
  #else
  // Unix-alike code
  #endif
  

  會更好。對於類 Unix 系統，最好使用 configure 來測試所需功能，而不是假設作業系統（而且人們常常忘記 R 也用於 Linux、Windows 和 macOS 以外的平台，有些人則忘記 macOS）。

• 子目錄中的標頭通常不可移植。對於 C++，這包括 bits/、tr1/ 和 tr2/，這些標頭都不存在於 macOS 中（而 ext/ 存在於 macOS 中，但其內容與基於 g++ 的平台不同）。標頭 bits/stdc++.h 不可移植，即使在包含它的平台上也不建議用於最終用戶程式碼。
• 使用 malloc 或 calloc 時要小心。首先，必須始終檢查其回傳值以查看配置是否成功 - 使用 R 的 R_Calloc 通常更容易，因為它會進行檢查。其次，第一個引數的類型為 size_t，最近的編譯器會警告傳遞有號引數（可能會提升為極大的值）。
• 對於 C 程式碼，考慮使用 gcc、LLVM 和 Apple clang 支援的標記 -Wstrict-prototypes。這已找出許多函式未宣告引數的錯誤，而且可能會成為未來編譯器的預設值。（對於 C23 模式下的 LLVM clang 來說，它已經是預設值。）請注意，在 C99 和 C11 中，使用 f() 表示沒有任何參數的函式已被棄用，但預計在 C23 中不會被棄用。然而，f(void) 受所有標準支援，且可避免任何不確定性。

  LLVM clang 有另一個警告 -Wdeprecated-non-prototype，它是由 -Wstrict-prototypes 啟用的。這會對 K&R 風格的使用發出警告，而這在 C23 中將不被接受。

• 大多數系統的 man 頁面都會警告不要使用幾個 C 進入點，通常用非常強烈的措辭，例如「不要使用這些函數」。macOS 已開始警告¹⁰⁶，如果這些函數用於 sprintf、vsprintf、gets、mktemp、tempmam 和 tmpnam。強烈建議您使用更安全的替代方案（在任何平台上），但可以在包含定義它們的（C 或 C++）標頭之前，將「_POSIX_C_SOURCE」定義為例如「200809L」來避免警告。（但是，這可能會隱藏其他擴充功能。）
• 編譯器可能會解釋原始碼中的註解，因此有必要移除任何供編譯器解釋的註解。主要範例是 Visual Fortran 的註解（因為 Intel Fortran 編譯器在 Windows¹⁰⁷ 上已廣為人知），例如

  !DEC$ ATTRIBUTES DLLEXPORT,C,REFERENCE,ALIAS:'kdenestmlcvb' :: kdenestmlcvb
  

  這些註解會在所有平台上由 Intel Fortran 解釋（而且不適合與 Windows 上的 R 搭配使用）。gfortran 有類似的形式，從 !GCC$ 開始。

• C++ new 運算子採用引數 std::size_t size，它是未簽署的。使用有符號的整數類型，例如 int，可能會導致編譯器警告，例如

  warning: argument 1 value ‘18446744073709551615’ exceeds maximum object
    size 9223372036854775807  [-Walloc-size-larger-than=]
  

  （特別是在使用 LTO 時）。所以不要這麼做！

Martyn Plummer 在 https://journal.r-project.org/archive/2011-2/RJournal_2011-2_Plummer.pdf 提供了 C++ 的一些其他資訊。

• 常見符號
• C++17 問題

#define extern
# include "globals.h"
#undef extern

-D_HAS_AUTO_PTR_ETC=0

std::auto_ptr
std::unary_function
std::binary_function
std::random_shuffle
std::binder1st
std::binder2nd

BOOST_MPL_AUX_STATIC_CAST(AUX_WRAPPER_VALUE_TYPE, (value - 1));

 -Wno-error=enum-constexpr-conversion

CXX="/path/to/clang/clang++ -std=gnu++17 -stdlib=libc++"

1.6.5 可攜式 Fortran 程式碼 ¶

多年來，幾乎所有已知的 R 平台都使用 gfortran 作為 Fortran 編譯器，但現在有 LLVM 和「傳統」flang，而 Intel 編譯器 ifort¹¹¹ 和 ifx 現在免費提供。

在 CRAN 套件中仍有許多 Fortran 程式碼早於 Fortran 77。現代 Fortran 編譯器撰寫時以 Fortran 2018 最低標準為目標，而套件中的 Fortran 程式碼最好符合該標準。對於 gfortran，可以透過將 -std=f2018 加入 FFLAGS 來檢查。最常見的問題是

• 使用 DFLOAT，它在 Fortran 77 中已被 DBLE 取代。此外，使用 DCMPLX、DCONJG、DIMAG 和類似的程式碼。
• 使用 GNU Fortran 延伸。有些列於 https://gcc.gnu.org/onlinedocs/gfortran/Extensions-implemented-in-GNU-Fortran.html。其他造成問題的程式碼包括 etime、getpid、isnan¹¹² 和 sizeof。

  一個經常困擾套件撰寫者的問題是，它允許無序宣告：在符合標準的 Fortran 中，變數必須在其他宣告（例如維度）中使用之前宣告（明確或隱含）。

不幸的是，這會標記 DOUBLE COMPLEX 和 COMPLEX*16 等延伸。R 已測試過 DOUBLE COMPLEX 可行，因此優先於 COMPLEX*16。（也可以使用類似 COMPLEX(KIND=KIND(0.0D0)) 的程式碼。）

GNU Fortran 10 及更新版本會針對以前廣泛使用的做法產生編譯錯誤，例如傳遞預期陣列的 Fortran 陣列元素，或傳遞純量而非長度為一的陣列。請參閱 https://gcc.gnu.org/gcc-10/porting_to.html。Intel Fortran 編譯器也會這樣做，而且它們可能會更嚴格。

強烈建議使用 IMPLICIT NONE – 使用 -warn 的 Intel 編譯器會針對沒有明確類型的變數發出警告。

常見的非可攜式結構包括

• 使用諸如 REAL(KIND=8) 之 Fortran 類型非常不利於移植。根據標準，這僅列舉不同的支援類型，因此 DOUBLE PRECISION 可能為 REAL(KIND=3)（且為實際編譯器）。即使對於特定編譯器，值表示以位元組為單位的尺寸，支援的值也與平台有關，例如 gfortran 在所有當前平台上支援 4 和 8 的值，在少數平台上支援 10 和 16（但例如不支援所有「arm」CPU）。

  相同情況適用於 INTEGER(KIND=4) 和 COMPLEX(KIND=16)。

  在套件中，Fortran 程式碼中許多使用整數和實數變數會與 C 互通（例如 .Fortran 以 C 編寫），且 R 已檢查 INTEGER 和 DOUBLE PRECISION 對應於 C 類型 int 和 double。為了明確表示這一點，從 Fortran 2003 起，可以使用模組 iso_c_binding 中的名稱常數 c_int、c_double 和 c_double_complex。

• Intel 編譯器僅辨識副檔名 .f（固定格式）和 .f90（自由格式）的擴充功能，而不辨識 .f95。對於沒有 src/Makefile 的套件，R CMD INSTALL 會解決此問題。
• 使用副檔名 .F 和 .F90 來表示要預處理的原始程式碼：使用的預處理器與編譯器有關，可能是 cpp，也可能不是。
• 固定格式 Fortran（擴充名為 .f）應僅使用 72 個欄位，而自由格式最多使用 132 個欄位。這包括尾端註解。過長的列可能會在未通知的情況下被截斷或產生警告。%% Intel 編譯器會發出警告。

1.6.6 二進位發行 ¶

如果您想在 Windows 或 macOS 上發行套件的二進位版本，您需要執行進一步的檢查以確認其可攜性：過於依賴您自己的機器上其他使用者可能沒有的外部軟體。

對於 Windows，請檢查套件的 DLL 依賴哪些其他 DLL（DLL 工具術語中的「匯入」）。一個方便的 GUI 工具是「Dependency Walker」（https://www.dependencywalker.com/），適用於 32 位元和 64 位元 DLL – 請注意，它會報告 R 自身 DLL 的遺失連結，例如 R.dll 和 Rblas.dll。適當工具鏈中的命令列工具 objdump 也會顯示匯入哪些 DLL。如果您使用 R 開發人員提供的工具鏈以外的工具鏈，或使用您自己的 makefile，請特別注意對工具鏈執行時期 DLL 的依賴性，例如 libgfortran、libstdc++ 和 libgcc_s。

對於 macOS，在 libs 目錄中的套件共用物件上使用 R CMD otool -L 會顯示它們依賴的項目：注意 /usr/local/lib 或 /usr/local/gfortran/lib 中的任何依賴項，特別是 libgfortran.?.dylib 和 libquadmath.0.dylib。（有關如何修正這些問題的方法，請參閱 R 安裝與管理 中的 建立二進制套件。）

許多人（包括 CRAN 套件儲存庫）不接受包含二進制檔案的原始程式碼套件，因為後者有安全風險。如果您想要散布需要 Windows 或 macOS 上外部軟體的原始程式碼套件，選項包括

• 安排套件安裝從 URL 下載額外的軟體，例如套件 Cairo 過去所使用的。
• 與 Tomas Kalibera 協商在 Rtools 中包含 Windows 軟體，或與 Simon Urbanek 協商在他的「配方」系統中包含 macOS 軟體。
• （對於 CRAN。）與 Uwe Ligges 協商在 WinBuilder 上主機額外的組件，並撰寫 configure.win 檔案來安裝它們。

請注意，您可能需要提供額外組件的原始程式碼的授權需求（如果您的套件有類似 GPL 的授權，則需要提供）。

1.8.1 C 層級訊息 ¶

啟用翻譯的程序是

• 在標頭檔中，將包含在所有包含應翻譯訊息的 C（或 C++ 或 Objective C/C++）檔案中，宣告

  #include <R.h>  /* to include Rconfig.h */
  
  #ifdef ENABLE_NLS
  #include <libintl.h>
  #define _(String) dgettext ("pkg", String)
  /* replace pkg as appropriate */
  #else
  #define _(String) (String)
  #endif
  

• 對於每個應翻譯的訊息，將其包覆在 _(...) 中，例如

  error(_("'ord' must be a positive integer"));
  

  如果您想對單數和複數形式使用不同的訊息，您需要新增

  #ifndef ENABLE_NLS
  #define dngettext(pkg, String, StringP, N) (N == 1 ? String : StringP)
  #endif
  

  並以標記字串

  dngettext("pkg", <singular string>, <plural string>, n)
  

• 在套件的 src 目錄中執行

  xgettext --keyword=_ -o pkg.pot *.c
  

檔案 src/pkg.pot 是範本檔案，且通常會以 po/pkg.pot 的形式出貨。

1.8.2 R 訊息 ¶

機制也可用於支援 R stop、warning 和 message 訊息的自動翻譯。它們使用訊息目錄的方式與 C 層級訊息相同，但使用網域 R-pkg 而不是 pkg。在 stop、warning 和 message 呼叫內部字元字串的翻譯會自動啟用，以及封裝在 gettext 或 gettextf 呼叫中的其他訊息。（若要抑制此功能，請使用參數 domain=NA。）

準備 R-pkg.pot 檔案的工具在 tools 套件中提供：xgettext2pot 會從所有出現在 gettext/gettextf、stop、warning 和 message 呼叫中的字串準備一個檔案。其中有些可能是無效的，因此檔案可能需要手動編輯。xgettext 會萃取實際呼叫，因此在整理錯誤訊息時會更有用。

R 函數 ngettext 提供一個與同名 C 函數的介面：請參閱前一節的範例。在呼叫 ngettext 時，最安全的方法是明確使用 domain="R-pkg"，而且對於較早版本的 R 來說是必要的，除非它們是直接從套件中的函數呼叫。

1.8.3 準備翻譯 ¶

一旦範本檔案建立完成，就可以進行翻譯。傳統的翻譯檔案副檔名為 .po，並放置在套件的 po 子目錄中，其名稱為 ‘ll.po’ 或 ‘R-ll.po’，分別對 C 和 R 訊息翻譯成代碼為 ‘ll’ 的語言。

請參閱 R 安裝和管理 中的 訊息在地化，以取得語言代碼的詳細資料。

套件 tools 中有一個 R 函數 update_pkg_po，可自動執行大部分訊息翻譯的維護工作。有關其詳細功能，請參閱其說明。

如果在沒有現有翻譯的套件上呼叫此函數，它會建立目錄 pkgdir/po，在其中建立 R 訊息範本檔案 pkgdir/po/R-pkg.pot，建立「en@quot」翻譯並安裝它。（「en@quot」偽語言會在適當的 (例如 UTF-8) 區域設定中以其方向形式詮釋引號。）

如果套件在標記為翻譯的 src 目錄中有 C 原始檔，請使用

touch pkgdir/po/pkg.pot

建立一個虛擬範本檔，然後再次呼叫 update_pkg_po（這也可以在第一次呼叫之前執行）。

當在 pkgdir/po 目錄中新增新語言的翻譯時，執行相同的指令會檢查並安裝翻譯。

如果套件來源已更新，相同的指令會更新範本檔，將變更合併到翻譯 .po 檔中，然後安裝已更新的翻譯。您經常會看到合併會將翻譯標記為「模糊」，這會在涵蓋率統計中報告。由於模糊翻譯不會使用，這表示翻譯檔需要人工處理。

合併的翻譯會透過 tools::checkPofile 執行，以檢查 C 式格式是否正確使用：如果沒有，會報告不符，且不會安裝損壞的翻譯。

此函式需要安裝並將 GNU gettext-tools 放置於路徑中：請參閱其說明頁面。

1.10.1 前端 ¶

這是一個相當通用的機制，用於新增新的前端，例如之前的 gnomeGUI 套件（請參閱 CRAN 上的 Archive 區域）。如果在套件的最上層目錄中找到 configure 檔案，則會執行該檔案，然後如果找到 Makefile（通常由 configure 產生），則會呼叫 make。如果使用 R CMD INSTALL --clean，則會呼叫 make clean。不會執行其他動作。

R CMD build 可以封裝此類型的延伸套件，但 R CMD check 會檢查類型並略過它。

許多此類型的套件需要 R 安裝目錄的寫入權限。

2.1.1 文件化函式 ¶

用於文件化 R 物件（特別是函式）的基本標記命令在此小節中提供。

\name{名稱} ¶

名稱 通常¹¹⁴是包含文件檔的 Rd 檔案的基本檔名。它是檔案所代表的 Rd 物件的「名稱」，而且在套件中必須是唯一的。為避免套件手冊索引的問題，它不能包含「!」、「|」或「@」，而且為避免 HTML 說明系統可能出現的問題，它不應包含「/」或空白。（允許使用 LaTeX 特殊字元，但索引中可能無法正確整理。）一個檔案中只能有一個 \name 項目，而且它不能包含任何標記。套件手冊中的項目將按照 \name 項目的字母順序¹¹⁵排列。

\alias{主題} ¶

\alias 區段會指定檔案文件中的所有「主題」。此資訊會收集到索引資料庫中，供線上（純文字和 HTML）說明系統查詢。 主題 可以包含空白，但（基於歷史原因）開頭和結尾的空白會被移除。百分比和左大括號需要用反斜線進行跳脫。

可能會有多個 \alias 項目。通常在一個檔案中文件化多個 R 物件會比較方便。例如，檔案 Normal.Rd 會文件化常態分佈的密度、分配函數、分位數函數和隨機變異的產生，因此會從以下開始

\name{Normal}
\alias{Normal}
\alias{dnorm}
\alias{pnorm}
\alias{qnorm}
\alias{rnorm}

此外，通常會用多種不同的方式來指稱一個 R 物件會比較方便，而且 \alias 不需要是物件的名稱。

請注意， \name 不一定會是文件化的主題，如果需要，則需要有明確的 \alias 項目（如同此範例）。

\title{標題} ¶

Rd 檔案的標題資訊。此資訊應以大寫字母開頭，且不應以句點結尾；為了最廣泛的相容性，請盡量將其長度限制在 65 個字元以內。

文字中支援標記，但使用英文文字和標點符號以外的字元（例如「<」）可能會限制可攜性。

說明檔案中必須有一個（且僅有一個） \title 區段。

\description{…} ¶

函數執行功能的簡短說明（一段落，僅數行）。（如果說明太長且無法輕易縮短，則檔案可能試圖一次文件化太多內容。）這是強制性的，套件概觀檔案除外。

\usage{函數(參數1, 參數2, …)} ¶

顯示檔案中函數和變數概要的一或多行。這些內容以打字機字型設定。這是一個類似 R 的指令。

指定的用法資訊應與函數定義完全相符（如此才能自動檢查程式碼和文件之間的一致性）。

若要指出函數可以根據指定的命名參數以多種不同的方式使用，請使用區段 \details。例如，abline.Rd 包含

\details{
  Typical usages are
\preformatted{abline(a, b, ...)
......
}

使用 \method{泛函}{類別} 指出繼承自類別 "類別" 物件的泛函函數 泛函 的 S3 方法名稱。在列印版本中，這將顯示為 泛函（反映出方法不應直接呼叫，而應透過方法調用），但 codoc() 和其他品質控管工具始終可以存取完整名稱。

例如，print.ts.Rd 包含

\usage{
\method{print}{ts}(x, calendar, \dots)
}

將列印為

Usage:

     ## S3 method for class ‘ts’:
     print(x, calendar, ...)

替換函數的用法應以 dim(x) <- 值 的樣式提供，而不是明確指出替換函數的名稱（如上方的 "dim<-"）。類似地，可以使用 \method{泛函}{類別}(參數清單) <- 值 指出繼承自類別 "類別" 物件的泛函替換函數 "泛函<-" 的 S3 替換方法的用法。

用於萃取或替換物件部分的 S3 方法、Ops 群組成員的 S3 方法，以及使用者定義 (二進位) 中綴運算子 (‘%xxx%’) 的 S3 方法遵循上述規則，使用適當的函式名稱。例如，Extract.factor.Rd 包含

\usage{
\method{[}{factor}(x, \dots, drop = FALSE)
\method{[[}{factor}(x, \dots)
\method{[}{factor}(x, \dots) <- value
}

將列印為

Usage:

     ## S3 method for class ‘factor’:
     x[..., drop = FALSE]
     ## S3 method for class ‘factor’:
     x[[...]]
     ## S3 replacement method for class ‘factor’:
     x[...] <- value

\S3method 可作為 \method 的替代選項。

\arguments{…} ¶

函式引數的說明，使用表單中的項目

\item{arg_i}{Description of arg_i.}

作為引數清單的每個元素。(請注意，項目三部分之間沒有空白。)引數也可以透過在 \item 標籤中以逗號 (和空白) 分隔其名稱來共同說明。在 \item 項目之外可能有選用文字，例如提供關於參數群組的一般資訊。

\details{…} ¶

提供詳細且精確的說明，說明所提供的功能，並延伸 \description 欄位中的基本資訊。

\value{…} ¶

函式傳回值的說明。

如果傳回清單包含多個值，您可以使用表單中的項目

\item{comp_i}{Description of comp_i.}

對於回傳清單的每個元件。在 \item 項目外可能會有選用的文字（例如 rle 和 inverse.rle 的共同說明，或 l10n_info 中的項目組）。請注意，\value 隱含地為 \describe 環境，因此不應使用該環境來列出元件，僅使用個別 \item{}{} 項目。¹¹⁶

\references{…} ¶

包含參考文獻的部分。針對網路指標使用 \url{} 或 \href{}{}，針對 DOI 使用 \doi{}（這需要 R >= 3.3，請參閱 使用者定義巨集 以取得更多資訊）。

\note{...} ¶

用於您想要特別指出的特殊註解。允許多個 \note 部分，但可能會讓最終使用者感到困惑。

例如，pie.Rd 包含

\note{
  Pie charts are a very bad way of displaying information.
  The eye is good at judging linear measures and bad at
  judging relative areas.
  ......
}

\author{…} ¶

關於 Rd 檔案作者的資訊。使用 \email{} 而沒有額外分隔符號（例如 ‘( )’ 或 ‘< >’）來指定電子郵件地址，或使用 \url{} 或 \href{}{} 針對網路指標。

\seealso{…} ¶

使用 \code{\link{...}} 指向相關 R 物件的指標（\code 是 R 物件名稱正確的標記，\link 會在支援此功能的輸出格式中產生超連結。請參閱 標記文字 和 交叉參照）。

\examples{…} ¶

函數使用範例。此區段的程式碼以打字機字型設定，不重新格式化，並由 example() 執行，除非另有標示（請見下方）。

範例不僅對文件目的有用，也提供用於診斷檢查 R 程式碼的測試程式碼。預設情況下，\examples{} 內的文字會顯示在說明頁面的輸出中，並由 example() 和 R CMD check 執行。您可以使用 \dontrun{} 來處理僅顯示但不執行的文字，以及 \dontshow{} 來處理額外的測試指令，這些指令不應顯示給使用者，但會由 example() 執行。（先前這稱為 \testonly，此名稱仍可接受。）

\dontrun{} 內的文字為「逐字」，但 \examples 區段的其他部分為類似 R 的文字。

例如，

x <- runif(10)       # Shown and run.
\dontrun{plot(x)}    # Only shown.
\dontshow{log(x)}    # Only run.

因此，未包含在 \dontrun 中的範例程式碼必須可執行！此外，不應使用任何系統特定功能或需要特殊設施（例如網際網路存取或對特定目錄的寫入權限）。\dontrun 中包含的文字會在已處理的說明檔案中以註解表示：它不必是有效的 R 程式碼，但仍必須對 %、\ 和未配對的大括弧使用跳脫字元，如同其他「逐字」文字。

範例程式碼必須能夠由 example 執行，而 example 使用 source。這表示它不應存取 stdin，例如從範例檔案 scan() 資料。

可以透過亂數產生（例如，x <- rnorm(100)），或使用 data() 列出的標準資料集（有關更多資訊，請參閱 ?data）取得製作範例可執行檔案所需的資料。

最後，\donttest（用於獨立行的開頭）用於標記應由 example() 執行，但不要由 R CMD check 執行的程式碼（預設值：可以使用 --run-donttest 選項）。這應該只有偶爾需要，但可以用於在難以測試的情況下可能會失敗的程式碼，例如在某些區域設定中。（使用例如 capabilities() 或 nzchar(Sys.which("someprogram")) 盡可能測試範例中需要的功能，您也可以使用 try() 或 tryCatch()。使用 interactive() 來設定需要有人互動的範例。）請注意，包含在 \donttest 中的程式碼必須是正確的 R 程式碼，且應在 DESCRIPTION 檔案中宣告使用的任何套件。在 \donttest 區段中包含註解來說明為何需要它，這是一個良好的習慣。

註解之間的程式碼輸出

## IGNORE_RDIFF_BEGIN
## IGNORE_RDIFF_END

在將檢查輸出與參考輸出（-Ex.Rout.save 檔案）進行比較時，會被忽略。此標記也可以用於 tests 底下的指令碼。

\keyword{key} ¶

每個檔案可以有零個或多個 \keyword 區段。每個 \keyword 區段應指定一個單一關鍵字，最好是 R 文件目錄中的 KEYWORDS 檔案中所列的標準關鍵字之一（預設為 R_HOME/doc）。例如，使用 RShowDoc("KEYWORDS") 來從 R 內部檢查標準關鍵字。如果要記錄的 R 物件屬於多個類別，則可以有多個 \keyword 項目，或沒有任何項目。

如果您打算使用少數幾個非標準關鍵字，請強烈考慮使用 \concept（請參閱 索引）代替 \keyword。

特殊關鍵字「internal」標示一個內部物件的頁面，該物件不是套件 API 的一部分。如果物件 foo 的說明頁面有關鍵字「internal」，則 help(foo) 會提供這個說明頁面，但 foo 會從多個主題索引中排除，包括 HTML 說明系統中的主題字母清單。

help.search() 可以依據關鍵字搜尋，包括使用者定義的值：不過，透過 help.start() 存取的「搜尋引擎與關鍵字」HTML 頁面只提供單一點擊存取至預先定義的關鍵字清單。

2.1.2 記錄資料集 ¶

記錄 R 資料集的 Rd 檔案結構略有不同。不需要 \arguments 和 \value 等區段，但應說明資料的格式和來源。

舉例來說，我們來看一下 src/library/datasets/man/rivers.Rd，它記錄了標準 R 資料集 rivers。

\name{rivers} \docType{data} \alias{rivers} \title{Lengths of Major North American Rivers} \description{ This data set gives the lengths (in miles) of 141 \dQuote{major} rivers in North America, as compiled by the US Geological Survey. } \usage{rivers} \format{A vector containing 141 observations.} \source{World Almanac and Book of Facts, 1975, page 406.} \references{ McNeil, D. R. (1977) \emph{Interactive Data Analysis}. New York: Wiley. } \keyword{datasets}

它使用了以下額外標記命令。

\docType{…}

指出文件物件的「類型」。對於資料集，永遠是「data」；對於 pkg-package.Rd 概觀檔案，永遠是「package」。S4 方法和類別的文件使用「methods」（來自 promptMethods()）和「class」（來自 promptClass()）。

\format{…} ¶

資料集格式的說明（作為向量、矩陣、資料框、時間序列等）。對於矩陣和資料框，這應該提供每一個欄位的說明，最好是作為清單或表格。請參閱 清單和表格，以取得更多資訊。

\source{…} ¶

原始來源的詳細資料（參考或 URL，請參閱 指定 URL）。此外，區段 \references 可以提供次要來源和用法。

另請注意，在記錄資料集 bar 時，

• \usage 項目永遠是 bar 或（對於不使用資料延遲載入的套件） data(bar)。（特別是，每個 Rd 檔案只記錄 單一 資料物件。）
• \keyword 項目永遠應該是「datasets」。

如果 bar 是資料框，可以 透過 prompt(bar) 將它記錄為資料集。否則，可以使用 promptData 函式。

2.1.3 記錄 S4 類別和方法 ¶

有特殊的方法可以使用「?」運算子，即「class?主題」和「methods?主題」，分別存取 S4 類別和方法的說明文件。此機制依賴於 \alias 項目中所使用的主題名稱慣例。S4 類別和方法的主題名稱分別為下列形式

class-class
generic,signature_list-method

其中 簽章_清單 包含方法簽章中類別的名稱（不含引號），以「,」分隔（不含空白），對於沒有明確規範的引數，則使用「ANY」。例如，「genericFunction-class」是 S4 類別 "genericFunction" 說明文件的主題名稱，而「coerce,ANY,NULL-method」則是 S4 方法 coerce 簽章 c("ANY", "NULL") 說明文件的主題名稱。

可以使用套件 methods 中的函數 promptClass() 和 promptMethods() 產生 S4 類別和方法的說明文件範本。如果需要或想要為 S4 方法提供明確的函數宣告（在 \usage 區段中）（例如，如果它有「令人驚訝的引數」需要明確提到），可以使用特殊標記

\S4method{generic}{signature_list}(argument_list)

(例如，「\S4method{coerce}{ANY,NULL}(from, to)」)。

為了充分利用線上說明文件系統的潛力，套件中所有使用者可見的 S4 類別和方法至少應在套件的其中一個 Rd 檔案中有一個合適的 \alias 項目。如果套件有在其他地方最初定義的函數方法，且不會變更函數的底層預設方法，則套件負責記錄它所建立的方法，但不負責函數本身或預設方法。

S4 取代方法的記錄方式與 S3 相同：請參閱 記錄函數 中對 \method 的說明。

請參閱 help("Documentation", package = "methods") 以取得更多有關使用和建立 S4 類別和方法的線上文件資訊。

2.1.4 文件化套件 ¶

套件可以有一個概觀說明頁，其中包含 \alias pkgname-package，例如 utils 套件的「utils-package」，當 package?pkgname 會開啟該說明頁。如果在其他 Rd 檔案中不存在名為 pkgname 的主題，則建議將其用作額外的 \alias。

可以使用函數 promptPackage() 為套件產生文件架構。如果使用 final = TRUE 參數，則 Rd 檔案將以最終形式產生，其中包含 library(help = pkgname) 會產生的資訊。否則（預設值），將插入提供內容建議的註解。

除了強制性的 \name 和 \title 以及 pkgname-package 別名之外，套件概觀頁面的唯一需求是包含 \docType{package} 陳述式。所有其他內容都是選用的。我們建議它應該是一個簡短的概觀，以提供不熟悉該套件的讀者足夠的資訊以開始使用。更廣泛的文件最好放入套件範例（請參閱 撰寫套件範例）並從此頁面參照，或放入函數、資料集或類別的個別手冊頁面中。

3.3.1 來自 Rprof 的記憶體統計資料 ¶

前一節所述的抽樣分析器 Rprof 可以給予選項 memory.profiling=TRUE。然後它會在每個抽樣區間寫出 R 記憶體配置在小向量、大向量和 cons 單元格或節點中的總量。它也會寫出內部函數 duplicate 的呼叫次數，此函數用於複製 R 物件。 summaryRprof 提供此資訊的摘要。這可能會產生誤導的主要原因是，記憶體使用量會歸因於在抽樣區間結束時執行的函數。第二個原因是，垃圾回收可能會減少使用的記憶體量，因此函數似乎只使用少量記憶體。在 gctorture 下執行有助於解決這兩個問題：它會減慢程式碼速度以有效增加抽樣頻率，而且會讓每次垃圾回收釋放較少的記憶體量。

3.3.2 追蹤記憶體配置 ¶

第二種記憶體剖析方法使用記憶體配置剖析器 Rprofmem()，它會在每次配置大向量（針對「大」設定使用者指定的閾值）或為 R 堆配置新記憶體頁面時，寫出堆疊追蹤至輸出檔案。此輸出的摘要函數仍在設計中。

執行前一節的範例，

> Rprofmem("boot.memprof",threshold=1000)
> storm.boot <- boot(rs, storm.bf, R = 4999)
> Rprofmem(NULL)

顯示除了 boot 中的一些初始和最終工作外，沒有超過 1000 位元的向量配置。

3.3.3 追蹤物件的拷貝 ¶

記憶體剖析的第三種方法涉及追蹤特定（假設為大型）R 物件所做的拷貝。對物件呼叫 tracemem 會標記該物件，以便在物件透過 duplicate 或強制轉換為另一種類型拷貝時，或在算術運算中建立相同大小的新物件時，會將訊息列印到標準輸出。這可能會產生誤導的主要原因是，系統不會追蹤物件的子集或組件拷貝。對這些組件使用 tracemem 可能會有幫助。

在上面的範例中，我們可以在資料框 st 上執行 tracemem

> tracemem(st)
[1] "<0x9abd5e0>"
> storm.boot <- boot(rs, storm.bf, R = 4)
memtrace[0x9abd5e0->0x92a6d08]: statistic boot
memtrace[0x92a6d08->0x92a6d80]: $<-.data.frame $<- statistic boot
memtrace[0x92a6d80->0x92a6df8]: $<-.data.frame $<- statistic boot
memtrace[0x9abd5e0->0x9271318]: statistic boot
memtrace[0x9271318->0x9271390]: $<-.data.frame $<- statistic boot
memtrace[0x9271390->0x9271408]: $<-.data.frame $<- statistic boot
memtrace[0x9abd5e0->0x914f558]: statistic boot
memtrace[0x914f558->0x914f5f8]: $<-.data.frame $<- statistic boot
memtrace[0x914f5f8->0x914f670]: $<-.data.frame $<- statistic boot
memtrace[0x9abd5e0->0x972cbf0]: statistic boot
memtrace[0x972cbf0->0x972cc68]: $<-.data.frame $<- statistic boot
memtrace[0x972cc68->0x972cd08]: $<-.data.frame $<- statistic boot
memtrace[0x9abd5e0->0x98ead98]: statistic boot
memtrace[0x98ead98->0x98eae10]: $<-.data.frame $<- statistic boot
memtrace[0x98eae10->0x98eae88]: $<-.data.frame $<- statistic boot

物件拷貝了十五次，對 storm.bf 的每個 R+1 呼叫拷貝三次。這令人驚訝，因為沒有任何拷貝發生在 nls 內部。在偵錯器中逐步執行 storm.bf 會顯示所有三次都發生在這一行

st$Time <- st$fit + rs[i]

資料框比矩陣慢，這就是原因之一。使用 tracemem(st$Viscosity) 不會顯示任何額外的拷貝。

3.4.1 Linux ¶

選項包括使用 sprof 來處理共用物件，以及 oprofile（請參閱 https://oprofile.sourceforge.io/news/）和 perf（請參閱 https://perf.wiki.kernel.org/index.php/Tutorial）來處理任何可執行檔或共用物件。這些工具似乎比過去提供的範圍更小。還有「Google Performance Tools」，也稱為 gperftools 或 google-perftools。

當 R 和任何套件都已使用偵錯符號建置時，所有這些工具都能發揮最佳效用。

• perf
• oprofile 和 operf
• sprof

perf record R -f tests/Examples/stats-Ex.R
perf report --sort=dso
perf report --sort=srcfile
rm perf.data*

  75.67%  R
   9.25%  libc.so.6
   4.87%  [unknown]
   3.75%  libz.so.1.2.11
   3.37%  stats.so
   1.17%  libm.so.6
   0.63%  libtirpc.so.3.0.0
   0.41%  graphics.so
   0.30%  grDevices.so
   0.20%  libRblas.so
   0.09%  libpcre2-8.so.0.11.0
   0.07%  methods.so
   ...

operf R -f boot.R
opreport
opreport -l /path/to/R_HOME/bin/exec/R
opreport -l /path/to/R_HOME/library/stats/src/stats.so
opannotate --source /path/to/R_HOME/bin/exec/R

	CPU_CLK_UNHALT...|
	  samples|      %|
	------------------
	   278341 91.9947 R
	    18290  6.0450 libc.so.6
	     2277  0.7526 kallsyms
	     1426  0.4713 stats.so
	      739  0.2442 libRblas.so
	      554  0.1831 libz.so.1.2.11
	      373  0.1233 libm.so.6
	      352  0.1163 libtirpc.so.3.0.0
	      153  0.0506 ld-linux-x86-64.so.2
	       12  0.0040 methods.so

samples  %        image name symbol name
52955    19.0574  R                        bcEval.lto_priv.0
16484     5.9322  R                        Rf_allocVector3
14224     5.1189  R                        Rf_findVarInFrame3
12581     4.5276  R                        CONS_NR
8289      2.9830  R                        Rf_matchArgs_NR
8034      2.8913  R                        Rf_cons
7114      2.5602  R                        R_gc_internal.lto_priv.0
6552      2.3579  R                        Rf_eval
5969      2.1481  R                        VECTOR_ELT
5684      2.0456  R                        Rf_applyClosure
5497      1.9783  R                        findVarLocInFrame.part.0.lto_priv.0
4827      1.7371  R                        Rf_mkPROMISE
4609      1.6587  R                        Rf_install
4317      1.5536  R                        Rf_findFun3
4035      1.4521  R                        getvar.lto_priv.0
3491      1.2563  R                        SETCAR
3179      1.1441  R                        Rf_defineVar
2892      1.0408  R                        duplicate1.lto_priv.0

samples  %        image name               symbol name
285      24.4845  stats.so                 termsform
284      24.3986  stats.so                 numeric_deriv
213      18.2990  stats.so                 modelframe
114       9.7938  stats.so                 nls_iter
55        4.7251  stats.so                 ExtractVars
47        4.0378  stats.so                 EncodeVars
37        3.1787  stats.so                 getListElement
32        2.7491  stats.so                 TrimRepeats
25        2.1478  stats.so                 InstallVar
20        1.7182  stats.so                 MatchVar
20        1.7182  stats.so                 isZeroOne
15        1.2887  stats.so                 ConvInfoMsg.isra.0

% setenv LD_PROFILE /path/to/R_HOME/library/stats/libs/stats.so
% R -f boot.R
% sprof /path/to/R_HOME/library/stats/libs/stats.so \
  /var/tmp/path/to/R_HOME/library/stats/libs/stats.so.profile

Flat profile:

Each sample counts as 0.01 seconds.
  %   cumulative   self              self     total
 time   seconds   seconds    calls  us/call  us/call  name
 76.19      0.32     0.32        0     0.00           numeric_deriv
 16.67      0.39     0.07        0     0.00           nls_iter
  7.14      0.42     0.03        0     0.00           getListElement

... to clean up ...
rm /var/tmp/path/to/R_HOME/library/stats/libs/stats.so.profile

3.4.2 macOS 上的剖析 ¶

開發人員建議使用 Instruments（Xcode 的一部分，請參閱 https://help.apple.com/instruments/mac/current/），在 macOS 12 之前，它有一個命令列版本。

3.4.3 Windows 上的剖析 ¶

Very Sleepy (https://github.com/VerySleepy/verysleepy) 已被使用。存取偵錯資訊時會出現問題，但透過 GUI 或使用 /a:（pid 透過 Sys.getpid() 取得）將剖析器附加到現有的 Rterm 程序，可以取得包含函數名稱的最佳結果。

4.3.1 使用 gctorture ¶

我們可以透過盡可能頻繁執行垃圾回收來協助提早偵測 R 物件中的記憶體問題。這可透過 gctorture(TRUE) 來達成，其說明頁中說明

在（幾乎）每次記憶體配置時觸發垃圾回收。用於找出記憶體保護錯誤。但不幸的是，也會讓 R 執行得非常慢。

「記憶體保護」是指遺漏對 PROTECT/UNPROTECT 的 C 層級呼叫（請參閱 處理垃圾回收的影響），如果遺漏，會讓 R 物件在仍被使用時遭到垃圾回收。但它也可以協助處理其他與記憶體相關的錯誤。

通常在 gctorture(TRUE) 下執行只會讓 R 程式在較早階段崩潰，希望接近實際原因。請參閱下一章節，了解如何解讀此類崩潰。

透過使用選項 --use-gct，可以在 gctorture(TRUE) 下執行 R CMD check 所涵蓋的所有範例、測試和範例。

函數 gctorture2 提供對 GC 測試程序更精細的控制。其參數 step、wait 和 inhibit_release 已記錄在說明頁中。環境變數也可以在 R 會話開始時用於開啟 GC 測試：R_GCTORTURE 對應於 gctorture2 的 step 參數，R_GCTORTURE_WAIT 對應於 wait，R_GCTORTURE_INHIBIT_RELEASE 對應於 inhibit_release。

如果 R 使用 --enable-strict-barrier 進行組態，則會啟用各種寫入屏障完整性測試。此外，還會啟用有助於偵測保護問題的測試

• 所有 GC 都是完整 GC。
• 小型節點頁面中的新節點在建立時標記為 NEWSXP。
• 在 GC 之後，所有不是 NEWSXP 類型的空閒節點都會標記為 FREESXP 類型，並記錄其先前的類型。
• 大多數存取函數呼叫都會檢查其 SEXP 輸入和 SEXP 輸出，如果發現 FREESXP，則會發出錯誤訊號。節點的位址和舊類型會包含在錯誤訊息中。

可以設定 R CMD check --use-gct 以使用 gctorture2(n)，而不是 gctorture(TRUE)，方法是將環境變數 _R_CHECK_GCT_N_ 設定為正整數值，以用作 n。

與偵錯器和 gctorture 或 gctorture2 搭配使用時，此機制有助於找出記憶體保護問題。

4.3.2 使用 valgrind ¶

如果您可以在常見的 CPU 類型或受支援版本的 FreeBSD 或 Solaris¹²⁵上存取 Linux，您可以使用 valgrind (https://valgrind.org/，發音與「tinned」押韻）來檢查可能的錯誤。要在 valgrind 下執行一些範例，請使用類似下列指令

R -d valgrind --vanilla < mypkg-Ex.R
R -d "valgrind --tool=memcheck --leak-check=full" --vanilla < mypkg-Ex.R

其中 mypkg-Ex.R 是一組範例，例如 R CMD check 在 mypkg.Rcheck 中建立的檔案。偶爾會回報「未初始化值」的記憶體讀取，這是編譯器最佳化的結果，因此值得在未最佳化的編譯下檢查：要取得最大的資訊，請使用具有偵錯符號的建置。我們知道 readline 和 R 本身會有一些小的記憶體外洩——這些記憶體區域在 R 工作階段結束前都會使用。預期執行速度會比沒有 valgrind 的情況慢 20 倍左右，在某些情況下會更慢。數個版本的 valgrind 對使用 CPU 特定指令的一些最佳化 BLAS 函式庫不滿意，因此您可能需要特別建置 R 版本才能與 valgrind 搭配使用。