2

R CMD build behaves differently whether a Rd file contains \PR{} or not. See Writing R Extensions for details on the macros.

Example when a Rd file does not contain \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'

Example when a Rd file contains \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'

The additional stage (i.e. building the PDF package manual, which can be quite slow on an old computer...) is due to the call to ..Rd2pdf() in .build_packages(). However I do not understand what triggers this stage. In addition, it is triggered only for \PR{} and not for other macros such as \CRANpkg{} and \doi{}.

Can someone trace back what happens and why? The question is on base R functions only. I do not use helpers such as package:devtools.

Minimal test package

Package structure:

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)

Build, check, and install with:

$ R CMD build test
$ R CMD check test_0.1.tar.gz
$ R CMD INSTALL test_0.1.tar.gz
Thomas
  • 457
  • 2
  • 12

2 Answers2

3

Here's an explanation of the mechanism that led to this difference.

You can see the system macro definitions in the file at file.path(R.home(), "share/Rd/macros/system.Rd"). The definition for \PR is

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

The definitions for the others you mention are

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

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

The \CRANpkg macro doesn't execute R code, so it doesn't trigger a package install.

The \doi macro executes code at build time.

Just above the code you linked, you see this test:

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

The manual variable defaults to TRUE, but the command line option --no-manual sets it to FALSE. The next part of the test says you can suppress the manual by a field in the DESCRIPTION file.

The getDynamicFlags() function is looking for code in Rd files executed at install or render time, not build time, so the \doi macro doesn't trigger the build of the reference manual.

The \PR macro doesn't specify the stage when it runs, and the documentation seems silent on the default run time, but apparently getDynamicFlags(Rd)[c("install", "render")] returns TRUE for it. I'd guess the default is render time, in case the URL for the bug database changes in some future version of R. [Edit: the docs do say that the default is "install".]

So to suppress this build, put BuildManual: false in the DESCRIPTION file or --no-manual on the R CMD build command line.

user2554330
  • 37,248
  • 4
  • 43
  • 90
  • Thank you very much for taking the time to write such an educational answer! Do you know where the function `getDynamicFlags` is defined? (did not find using https://github.com/wch/r-source/search?q=getDynamicFlags) – Thomas Feb 16 '22 at 14:04
  • More info on the stage when the macro are run on https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Dynamic-pages – Thomas Feb 16 '22 at 14:05
  • (part 1/2) From https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Building-package-tarballs: – Thomas Feb 16 '22 at 14:54
  • (part 2/2) "Similarly, if the .Rd documentation files contain any \Sexpr macros (see Dynamic pages), the package will be temporarily installed to execute them. Post-execution binary copies of those pages containing build-time macros will be saved in build/partial.rdb. If there are any install-time or render-time macros, a .pdf version of the package manual will be built and installed in the build subdirectory. (...) This can be suppressed by the option --no-manual or if package’s DESCRIPTION contains ‘BuildManual: no’ or similar." – Thomas Feb 16 '22 at 14:55
  • 1
    @Thomas `getDynamicFlags` is an unexported function in the `tools` namespace. You can access it with `tools:::getDynamicFlags`. (GitHub is only showing 2 of ~15 matches.) – Mikael Jagan Feb 16 '22 at 16:16
  • 1
    @Thomas: thanks for the pointer to the docs. I read that, but didn't spot that it said the default stage is "install". I think my guess at the rationale is still valid: the first two parts of the R version can't change for an installed package, so the URL returned by `tools:::Rd_expr_PR` wouldn't be expected to change. I suppose if they need to change it in a patch release they could change the macro run stage. – user2554330 Feb 16 '22 at 19:09
  • @user2554330 Sorry, but what are you referring to with "*the first two parts of the R version* can't change for an installed package"? – Thomas Feb 16 '22 at 21:42
  • 1
    @Thomas: The current R version is 4.1.2. If you install R 4.1.3, you don't need to reinstall packages, because only the third part of the version has changed. But you can't use packages that were installed in 4.1.2 in the eventual 5.1.0 or 4.2.0 because they change the major and minor parts (the first two parts) of the version number. – user2554330 Feb 17 '22 at 11:42
0

Response from R-core on 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.)

Thomas
  • 457
  • 2
  • 12