取决于Rd含量的“R CMD构建”行为

xcitsw88  于 2023-03-20  发布在  其他
关注(0)|答案(2)|浏览(170)

无论Rd文件是否包含\PR{}R CMD build的行为都不同。有关宏的详细信息,请参阅编写R扩展。
Rd文件不包含\PR{}时的示例:

$ R CMD build test
* checking for file 'test/DESCRIPTION' ... OK
* preparing 'test':
* checking DESCRIPTION meta-information ... OK
* installing the package to process help pages
* saving partial Rd database
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building 'test_0.1.tar.gz'

Rd文件包含\PR{}时的示例:

$ R CMD build test
* checking for file 'test/DESCRIPTION' ... OK
* preparing 'test':
* checking DESCRIPTION meta-information ... OK
* installing the package to process help pages
* saving partial Rd database
* building the PDF package manual      # <- this
Hmm ... looks like a package           # <- this
Converting Rd files to LaTeX           # <- this
Creating pdf output from LaTeX ...     # <- this
Saving output to 'xxx/test.pdf' ...    # <- this
Done                                   # <- this
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building 'test_0.1.tar.gz'

额外的阶段(即building the PDF package manual,在旧计算机上可能相当慢...)是由于.build_packages()中对..Rd2pdf()的调用。但是我不明白是什么触发了这个阶段。此外,它只对\PR{}触发,而不对其他宏(如\CRANpkg{}\doi{})触发。
有人能追溯发生了什么以及为什么吗?问题只针对base R函数。我不使用package:devtools这样的助手。

最小测试包

Package 结构:

test
test/man
test/man/one.Rd
test/R
test/R/one.R
test/DESCRIPTION
test/NAMESPACE

test/man/one.Rd

\name{one}
\alias{one}
\title{Get One}
\description{
Rd file containing or not the PR macro:
\PR{1} % comment/uncomment this line as needed
but containing other macros:
\CRANpkg{ggplot2} and \doi{10.1002/wics.147}
}
\usage{
one()
}

test/R/one.R

one <- function() 1

test/DESCRIPTION

Package: test
Version: 0.1
Title: Test
Author: Nobody
Maintainer: Nobody <no@body.org>
Description: Test.
License: GPL-3

test/NAMESPACE

export(one)

使用以下工具生成、检查和安装:

$ R CMD build test
$ R CMD check test_0.1.tar.gz
$ R CMD INSTALL test_0.1.tar.gz
xzlaal3s

xzlaal3s1#

以下是导致这种差异的机制的解释。
可以在file.path(R.home(), "share/Rd/macros/system.Rd")文件中看到系统宏定义。\PR的定义为

\newcommand{\PR}{\Sexpr[results=rd]{tools:::Rd_expr_PR(#1)}}

你提到的其他定义是

\newcommand{\CRANpkg}{\href{https://CRAN.R-project.org/package=#1}{\pkg{#1}}}

\newcommand{\doi}{\Sexpr[results=rd,stage=build]{tools:::Rd_expr_doi("#1")}}

\CRANpkg宏不执行R代码,因此不会触发软件包安装。
\doi宏在生成时执行代码。
就在您链接的代码上方,您会看到以下测试:

needRefman <- manual &&
        parse_description_field(desc, "BuildManual", TRUE) &&
        any(vapply(db,
                   function(Rd)
                       any(getDynamicFlags(Rd)[c("install", "render")]),
                   NA))

manual变量默认为TRUE,但命令行选项--no-manual将其设置为FALSE。测试的下一部分说明您可以通过DESCRIPTION文件中的一个字段取消手动。
getDynamicFlags()函数在Rd文件中查找安装或渲染时执行的代码,而不是构建时执行的代码,因此\doi宏不会触发参考手册的构建。
\PR宏没有指定它运行的阶段,文档中似乎没有提到默认的运行时,但显然getDynamicFlags(Rd)[c("install", "render")]返回了TRUE。我猜默认值是呈现时,以防bug数据库的URL在将来的R版本中发生变化。[编辑:文档确实说默认值是"install"。]
因此,要抑制此构建,请将BuildManual: false放在DESCRIPTION文件中或将--no-manual放在R CMD build命令行中。

yyhrrdl8

yyhrrdl82#

R's Bugzilla上来自R内核的响应:
\PR宏最初只在R自己的NEWS.Rd中使用,其中stage并不真正适用。
Sexpr的默认值stage=install可能有历史原因:我同意stage=build在非基础包中通常是更好的,以避免PDF手册中的tarball文件爆炸。由于\doi宏的原因,通常会包含部分Rd db。
我还没有检查是否/如何修改PR宏而不中断NEWS.Rd处理。注意,WRE中提到的宏只是作为\newcommand的一个例子;我不认为这是通用的。在一个贡献的软件包的帮助中,“PR#”指的是哪个bug跟踪器是不清楚的。在这里简单地包括一个bug报告的普通URL可能会更好。
如果你还想使用它,你可以在Rd文件的开头设置\RdOpts{stage=build}(由于Bug 18073,这需要R〉= 4.1.0)。

相关问题