如何创建一个R扩展包 1

名词解释;

  • 包(Package): 基于R系统的标准化的代码,数据及文档的文件集合
  • 库(Library): 安装包的文件路径
  • 安装源(Repository): 提供可用于安装的带有版本控制的包的网站
  • 源码(Source): 人类可读的源代码或者文档组合而成的包的一种形式
  • 二进制文件(Binary): 依据指定操作平台经过编译形成的机器可读的二进制形式代码或者文档组合而成的包的一种形式
  • 基础包(Base packages): R系统的一部分,由R Core维护
  • 推荐包(Recommended packages): R安装时默认会安装的包,但不由R Core维护
  • 扩展包(Contributed packages): 所有其它的包的统称。因为其它的包是开放式开发的结果,所以被称为集体贡献(contributed)。

我们在R当中写了一段代码:

helloworld<-function(){
    cat("hello world!\n")
}

并把它保存为文件:helloworld.R

而后我们在R中设置工作路径为helloworld.R的保存路径,运行

> package.skeleton(name="myFirstPkg",code_files=dir(pattern="R$"))
Creating directories ...
Creating DESCRIPTION ...
Creating NAMESPACE ...
Creating Read-and-delete-me ...
Copying code files ...
Making help files ...
Done.
Further steps are described in './myFirstPkg/Read-and-delete-me'.

至此,我们已经得到了一个扩展包的基本雏形。我们进入myFirstPkg文件夹,看到其下的目录是这样的:

./myFirstPkg/DESCRIPTION
./myFirstPkg/NAMESPACE
./myFirstPkg/Read-and-delete-me
./myFirstPkg/man
./myFirstPkg/man/helloworld.Rd
./myFirstPkg/man/myFirstPkg-package.Rd
./myFirstPkg/R
./myFirstPkg/R/helloworld.R

打开Read-and-delete-me,

* Edit the help file skeletons in 'man', possibly combining help files for multiple functions.
* Edit the exports in 'NAMESPACE', and add necessary imports.
* Put any C/C++/Fortran code in 'src'.
* If you have compiled code, add a useDynLib() directive to 'NAMESPACE'.
* Run R CMD build to build the package tarball.
* Run R CMD check to check the package tarball.

Read "Writing R Extensions" for more information.

看完后将其删除。

接着,修改DESCRIPTION以及man目录下的Rd文件。关于Rd文件,请阅读”Writing R Extensions“或者”Parsing Rd files“。
然后就可以试着检查,编译,和安装了。
在命令行下:

R CMD check myFirstPkg
R CMD build myFirstPkg
R CMD INSTALL myFirstPkg

但是,这还没有真正完。一个完整的R扩展包还需要几个文件,其结构应该是这样的:

DESCRIPTION
NAMESPACE
data
	datalist
	mydata.rda
exec
	java.perl.executalbes
inst
	doc
		myFirstPkg.Rnw
	extdata
		myextdata
	unitTests
		test_helloworld.R
man
	helloworld.Rd
	myFirstPkg-package.Rd
R
	helloworld.R
src
	head.h
	code.c
tests
	runTests.R
vignettes
	myFirstPkg.Rnw

其中,data文件夹用于存放二进制文件,对于比较大的数据,保存为二进制比较好。inst中的extdata文件夹也可以用于存放数据,但一般为人类可读的数据。exec文件夹用于保存一些可执行的文件。tests中的runTests.R和unitTests中的所有.R文件联合在一起,形成功能测试(R unit test)。其中runTests.R可能是这样的

require("myFirstPkg") || stop("unable to load Package:myFirstPkg")
BiocGenerics:::testPackage("myFirstPkg")

而unitTests中的.R文件可能是这样的:

test_add<-function(){
	checkEquals(3, myFirstPkg:::add(1,2))
}

具体请参考http://cran.fhcrc.org/web/packages/RUnit/vignettes/RUnit.pdf。

One comment on “如何创建一个R扩展包

  1. Pingback: 使用RStudio结合devtools开发bioconductor扩展包 ← 糗世界

Leave a Reply

  

  

  

%d 博主赞过: