网站开发公司 杭州,网站专题页是什么,wordpress照片墙,个人简介网页设计素材DESCRIPTION(描述文件) 的作用是存储包中重要的元数据。当第一次开发包时#xff0c; 你会 使用这个文件记录包运行时所需要的包。然而#xff0c;随着时间的流逝#xff0c;当开始与他人分享包 时#xff0c;元数据文件变得越来越重要#xff0c;因为它指定了谁可以使用它…
DESCRIPTION(描述文件) 的作用是存储包中重要的元数据。当第一次开发包时 你会 使用这个文件记录包运行时所需要的包。然而随着时间的流逝当开始与他人分享包 时元数据文件变得越来越重要因为它指定了谁可以使用它(许可证)以及如果包有 什么问题时需要和谁(你!)联系。每一个包必须有一个DESCRIPTION。事实上 它是包的定义特征(R Studio和devtools 把任何包含DESCRIPTION的目录都视为一个包) 。为方便你开始 devtools::create (mypackage) 会自动添加一个描述文件框架。这让你可以开始进行包开发而无需担心元 数据的问题直到需要时才去关心它。
最小的描述文件会依据设置而有所不同但它看起来应该是这样的
Packagemy package
TitLeWhat The Package Does(one line title case required)
Version 0.1
AuthorsRperson(First,Last,email first.lastdexample.com,rolec(autcre))
DescriptionWhat the package does(one paragraph)
DependsR(3.1.0)
LicenseWhat Licenseis it under?
Lazy Datatrue
DESCRIPTION使用一个称为Debian控制格式 (Debian control formatDCF) 的简单文件格式。可以通过下面所示的简单例子看到它的大部分结构。它每行包括一个域的名字和一个值中间用冒号分开。当值跨越多行时需要缩进 Description包的描述通常很长跨越多行。 第二行及随后的行应缩进通常是缩进四个空格。 4.1 依赖包需要什么
描述文件需要列出该包所依赖的包。R有很多方法来描述潜在的依赖关系。
Imports和Suggests使用逗号分隔的包名列表。我建议每行放一个包名 并按字母顺序排 列。这将易于快速阅读。 Imports和Suggests的不同在于依赖的程度。
Imports(输出 为使包能够工作 In ports列表里的包必须安装。事实上 任何时候 如果包被安装 这些包也将会被安装如果以前没有安装的话(devtoolsLoad_alL() 也会检查那些已 安装的包)。Suggests 建议 你的包可以使用这些包但它们不是必需的。比如你可能会使用建议包中的数据包来运 行测试、编译使用指南或者只有一个函数需要那个包。在本地开发包时 永远不需要使用Suggests。当发布包时 使用Suggests对用户而言很方便。这样他们就不必下载很少使用的包进而可以以最快的速度来使用你的包。 要为包添加In ports和Suggests 最简单的方法是使用devtoolsuse_package() 。这会自 动把它们放在DESCRIPTION文件中正确的位置 并提醒你如何使用它们 4.1.1版本
如果需要一个特定版本的包则在包名后面的括号中指定它
Importsggvis(0.2) dplyr(0.3.0.1)
SuggestsMASS(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作者你是谁
利用AuthorR域来指定包的作者 以及如果包有什么问题该和谁联系。这个域是独特的 因为它包含可执行的R代码而不是纯文本。下面是一个例子
AuthorsRperson(HadLeyWickham enailhadleyrstudio.comrolec(autcre)) 该命令说 包的作者(aut) 和维护者(cre) 都是Hadley Wickham他的电子邮件地址是 hadleyrstudio.com。person() 函数有以下四个主要参数。
名字由前两个参数指定名和姓(这些参数由位置确定没有参数名)。在西方文化中名在姓的前面但是在许多东方文化中并没有这个习惯。email地址。三个字母的代码用来指定角色(role) 有四个重要的角色。 cre 创建者或者维护者 也就是你遇到问题时需要联系的人。aut 作者 对包作出重大贡献的人。ctb 贡献者 作出了较小贡献的人 比如提供了一些补丁。cph 版权所有人。用在下面这种情况版权是作者以外的人 通常是一个公司(即作者的雇主)。 4.4许可证谁能使用包
许可证((License))域可以是一个开源许可证的标准缩写 比如GPL-2或BSD 也可以指向 包含更多信息的文件——文件许可丁(fileLICENSE) 。如果计划发布包该许可证是非常重 要的。如果不打算发布可以忽出咯这个部分。如果想清楚地说明包不是开源的使用许可 证文件许可证(LicensefileLICENSE) 然后创建一个文件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.21 是主要版本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 扩展开发手册)
