roxy.package: Automatic doc creation, package building and repository...

In unDocUMeantIt/roxyPackage: Utilities to Automate Package Builds

Automatic doc creation, package building and repository update

Description

This function should help to create R packages with full documentation and updates to a local repository. It supports source and binary packaging (Windows and Mac OS X; see Note section on the limitations).

Usage

roxy.package(
  pck.source.dir,
  pck.version,
  pck.description,
  R.libs,
  repo.root,
  pck.date = Sys.Date(),
  actions = c("roxy", "package"),
  cleanup = FALSE,
  rm.vignette = FALSE,
  R.homes = R.home(),
  R.libs.append = NULL,
  Rcmd.options = c(install = "--install-tests", build =
    "--no-manual --no-build-vignettes --md5", check = "--as-cran", Rd2pdf =
    "--pdf --no-preview"),
  URL = NULL,
  deb.options = NULL,
  readme.options = NULL,
  html.options = NULL,
  ChangeLog = list(changed = c("initial release"), fixed = c("missing ChangeLog")),
  Rbuildignore = NULL,
  Rinstignore = NULL,
  OSX.repo = list(main = "contrib", symlinks = "el-capitan"),
  pck.aliases = NULL,
  ...
)

Arguments

pck.source.dir	Character string, path pointing to the root directory of your package sources.
pck.version	Character string, defining the designated version number. Can be omitted if actions don't include "roxy", then this information is read from the present DESCRIPTION file.
pck.description	Data.frame holding the package description (see Examples section). Any data.frame with valid fields will do, but you should use package_description if possible because it does some basic validity checks.
R.libs	Character string, valid path to the R library where the package should be installed to.
repo.root	Character string, valid path to a directory where to build/update a local package repository.
pck.date	Date class object or character string of the release date in YYYY-MM-DD format. Defaults to Sys.Date(). If actions don't include "roxy" and neither Date, Packaged, nor Date/Publication are found in the present DESCRIPTION file, then pck.date will be used. Otherwise, the information from the DESCRIPTION file is used.
actions	Character vector, must contain at least one of the following values: "roxy" Roxygenize the docs "cite" Update CITATION file "license" Update LICENSE file "readme" Generate initial README.md file "check" Do a full package check, calling R CMD check. Combine with "package" to do the check on the tarball, not the source directory. "package" Build & install the package, update source repository, calling R CMD build and R CMD INSTALL "binonly" Like "package", but doesn't copy the source package to the repository, to enable binary-only rebuilds "gitCheckout" Treats pck.source.dir as a git repository and pck.version as a branch or tag to checkout temporarily; only valid in combination with "binonly" "cl2news" Try to convert a ChangeLog file into an NEWS.Rd file "news2rss" Try to convert inst/NEWS.Rd into an RSS feed. You must also set URL accordingly "doc" Update PDF documentation (R CMD Rd2pdf) and vignettes if present; "html" Update HTML index files and compile HTML versions of README.md and NEWS.md (if pandoc is available). "win" Update the Windows binary package "macosx" Update the Mac OS X binary package "log" Generate initial ChangeLog or update a present ChangeLog file "deb" Update the Debian binary package with debianize (works only on Debian systems; see deb.options, too). URL must also be set to generate Debian repository information "cleanRd" Insert line breaks in Rd files with lines longer than 90 chars "vignette" Generate initial vignette stub in directory vignettes; if html.options has a flattr.id, it will be included "buildVignettes" Re-build all vignettes during the "package" action, to force generation of a vignette index in the source package (recommended if VignetteBuilder is set in the package description) "buildEmAll" Build binary packages for all configured R versions, not just the first. Only effective if multiple versions of R are actually provided (see above) Note that "cl2news" will write the NEWS.Rd file to the inst directory of your sources, which will overwrite an existing file with the same name! Also note that if both a NEWS/NEWS.Rd and ChangeLog file are found, only news files will be linked by the "html" action.
cleanup	Logical, if TRUE will remove backup files (matching .*~$ or .*backup$) from the source directory.
rm.vignette	Logical, if TRUE and a vignette was build during the "doc" action and vignettes live in the directory inst/doc, they will not be kept in the source package but just be moved to the ./pckg/$PACKAGENAME directory of the repository.
R.homes	Path to the R installation to use. Can be set manually to build packages for other R versions than the default one, if you have installed them in parallel. Should probably be used together with R.libs.
R.libs.append	An optional vector of paths pointing to R libraries to always be included for package lookup. These locations will be added to package build calls by appending them to the R_LIBS_USER environment variable accordingly, if not NULL.
Rcmd.options	A named character vector with options to be passed on to the internal calls of R CMD build, R CMD INSTALL, R CMD check and R CMD Rd2pdf. Change these only if you know what you're doing! Will be passed on as given here. To deactivate, options must explicitly be se to "", missing options will be used with the default values. Please note that if you've set VignetteBuilder in the package description, the vignettes will always be re-build if you enabled the "buildVignettes" action, even if you keep --no-build-vignettes in the build options.
URL	Either a single character string defining the URL to the root of the repository (i.e., which holds the directories src etc., see below), or a named character vector if you need different URLs for different services. If you provide more than one URL, these are valid names for values: default A mandatory fallback URL, will be used if not overridden by one of the other values. This is fully equivalent to the global value if only one character string is provided. debian Used for the Debian package repository if different from the default. mirror.list URL pointing to a list of mirrors users should choose from, rather than using one particular host name for the Debian repository. Will only be used in the HTML instructions for a Debian repository. debian.path Can be used to define a custom path users would need to specify in addition to the main URL. Defaults to "/deb", and if given, it must start with a slash. Will be used in combination with default, debian or mirror.list. It is not advisable to combine it with default, because you will have to manually rename the directory generated after each run! These URLs are not the path to the local file system, but should be the URLs to the respecive repository as it is available via internet. This option is necessary for (and only interpreted by) the actions "news2rss", "deb", and possibly "html" – if flattr.id is also set in html.options, a Flattr meta tag be added to the HTML page.
deb.options	A named list with parameters to pass through to debianize. By default, pck.source.dir and repo.root are set to the values given to the parameters above, and if packages are being build for R 3.5, the default deb.dir changes from "deb" to "debR35", and if built for R 4.0 to "debR40". As for the other options, if not set, the defaults of debianize will be used.
readme.options	A named list with parameters that add optional extra information to an initial README.md file, namely instructions to install the package directly from a GitHub repository. Ignore this if you don't use GitHub. Theoretically, you can overwrite all values of the internal function readme_text (e.g., try formals(roxyPackage:::readme_text)). But in practice, these two should be all you need to set: githubUser Your GitHub user name, can be used to contruct the GitHub repo URL All other missing values are then guessed from the other package information. It is then assumed that the GitHub repo has the same name as the package.
html.options	A named list with parameters to be used for generating the HTML files of the repository. These values are recognized: index A character string for the headline of the global index HTML file; if missing, "Available R Packages" will be used as default title A character string for the title tag prefix of the package index HTML file; if missing, "R package" will be used as default flattr.id A Flattr meta ID, will be added to the headers of package specific HTML files, and to a vignette stub if the "vignette" action is active repo.flattr.id A Flattr meta ID, will be added to the headers of all global HTML files of the repository imprint A named character string used as a URL to link to an imprint page; he name is used as the link text privacy.policy A named character string used as a URL to link to a privacy policy statement in accordance with GDPR; the name is used as the link text
ChangeLog	A named list of character vectors with log entry items. The element names will be used as section names in the ChangeLog entry, and each character string in a vector will be pasted as a log item. The news you provide here will be appended to probably present news, while trying to prevent duplicate entries to appear. If you need more control, don't use the "log" action, but have a look at updateChangeLog. Also note that the date of altered entries will be updated automatically, unless you don't call the "roxy" action, too.
Rbuildignore	A character vector to be used as lines of an .Rbuildignore file. If set, this will replace an existing .Rbuildignore file. Setting it to an empty string ("") will remove the file, the default value NULL will simply keep the file, if one is present.
Rinstignore	A character vector to be used as lines of an .Rinstignore file. If set, this will replace an existing .Rinstignore file. Setting it to an empty string ("") will remove the file, the default value NULL will simply keep the file, if one is present.
OSX.repo	A named list of character vectors, one named "main" defines the main directory below ./bin/macosx/ where packages for Mac OS X should be copied, and the second optional one named "symlink" can be used to set symbolic links, e.g., symlinks="el-capitan" would also make the repository available via ./bin/macosx/mavericks. Symbolic links will be ignored when run on on Windows. If you use them, make sure they're correctly transferred to your server, where applicable.
pck.aliases	A character vector, defining all aliases to be used in the *-package.R file. The default NULL results in paste0(pck.description[["Package"]], c("", "-package")) to be set in the *-package.Rd file after roxygenizing the docs. It can be necessary to limit this to paste0(pck.description[["Package"]], "-package") if your package has the same name as one of its exported objects (e.\, g. a function/method) to not end up with two aliases two pck.description[["Package"]] in different files.
...	Additional options passed through to roxygenize.

Details

For the documentation roxygen2[1] is used. Next to the actual in-line documentation of the package's contents, you only need to prepare a data.frame to be used to write a package DESCRIPTION file. See the example section for details on that. This means that you neither edit the DESCRIPTION nor the *-package.R file manually, they will both be created automatically by this function with contents according to these settings!

Sandboxing

If you want to check out the effects of roxy.package() without touching you actual package sources, try sandbox to set up a safe testing environment.

Repository layout

The repository will have this directory structure, that is, below the defined repo.root:

./src/contrib

Here go the source packages

./bin/windows/contrib/$RVERSION

Here go the Windows binaries

./bin/macosx/contrib/$RVERSION

Here go the Mac OS X binaries (see OSX.repo for further options)

./pckg/index.html

A global package index with links to packages' index files, if actions included "html"

./pckg/web.css

A CRAN-style CSS file, if actions included "html"

./pckg/$PACKAGENAME

Here go documentation PDF and vignette, as well as a ChangeLog file, if found. and an index.html with package information, if actions included "html". This is probably a bit off-standard, but practical if you several packages.

Converting ChangeLogs into NEWS

See cl2news for details.

Build for multiple R versions

The options R.libs and R.homes can take a vector of strings. This can be used to build packages for multiple R versions, provided you installed them on your system. By default, roxy.package will only use the first entry of both and ignore the rest, except if you use the "buildEmAll" action. This makes it easy to use roxy.package in a script, as you can turn multiple builds on and off with one action, and leave the rest untouched.

If you're running GNU/Linux, an easy way of preparing for multiple builds is to fetch the R sources from CRAN, calling "./configure" with something like "--prefix=$HOME/R/<R version>", so that "make install" installs to that path. Let's assume you did that with R 3.4.4 and 3.3.3, you could then call roxy.package with options like R.homes=c("home/user/R/R-3.4.4", "home/user/R/R-3.3.3") and R.libs=c("home/user/R/R-3.4.4/lib64/R/library", "home/user/R/R-3.3.3/lib64/R/library"). If you add "buildEmAll" to the actions to perform, roxy.package will then call itself recursively for each given R installation; if you omit "buildEmAll", it will only build packages for R 3.4.4, as that is the first configured version.

One thing you should be aware of is that roxy.package will not perform all actions each time. That is because some of them, namely "roxy", "cite", "license", "doc", "cl2news", "news2rss", "cleanRd", "readme", "buildVignettes", and "vignette", would overwrite previous results anyway, so they are only considered during the first run. Therefore, you should always place the R version which should be used for these actions first in line. The "html" action will list all Windows and OS X binary packages. The "deb" action will only actually debianize and build a binary package during the first run, too.

Windows

On Windows, the actions "doc" and "check" will only work correctly if you have installed and configured LaTeX accordingly, and you will also need Rtools set up for packaging.

CRAN compliance

The CRAN policies can sometimes be very strict. This package should allow you to produce packages which are suitable for release on CRAN. But some steps have to be taken care of by yourself. For instance, CRAN does currently not allow copies of common licenses in a source package, nor a debian folder. Therefore, if your package is supposed to be released on CRAN, you should include Rbuildignore=c("debian", "LICENSE") to the function call.

Temporary git checkouts

If you want to rebuild binaries of something that was already released, i.e. by using the "binonly" action, and if your source directory is a git repository, then the action "gitCheckout" can temporarily checkout the source version to build and switch back to the status quo afterwards again. This might or might not work as you expect, depending on whether you organize your code like it is expected here. That is, each release must be tagged properly, with the exact version number as the tag name. You should also commit all current changes to the code before you use this. Internally, roxy.package will try to find out the current branch of the git repository, then checkout the version number you provided as the new branch or tag, do all the packaging, and checkout bach to the previous branch.

Note

The binary packaging is done simply by zipping (Windows) or targzipping (Mac OS X) the built and installed package. This should do the trick as long as your package is written in pure R code. It will most likely not produce usable packages if it contains code in other languages like C++.

References

[1] https://CRAN.R-project.org/package=roxygen2

See Also

package_description for proper package description, and sandbox to run roxy.package() in a sandbox.

Examples

## Not run: 
## package description as data.frame:
pckg.dscrptn <- package_description(
  Package="SquareTheCircle",
  Type="Package",
  Title="Squaring the circle using Heisenberg compensation",
  Author="Ernst Dölle [aut, cre, cph], Ludwig Dölle [trl,
      ctb] (initial translation to whitespace)",
  AuthorsR="c(person(given=\"Ernst\", family=\"Dölle\",
       email=\"[e-mail]\",
       role=c(\"aut\", \"cre\", \"cph\")),
     person(given=\"Ludwig\", family=\"Dölle\",
       role=c(\"trl\", \"ctb\"),
       comment=\"initial translation to whitespace\")
     )",
  Maintainer="E.A. Dölle <[e-mail]>",
  Depends="R (>= 2.10.0),heisenberg (>= 0.23),tools",
  Enhances="rkward",
  Description="This package squares the circle using Heisenberg compensation.
      The code came from a meeting with Yrla Nor that i had in a dream. Please
      don't forget to chain your computer to the ground, because these
      algorithms might make it fly.",
  License="GPL (>= 3)",
  Encoding="UTF-8",
  LazyLoad="yes",
  URL="http://eternalwondermaths.example.org"
)
# hint no. 1: you *don't* specify version number and release date here,
#   but all other valid fields for DESCRIPTION files must/can be defined
# hint no. 2: most of this rarely changes, so you can add this to the
#   internals of your package and refer to it as
#   roxy.package(pck.description=SquareTheCircle:::pckg.dscrptn, ...)
# hint no. 3: use "AuthorR" for the "Author@R" field, or "AuthorsR" for
# R >= 2.14, to work around naming problems

roxy.package(pck.source.dir="~/my_R_stuff/SquareTheCircle",
  pck.version="0.01-2",
  pck.description=pckg.dscrptn,
  R.libs="~/R",
  repo.root="/var/www/repo",
  actions=c("roxy", "package", "doc"))

## End(Not run)

unDocUMeantIt/roxyPackage documentation built on March 9, 2023, 6:31 p.m.