`R CMD build` 的行为取决于 Rd 内容

Question

无论 Rd 文件是否包含 \PR{}，

R CMD build 的行为都不同。有关宏的详细信息，请参阅 Writing R Extensions。

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，在旧计算机上可能会很慢...）是由于调用了 ..Rd2pdf in .build_packages (lines 619-625)。但是我不明白是什么触发了这个阶段。此外，它仅针对 \PR{} 而不会针对 \CRANpkg{} 和 \doi{}.

等其他宏触发

有人可以追溯发生了什么以及为什么吗？问题仅针对基本 R 函数。我不使用 devtools.

等助手

最小测试包

包结构

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

Answer 1

这里解释了导致这种差异的机制。

您可以在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 宏在构建时执行代码。

在您链接的代码上方，您会看到这个 test:

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")] returns TRUE 就可以了。我猜默认值是渲染时间，以防错误数据库的 URL 在 R 的某些未来版本中发生变化。[编辑：文档确实说默认值是 "install"。]

因此，要抑制此构建，请将 BuildManual: false 放入 DESCRIPTION 文件中，或将 --no-manual 放入 R CMD build 命令行。

Answer 2

R-core 在 R's Bugzilla 上的回复：

The \PR macro has initially been used exclusively in R's own NEWS.Rd, where stage does not really apply.

The stage=install default for Sexpr's probably has historical reasons: build was implemented later. I agree that stage=build is usually preferable in non-base packages to avoid blowing up the tarball with the PDF manual. A partial Rd db is often included anyway because of the \doi macro.

I haven't checked if/how we could modify the PR macro without breaking NEWS.Rd processing. Note that the macro is mentioned in WRE only as an example for \newcommand; I don't think it is of general use. It is unclear to which bug tracker a "PR#" would refer to in the help of a contributed package. It may be better to simply include the plain URL to a bug report here.

If you'd still like to use it, you could set \RdOpts{stage=build} at the beginning of the Rd file. (This requires R >= 4.1.0 due to Bug 18073.)

`R CMD build` 的行为取决于 Rd 内容

Behavior of `R CMD build` depending of Rd content

r

rd

r-package

最小测试包