在Windows下创建R程序包简明指南

（2016年8月15日修订）

张金龙 jinlongzhang01@gmail.com

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因安装的版本而异）：

c:Rtoolsbin;c:Rtoolsmingw_32bin;c:Rtoolsbin;c:Rtoolsgcc-4.6.3bin;C:ProgramFilesRR-3.3.1bini386;C:Program FilesRR-3.3.1binx64;C:ProgramFilesMiKTeX 2.9miktexbinx64;

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

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

假如现在现有R函数F2C，用来将华氏温度转换为摄氏温度, 保存在C:JinlongpackageTEMP.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())

Creatingdirectories ...

CreatingDESCRIPTION ...

CreatingNAMESPACE ...

CreatingRead-and-delete-me ...

Savingfunctions and data ...

Makinghelp files ...

Done.

Furthersteps are described in './TEMP/Read-and-delete-me'.

>

可以看到C:Jinlongpackage文件夹下出现了一个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 一节。

更改后：

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文件：单个%为注释，编译时将直接忽略。两个百分号%%为需要修改的内容，

##############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:JinlongpackageTEMP 转入当前的工作目录（图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文件，可以对skycalc程序包中的错误进行检查。

(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:/pa/文件夹下分别生成了TEMP.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