在windows中创建R程序包简明指南

• 2009年8月5日 初稿
• 2016年8月15日修订
• 2019年5月24日修订

R软件中CRAN镜像已经有8957个程序包在线发表（截至2016年8月15日），几乎涉及统计编程的所有领域。CRAN上每个程序包都包含源代码以及编译好的Windows， MacOS版本，可在多种平台上使用。除了使用CRAN上的R程序包，用户还可以自己编写R程序包。在数据处理中，如果积累了一定量的R函数，最好将为它们准备好帮助文档，并制作成自己的R程序包，便于管理和使用。

那么在Windows环境下如何编写R程序包并提交到CRAN？本文拟简要说明：

在Windows下编写R程序包通常包括以下几步：

1. 安装工具软件Rtools和MikTeX并配置启动路径。

2. 利用R中自带的package.skeleton()函数生成R程序包的模板。

3. 填写程序包的DESCRIPTION，NAMESPACE，Rd等模板文件。

4. R包的编译和检查

下面我们来创建一个简单的R程序包，其中只包含一个函数F2C。

1. 安装工具软件Rtools和MikTeX并配置启动路径

1.1 Rtools

Rtools（图1）是在windows下制作R包的一系列工具，其中主要包括MinGW编译器，其中的gcc，g++, gfortran等可用来编译带有C，C++和Fortran等语言的R程序包源代码。

下载地址为：https://cran.r-project.org/bin/windows/Rtools/

安装Rtools时，必须允许其修改启动路径（图2），这样之后才能正常使用。安装大约需要3-5min。

图1 Rtools下载页面，应该以最新版本的为准

图 2 安装Rtools时应该允许其修改system PATH

1.2 MikTeX

MikTex用来生成PDF帮助文档，在R程序包做检查时是必须的（图3）。

下载地址：http://miktex.org/download。MikTex在使用时会自动安装程序包，所以第一次使用时要保证联网。

图3 Mitex在安装中

1.3 设置文件启动路径

设置启动路径的目的是在cmd命令行可以直接调用Rcmd, gcc等命令（找到gcc.exe, Rcmd.exe所在的文件夹，并将其添加到启动路径图4）。

图4含有Rcmd.exe的文件夹，该文件夹需要添加到PATH中

方法如下：

右键点击：我的电脑 > 属性 > 高级 > 环境变量 > 系统变量 PATH一项，点击“编辑”，在弹出的窗口中，值Variable Value应该含有如下路径（R和gcc， Miktex因安装的版本而异）：

通常Rtools， Miktex等在安装时已经自动配置好启动路径，而R的路径(如C:ProgramFilesRR-3.3.1bini386;C:Program FilesRR-3.3.1binx64; )必须手动添加。每个路径与之前一个路径用英文的分号分隔。

2. 利用package.skeleton()函数生成R程序包模板

假如现在现有R函数F2C，用来将华氏温度转换为摄氏温度, 保存在'C:\Jinlong\package\TEMP.R'中。

函数如下所示:

F2C <- function(x){
   res <- (x - 32) / 1.8
   return(res)
}

则可以用package.skeletons()函数生成R程序包的框架。方法为：

登陆R，例如：开始 > 所有程序 > R > R i386 3.3.1

2.1 清除内存中的对象

目的是删除R内存中所有不需要的数据或函数：

rm(list=ls())

2.2 设定工作目录

这里设定为C:\Jinlong\package

setwd("C:\\Jinlong\\package")

2.3 导入脚本中的所有R函数

用source()函数读取TEMP.R脚本中的所有函数。

source("TEMP.R")

2.4 生成R程序包框架

程序包可以命名为TEMP。输入以下命令生成R包的骨架：

package.skeleton(name="TEMP",list = ls())

此时，R控制台中显示：

>setwd("C:\\Jinlong\\package")
>source("TEMP.R")
>package.skeleton(name="TEMP", list = ls())
Creating directories ...
Creating DESCRIPTION ...
Creating NAMESPACE ...
Creating Read-and-delete-me ...
Saving functions and data ...
Making help files ...
Done.
Furthersteps are described in './TEMP/Read-and-delete-me'.
>

可以看到C:\Jinlong\package文件夹下出现了一个TEMP文件夹，该文件夹结构如下：

└─TEMP
   │ DESCRIPTION
   │ NAMESPACE
   │ Read-and-delete-me
   │  
   ├─man
   │ F2C.Rd
   │ TEMP-package.Rd
   │    
   └─R
​     F2C.R

以上就是R包的框架，包括DESCRIPTION，NAMESPACE，Read-and-delete-me三个纯文本文件，以及Ｒ文件夹，man文件夹。

3. 填写程序包的DESCRIPTION，NAMESPACE，Rd等模板文件。

3.1. Read-and-delete-me 文件

该文件主要介绍如何创建R包

文件内容如下：

* Editthe help file skeletons in 'man', possibly combining help files for multiplefunctions.：
编辑man文件夹中的帮助文件模板

* Editthe exports in 'NAMESPACE', and add necessary imports.：
编辑NAMESPACE文件，显示需要导出或者导入的函数。

* Put anyC/C++/Fortran code in 'src'. ：
将C/C++/Fortran 的源代码应该放入src文件夹下

* If youhave compiled code, add a useDynLib() directive to 'NAMESPACE'.：
如果含有已经编译好的代码（Windows下是DLL文件），在NAMESPACE中需要加入 useDynLib() 标记。

* Run RCMD build to build the package tarball.
创建R程序包使用命令 R CMD build 程序包名称

* Run RCMD check to check the package tarball.
检查R程序包使用命令 R CMD check 程序包名称

Read "Writing R Extensions" for more information.

请阅读编写R扩展的相应信息。

不过，这里的R CMD说的是在Linux的终端输入的命令，实际上在Windows环境中应该输入 Rcmd (见第四节 R包的编译和检查)

3.2 编辑DESCRIPTION文件和帮助文件

DESCRIPTION文件是该程序包的简介，内容如下：

Package:TEMP
Type:Package
Title:What the package does (short line)
Version:1.0
Date:2016-08-15
Author:Who wrote it
Maintainer:Who to complain to <yourfault@somewhere.net>
Description:More about what it does (maybe more than one line)
License:What license is it under?

冒号右边的内容需要修改。其中不能有非ASCII码的字符。

• 如果程序包中使用了其它程序包的函数或者数据，则应该在Description文件中加入Suggests或者Depends, imports某程序包的选项，详情参见 Writing R Extensions中的 1.1.3 Package Dependencies 一节。
• 编写DESCRIPTION文件的相信指南，请参考 Writing R Extensions 的 1.1.1 The DESCRIPTION file 一节。

更改后的DESCRIPTION文件：

Package: TEMP 程序包名称
Type: Package 类型为程序包
Title: Convert Temperature 程序包安装后显示的标题
Version: 1.0 程序包的版本
Date: 2016-08-15 日期，以年月日的格式提供
Author: Jinlong Zhang 作者
Maintainer:Jinlong Zhang <jinlongzhang01@gmail.com>  作者的联系方式
Description:Containing functions for converting temperatures. 程序包的详细功能
License: GPL-2 程序包遵循的版权协议。

3.3 编辑man文件夹中的.rd文件

man文件夹中包含两个文件 F2C.Rd和TEMP-package.Rd，分别是F2C()函数和TEMP包的帮助文件。

Rd文件的格式与Tex的格式很像。在花括号中输入要更改的内容即可。Rd文件的项目中不能留空，否则在检查时会显示警告。其中title是必须填写的内容。同时要注意：在Rd文件中，不要出现非ASCII码字符，否则在Rcmd check中将不能通过。

F2C.Rd文件：单个%为注释，编译时将直接忽略。两个百分号%%为需要修改的内容，

\name{F2C}
\alias{F2C}
\title{Fahrenheit to Celsius}

\description{
Convert Fahrenheit to Celsius Degrees
}

\usage{F2C(x)}

\arguments{
    item{x}{Fahrenheit in decimal.}
}

\details{
    Convert Fahrenheit to Celsius Degreesusing the formula C =(F - 32)/ 1.8
}

\value{Celsius degrees}

\references{\url{http://www.21ic.com/calculator/sheshiwendu.htm}}

\author{Jinlong Zhang}

\note{This is just an example}

\examples{F2C(100)}

\keyword{ Temperature }
\keyword{ Fahrenheit }
\keyword{ Celsius }

TEMP-package.Rd中帮助文件的填法与F2C.Rd的类似。

4 R包的编译和检查

4.1直接在cmd输入命令编译和检查程序包

R 程序包的编译和检查，一般都通过在cmd输入命令。

在开始，运行 cmd的窗口，输入 cd C:\Jinlong\package\TEMP 转入当前的工作目录（图5）。

• 键入Rcmd check TEMP 对TEMP_1.0.tar.gz代码的各项内容进行检查。

• 键入Rcmd INSTALL --build TEMP 建立Window压缩包

• 键入Rcmd build TEMP建立源代码压缩包

• 键入Rcmd INSTALL TEMP安装到当前的R中

图 5 通过cmd编译TEMP文件夹

4.2 通过.bat文件编译和检查程序包

cmd中输入的命令可以保存在Windows的批处理文件中。下面准备编译或安装R程序包的Windows批处理命令:

• (1)点击鼠标右键新建一个纯文本文件，将以下内容拷贝到该文件夹中，重命名为check package.bat

Rcmd check TEMP
PAUSE

双击该bat文件，可以对TEMP程序包中的错误进行检查。

• (2)点击鼠标右键新建一个纯文本文件,将以下内容拷贝到该文件夹中，并重命名为build Windows Binary.bat

  Rcmd INSTALL --build TEMP
  PAUSE

  双击该文件，可以建立Windows系统下的R程序包。

• (3)点击鼠标右键新建一个纯文本文件，将以下内容拷贝到该文件夹中，重命名为build Linux Source Code.bat，

Rcmd build TEMP
pause

双击该文件，可以建立Linux系统下的安装包。

• (4)点击鼠标右键新建一个纯文本文件，将以下内容拷贝到该文件夹中，命名为install package.bat

Rcmd INSTALL TEMP
PAUSE

双击该文件，可以安装skycalc到当前的R中。

将以上四个.bat文件，放置到TEMP文件夹所在的文件夹, 双击文件，即可完成程序包的安装，编译和检查等。

命令运行完之后可以发现，在C:\Jinlong\package\文件夹下分别生成了TEMP_1.0.zip和TEMP_1.0.tar.gz压缩包（图6）。

图6. 编译程序包

如果作者希望将自己制作的Package上传到CRAN，则必须要检查gz的Linux压缩包，通过R CMD check –as-cranpackage_name.gz，并且其中不能有任何错误或警告。

进一步阅读

• https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
• http://kbroman.org/pkg_primer/
• http://r-pkgs.had.co.nz/
• https://www.hsph.harvard.edu/statinformatics/soft/files/buildingrpackages.pdf