R扩展开发指南：构建与管理R包

154 浏览量更新于2024-07-14 收藏 514KB PDF 举报

身份认证购VIP最低享 7 折!

领优惠券(最高得80元）

《Writing R Extensions》是一本由R Development Core Team编写的指南，于2003年11月21日发布，版本为1.8.1。该手册主要针对R语言的扩展开发提供深入的指导，帮助开发者理解和创建自定义的R包。本书是R软件生态的重要参考资料，包含了关于R包结构、配置管理、打包检查、以及编写package vignettes（包装文档）等核心内容。 1. **包结构与组件**： - `DESCRIPTION`文件：是每个R包的基础，包含了包的基本信息，如包名、版本号、作者、依赖关系、描述等，它是R包的元数据，对于包的安装和管理至关重要。 - `INDEX`文件：虽然在现代R包中可能不常用，但在早期版本中，它用于索引包中的函数和变量，帮助用户快速查找。 - 包子目录：包括源代码文件（`.R`），帮助文档（`.Rd`），以及其他支持文件，如`NAMESPACE`文件用于声明包内的函数和数据。 2. **配置与清理**： - `Makevars`文件：允许开发者自定义编译时的环境变量和选项，这对于调整包性能或处理特定平台特定问题非常有用。 3. **检查与构建**： - 包的构建过程通常通过`R CMD`命令行工具进行，这个阶段涉及编译源代码、检验代码质量和生成文档。开发者需要确保包满足R的API标准，并能顺利通过各种测试。 4. **编写package vignettes**： - Vignettes是R包中可执行的文档，用于展示包如何使用，以及提供的功能实例。它们不仅增强了包的文档性，还提供了一个演示和交互式教程的平台。 5. **提交与分发**： - 根据手册的许可协议，开发者可以自由地复制、分发修改后的版本，但必须保持版权和许可信息不变。此外，翻译版本也受到类似的条件约束，需经过R Development Core Team的认可。《Writing R Extensions》是一本详尽的教程，涵盖了R包开发的各个环节，无论是初学者还是经验丰富的R开发者，都可以从中获得实用的知识和指导，以提升R项目的质量与可维护性。通过遵循其提供的规则，开发者能够更好地融入R生态系统，为开源社区贡献自己的力量。

资源详情

资源推荐

Chapter 1: Creating R packages 9

a dynamic library libRlapack which contains all the double-precision LAPACK

routines as well as those double-complex LAPACK and BLAS routines needed

to build R, or it may point to an external LAPACK library, or may be empty

if an external BLAS library also contains LAPACK.

[There is currently no guarantee that the LAPACK library will provide more

than the double-precision and double-complex driver routines used by R, and

some do not provide all the auxiliary routines.]

The macro BLAS_LIBS should always be included after LAPACK_LIBS.

1.3 Checking and building packages

Using R CMD check, the R package checker, one can test whether source R packages work

correctly. (Under Windows the equivalent command is Rcmd check.) This runs a series of

checks.

1. The package is installed. This will warn about missing cross-references and duplicate

aliases in help ﬁles.

2. The ﬁle names are checked to be valid across ﬁle systems and supported operating

system platforms.

3. The ﬁles and directories are checked for suﬃcient permissions (Unix only).

4. The ‘DESCRIPTION’ ﬁle is checked for completeness, and some of its entries for correct-

ness. Unless installation tests are skipped, checking is aborted if the package depen-

dencies cannot be resolved at run time.

5. Available index information (in particular, for demos and vignettes) is checked for

completeness.

6. The R ﬁles are checked for syntax errors.

7. The R ﬁles are checked for correct calls to library.dynam (with no extension). In ad-

dition, it is checked whether methods have all arguments of the corresponding generic,

and whether the ﬁnal argument of replacement functions is called ‘value’.

8. The Rd ﬁles are checked for the mandatory (\name, \alias, \title, \description

and \keyword) ﬁelds, and for unbalanced braces (which indicate Rd syntax errors).

The R d name and title are checked for being non-empty, and the keywords found are

compared to the standard ones.

9. A check is made for missing doc umentation entries, such as undocumented user-level

objects in the package

10. The functions and their documentation are compared, and any diﬀerences in the call

sequences reported.

11. It is checked whether all function arguments given in \usage sections of Rd ﬁles are

documented in the corresponding \arguments section.

12. C source and header ﬁles are tested for correct (LF-only) line endings.

13. The examples provided by the package’s documentation are run. (see

Chapter 2 [Writ-

ing R documentation ﬁles], page 16, for information on using \examples to create

executable example code.)

Of course, released packages should be able to run at least their own examples.

Chapter 1: Creating R packages 10

14. If the package sources contain a ‘tests’ directory then the tests speciﬁed in that direc-

tory are run. (Typically they will consist of a set of ‘.R’ source ﬁles and target output

ﬁles ‘.Rout.save’.)

15. The code in package vignettes (see Section 1.4 [Writing package vignettes], page 10) is

executed.

16. If a working latex program is available, the ‘.dvi’ version of the package’s manual is

created (to check that the Rd ﬁles can be converted successfully).

Use R CMD check --help (Rcmd check --help on Windows) to obtain more information

about the usage of the R package checker. A subset of the checking steps can be selected

by adding ﬂags.

Using R CMD build, the R package builder, one can build R packages from their source s

(for example, for subsequent release). The Windows equivalent is Rcmd build.

Prior to actually building the package in the common gzipped tar ﬁle format, a variety

of diagnostic checks and cleanups are performed. In particular, it is tested whether the

‘DESCRIPTION’ ﬁle contains the required entries, whether object and data indices exist (it

will build them if they do not) and can be assumed to be up-to-date.

Run-time checks whether the package works correctly should be performed using R CMD

check prior to invoking the build procedure.

To exclude ﬁles from being put into the package, one can specify a list of exclude patterns

in ﬁle ‘.Rbuildignore’ in the top-level source directory. These patterns should be Perl

regexps, one per line, to be matched against the ﬁle names relative to the top-level source

directory. In addition, ﬁles called ‘CVS’ or ‘GNUMakefile’, or with base names starting with

‘.#’, or starting and ending with ‘#’, or ending in ‘~’ or ‘.bak’ or ‘.swp’, are excluded by

default.

Note: ﬁle exclusion does not work correctly with gnu tar 1.13 but does work

with later versions (e.g., version 1.13.17).

Use R CMD build --help (Rcmd build --help on Windows) to obtain more information

about the usage of the R package builder.

R CMD build can also build pre-compiled version of packages for binary distributions.

Note: R CMD check and R CMD build run R with ‘--vanilla’, so none of the

user’s startup ﬁles are read. If you need R_LIBS set (to ﬁnd packages in a

non-standard library) you will need to set it in the environment.

Note to Windows users: Rcmd check and Rcmd build work well under Windows

NT4/2000/XP but may not work correctly on Windows 95/98/ME because of

problems with some versions of Perl on those limited OSes. Experiences vary.

To use them you will need to have installed the ﬁles for building source packages.

1.4 Writing package vignettes

In addition to the help ﬁles in Rd format, R packages allow the inclusion of documents

in arbitrary other formats. The standard location for these is subdirectory ‘inst/doc’ of

a source package, the contents will be copied to subdirectory ‘doc’ when the package is

installed. Pointers from package help indices to the installed documents are automatically

Chapter 1: Creating R packages 11

created. Documents in ‘inst/doc’ can be in arbitrary format, however we strongly rec-

ommend to provide them in PDF format, such that users on all platforms can easily read

them.

A special case are documents in Sweave format, which we call package vignettes. Sweave

allows to integrate LaT

X documents and R code and is contained in package tools which is

part of the base R distribution, see the Sweave help page for details on the document format.

Package vignettes found in directory ‘inst/doc’ are tested by R CMD check by executing all

R code chunks they contain to ensure consistency between code and documentation. Note

that even code chunks with option eval=FALSE are tested, if you want code in a vignette

that s hould not be tested, move it to a normal LaTeX verbatim environment. The reason

for this policy is that users should be able to rely on code examples to be executable as

seen in the vignette. The R working directory for all vignette tests in R CMD check is the

installed version of the ‘doc’ subdirectory. Make sure all ﬁles needed by the vignette (data

sets, . . . ) are accessible by either placing them in the ‘inst/doc’ hierarchy of the source

package, or using calls to system.file().

R CMD build will automatically create PDF versions of the vignettes for distribution

with the package sources. By including the PDF version in the package sources it is not

necessary that the vignettes can be compiled at install time, i.e., the package author c an

use private LaT

X extensions which are only available on his machine. Only the R code

inside the vignettes is part of the checking procedure, typesetting manuals is not part of

the package QC.

By default R CMD build will run Sweave on all ﬁles in Sweave format. If no ‘Makefile’

is found in directory ‘inst/doc’, then texi2dvi --pdf is run on all vignettes. Whenever

a ‘Makefile’ is found, then R CMD build will try to run make after the Sweave step, such

that PDF manuals can be created from arbitrary source formats (plain LaT

X ﬁles, . . . ).

The ‘Makefile’ should take care of both creation of PDF ﬁles and cleaning up afterwards,

i.e., delete all ﬁles that shall not appear in the ﬁnal package archive. Note that the make

step is executed independently from the presence of any ﬁles in Sweave format.

It is no longer necessary to provide a ‘00Index.dcf’ ﬁle in the ‘inst/doc’ directory—

the corresponding information is generated automatically from the \VignetteIndexEntry

statements in all Sweave ﬁles when installing from source, or when using the package builder

(see Section 1.3 [Checking and building packages], page 9). The \VignetteIndexEntry

statement is best placed in LaT

X comment, such that no deﬁnition of the command is

necessary.

At install time an HTML index for all vignettes is automatically created from the

\VignetteIndexEntry statements unless a ﬁle ‘index.html’ exists in directory ‘inst/doc’.

This index is linked into the HTML help system for each package.

1.5 Submitting a package to cran

cran is a network of WWW sites holding the R distributions and contributed code, espe-

cially R packages. Users of R are encouraged to join in the collaborative project and to

submit their own packages to cran.

Chapter 1: Creating R packages 12

Before submitting a package mypkg, do run the following steps to test it is complete and

will install properly. (Unix procedures only, run from the directory containing ‘mypkg’ as a

subdirectory.)

1. Run R CMD check to check that the package will install and will runs its examples, and

that the documentation is complete and can be processed. If the package contains code

that needs to be compiled, try to enable a reasonable amount of diagnostic messaging

(“warnings”) when compiling, such as e.g. ‘-Wall -pedantic’ for tools from GCC, the

Gnu Compiler Collection. (If R was not conﬁgured accordingly, one can achieve this

e.g. via PKG_CFLAGS and related variables.)

2. Run R CMD build to run a few further checks and to make the release ‘.tar.gz’ ﬁle.

Please ensure that you can run through the c omplete procedure with only warnings that

you understand and have reasons not to e liminate.

When all the testing is done, upload the ‘.tar.gz’ ﬁle to

ftp://ftp.ci.tuwien.ac.at/incoming

and send a message to cran@r-project.org about it. The cran maintainers will run these

tests before putting a submission in the main archive.

Currently, packages containing compiled code should contain at most one dot in their

name to work smoothly under Windows.

Note that the fully qualiﬁed name of the ‘.tar.gz’ ﬁle must be of the form

‘package _version [_engine [_type]]’,

where the ‘[ ]’ indicates that the enclosed component is optional, package and version are

the corresponding entries in ﬁle ‘DESCRIPTION’, engine gives the S engine the package is

targeted for and defaults to ‘R’, and type indicated whether the ﬁle contains source or

binaries for a certain platform, and defaults to ‘source’. I.e.,

OOP_0.1-3.tar.gz

OOP_0.1-3_R.tar.gz

OOP_0.1-3_R_source.tar.gz

are all equivalent and indicate an R source package, whereas

OOP_0.1-3_Splus6_sparc-sun-solaris.tar.gz

is a binary package for installation under Splus6 on the given platform.

This naming scheme has been adopted to ensure usability of code across S engines. R

code and utilities operating on package ‘.tar.gz’ ﬁles can only be assumed to work provided

that this naming scheme is respected. Of course, R CMD build automatically creates valid

ﬁle names.

1.6 Package name spaces

R 1.7.0 introduces an experimental name space management system for packages. This

system allows the package writer to specify which variables in the package should be exported

to make them available to package users, and which variables should be imported from other

packages.

The current mechanism

for sp e cifying a name space for a package is to place a

‘NAMESPACE’ ﬁle in the top level package directory. This ﬁle contains name space directives

Alternate approaches are under consideration and may replace this approach in future R releases.

剩余84页未读，继续阅读

weixin_38677190

粉丝: 6
资源: 891

R扩展开发指南：构建与管理R包

typing-extensions-4.5.0-py3-none-any.whl

GitExtensions-2.48.05

GitExtensions-2.49.03-SetupComplete.msi

typing_extensions-3.7.4.3-py_0 下载

E: 无法定位软件包 python3-colcon-common-extensions-ui

pip3 install --upgrade colcon-common-extensions --upgrade-strategy=eager

selenium清除chrome缓存

the 'kotlin-android-extensions' gradle plugin is deprecated. please use this migration guide (https://goo.gle/kotlin-android-extensions-deprecation) to start working with view binding (https://developer.android.com/topic/libraries/view-binding) and the 'kotlin-parcelize' plugin.

Error: 0: couldn't open source file <python3-colcon-common-extensions.ui> python3-colcon-common-extensions.ui: No such file or directory

编写一个shell脚本，内容为以topsec用户执行dpkg -i *.deb gnome-extensions disable desktop-icons@csoriano gnome-extensions disable ubuntu-appindicators@ubuntu.com gnome-extensions disable ubuntu-dock@ubuntu.com gnome-extensions enable hidetopbar@mathieu.bidon.ca

ImportError: cannot import name 'TypeAliasType' from 'typing_extensions'

vscode 插件安装目录

ImportError: cannot import name 'Buffer' from 'typing_extensions' (C:\Users\69515\.conda\envs\py39tf\lib\site-packages\typing_extensions.py)

Wappalyzer扩展下载

python virtualenv typing-extensions

运行之后提示'/mnt/workspace/stable-diffusion-webui/extensions/sdweb-easy-prompt-selector'

platformdirs 3.2.0 requires typing-extensions>=4.5; python_version < "3.8", but you have typing-extensions 3.7.4.3 which is incompatible.

最新资源