【R包开发：包的组件】 第4章 包的元数据

DESCRIPTION(描述文件) 的作用是存储包中重要的元数据。当第一次开发包时， 你会
使用这个文件记录包运行时所需要的包。然而，随着时间的流逝，当开始与他人分享包
时，元数据文件变得越来越重要，因为它指定了谁可以使用它(许可证)，以及如果包有
什么问题时需要和谁(你!)联系。
每一个包必须有一个DESCRIPTION。事实上， 它是包的定义特征(R Studio和devtools
把任何包含DESCRIPTION的目录都视为一个包) 。为方便你开始， devtools::create
("mypackage") 会自动添加一个描述文件框架。这让你可以开始进行包开发而无需担心元
数据的问题，直到需要时才去关心它。

最小的描述文件会依据设置而有所不同，但它看起来应该是这样的：

Package：my package
TitLe：What The Package Does(one line， title case required)
Version ：0.1
Authors@R：person("First","Last",email = "first.lastdexample.com",
    role=c("aut""cre"))
Description：What the package does(one paragraph)
Depends：R(>=3.1.0)
License：What Licenseis it under?
Lazy Data：true

• DESCRIPTION使用一个称为Debian控制格式 (Debian control format，DCF) 的简单文件格式。可以通过下面所示的简单例子看到它的大部分结构。它每行包括一个域的名字和一个值，中间用冒号分开。当值跨越多行时，需要缩进：
  •  Description：包的描述通常很长，跨越多行。
    •  第二行及随后的行应缩进，
    • 通常是缩进四个空格。 

 
4.1 依赖：包需要什么

描述文件需要列出该包所依赖的包。R有很多方法来描述潜在的依赖关系。

Imports和Suggests使用逗号分隔的包名列表。我建议每行放一个包名， 并按字母顺序排
列。这将易于快速阅读。
Imports和Suggests的不同在于依赖的程度。

• Imports(输出）
  • 为使包能够工作， In ports列表里的包必须安装。事实上， 任何时候， 如果包被安装，
    这些包也将会被安装，如果以前没有安装的话(devtools：：Load_alL() 也会检查那些已
    安装的包)。
• Suggests （建议）
  • 你的包可以使用这些包，但它们不是必需的。比如你可能会使用建议包中的数据包来运
    行测试、编译使用指南，或者只有一个函数需要那个包。
  • 在本地开发包时， 永远不需要使用Suggests。当发布包时， 使用Suggests对用户而言很方便。这样他们就不必下载很少使用的包，进而可以以最快的速度来使用你的包。  

要为包添加In ports和Suggests， 最简单的方法是使用devtools：：use_package() 。这会自
动把它们放在DESCRIPTION文件中正确的位置， 并提醒你如何使用它们

4.1.1版本

如果需要一个特定版本的包，则在包名后面的括号中指定它：

Imports：
    ggvis(>=0.2) ，
    dplyr(>=0.3.0.1)
Suggests：
    MASS(>=7.3.0)

我们几乎总是指定一个最小的版本， 而不是一个精确的版本(MASS(==7.3.0))。因为R不能同时装载一个包的多个版本，所以指定一个确切的版本依赖大大地增加了出问题的机会。版本控制是发布包时最重要的事情。通常人们不会和你有版本完全相同的包。如果有人有一个旧版本的包，而其中没有你的包需要的函数，那他会得到一条没有任何帮助的错误消息。但是，如果你提供了版本号，他就会得到一个明确的错误消息：一个过时的包。
一般而言，好的做法是指定版本，并且保守地指定需要的版本。除非你知道，否则就总是
指定一个大于等于你目前使用的版本。

4.1.2其他依赖

Depends （依赖）

使用Depends来指定一个特定的R版本

LinkingTo （链接到）

这里列出的包依赖于另一个包中的C或者C++代码。

Enhances (增强)

这里列出的包是你的包“增强”了的包。通常，这意味着你的包为其他包里的类提供了方法(反过来的Suggests) 。但很难确切定义这是什么意思， 所以不建议使用Enhances。

4.2 标题和描述：包是做什么

标题和描述域描述包做了些什么。它们的区别只在于长度。

Title(标题)是包的一行描述，经常显示在包列表中。它应该是纯文本(无标记)，并在大小写上遵循标题风格；它不应该以句号号结束。保持简短：列表通常会截掉标题中超出65个字符的部分。
Description(描述)比标题更详细。可以使用多个句子，但只限于一段。如果描述跨越多行((应该如此!)，每行必须不超过80个字符。用四个空格缩进后续的行。

4.3作者：你是谁

利用Author@R域来指定包的作者， 以及如果包有什么问题该和谁联系。这个域是独特的，
因为它包含可执行的R代码，而不是纯文本。下面是一个例子：

Authors@R：person("HadLey"，"Wickham"， enail="[email protected]"，
  role=c("aut"，"cre"))

该命令说， 包的作者(aut) 和维护者(cre) 都是Hadley Wickham，他的电子邮件地址是
[email protected]。person() 函数有以下四个主要参数。

• 名字，由前两个参数指定，名和姓(这些参数由位置确定，没有参数名)。在西方文化中，
• 名在姓的前面，但是在许多东方文化中并没有这个习惯。
• email地址。
• 三个字母的代码用来指定角色(role) ，有四个重要的角色。
  • cre， 创建者或者维护者， 也就是你遇到问题时需要联系的人。
  • aut， 作者， 对包作出重大贡献的人。
  • ctb， 贡献者， 作出了较小贡献的人， 比如提供了一些补丁。
  • cph， 版权所有人。用在下面这种情况：版权是作者以外的人， 通常是一个公司(即作者的雇主)。

4.4许可证：谁能使用包

许可证((License))域可以是一个开源许可证的标准缩写， 比如GPL-2或BSD， 也可以指向
包含更多信息的文件——文件许可丁(fileLICENSE) 。如果计划发布包，该许可证是非常重
要的。如果不打算发布，可以忽出咯这个部分。如果想清楚地说明包不是开源的，使用许可
证：文件许可证(License：fileLICENSE) ， 然后创建一个文件LICENNSE， 例如包含：
Proprietary
Do not distribute outside of Widgets Incorporated.
开源软件许可证是一个丰富而复杂的域。幸运的是，在我看来，只需为R包考虑三种许可证：

• MIT(https：//tldrlegal.com/license/mit-license)
  • 这是一个简单的、类似于BSD-2-clause或BSD-3-clause的许可证。它让人们使用和自由分发你的代码， 但是有一个限制：许可证必须始终和代码一起分发。
• GPL-2 (https://tldrlegal.com/license/gnu-general-public-license-v2) 或者 GPL-3 (https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3))
  • 这些都是“许可证保留”(copy-left) 许可证。这意味着任何包含你的代码的包都必须使用GPL兼容的许可证来发布。此外， 任何人发布你代码的修改版本(衍生作品)时，必须公布源码
• CC0(https://tldrlegal.com/license/creative-commons-cc0-1.0-universal)
  • 这个许可证放弃了你对代码和数据的所有权利，这样任何人都可以自由地把它用于任何目的。这有时被称为“把它放在公共领域”，在所有的国家，它都是一个既没有明确定义也没有意义的术语。此许可证最适合数据包。

4.5版本

正式的情况下，R包的版本是一个用.或者-分隔的至少有两个整数的序列。

发布的版本包括三个数字，<主版本号><次版本号><补丁版本>。对于版本数1.9.2，1
是主要版本，9是次要版本，2是补丁版本。永远不要使用像1.0这样的版本号；请总是把
三个版本号写出来(即1.0.0)。

4.6其他域

其他的一些域会在本书的其他地方说明。

• Collate控制R文件被加载的顺序。这只在代码有副作用(最常见的原因是使用S4)时有用。
• Lazy Data使得访问包中的数据更容易。因为它很重要， 所以devtools创建的最小描述文件中包含了它。

参考文献

中文书籍 (ituring.com.cn)

R Packages (2e) (r-pkgs.org)

英文书籍Writing R Extensions (r-project.org) (官方 R 扩展开发手册)