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

In saurfang/roxyPackage: Utilities to automate package builds

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"),
  local.roxy.dir = NULL, cleanup = FALSE, roxy.unlink.target = TRUE,
  rm.vignette = FALSE, R.homes = R.home(),
  html.index = "Available R Packages", html.title = "R package",
  Rcmd.options = c(install = "", build = "--no-manual --no-build-vignettes",
  check = "--as-cran", Rd2pdf = "--pdf --no-preview"), URL = NULL,
  deb.options = NULL, ChangeLog = list(changed = c("initial release"), fixed
  = c("missing ChangeLog")), Rbuildignore = NULL, Rinstignore = 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).
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	Character string of the release date in YYYY-MM-DD format. Defaults to Sys.Date(). If actions don't include "roxy", then this information is read from the present DESCRIPTION file.
actions	Character vector, must contain at least one of the following values: "roxy" Roxygenize the docs "cite" Update CITATION file "license" Update LICENSE.txt file; it's not called LICENSE to prevent an automatic installation "check" Do a full package check, calling R CMD check "package" Build & install the package, update source repository, calling R CMD build and R CMD INSTALL "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 and vignette (if present), R CMD Rd2pdf (or R CMD Rd2dvi for R < 2.15) "html" Update HTML index files "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) "cleanRd" Insert line breaks in Rd files with lines longer than 90 chars 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.
local.roxy.dir	Character string, path to a directory to roxygenize docs in, if you don't want to do it in place. If NULL (the default) or identical to pck.source.dir, docs will be created in place.
cleanup	Logical, if TRUE will remove backup files (matching .*~$ or .*backup$) from the source directory.
roxy.unlink.target	Logical, setting the unlink.target option of roxygenize
rm.vignette	Logical, if TRUE and a vignette PDF was build during the "doc" action, it 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.
html.index	A character string for the headline of the global index HTML file.
html.title	A character string for the title tag prefix of the package index HTML file.
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 (or R CMD Rd2dvi for R < 2.15). 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.
URL	A character string defining the URL to the root of the repository (i.e., which holds the directories src etc.). This is not the path to the local file system, but should be the URL to the repository as it is available via internet. This option is neccessary for (and only interpreted by) the action "news2rss".
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. As for the other options, if not set, the defaults of debianize will be used.
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.
...	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/leopard/contrib/$RVERSION

Here go the Mac OS X binaries

./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 several R versions

The options R.libs and R.homes can actually take more than one string, but a vector of strings. This can be used to build packages for different R versions, provided you installed them on your system. If you're running GNU/Linux, an easy way of doing so 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 2.12.2 and 2.11.1, you could then call roxy.package with options like R.homes=c("home/user/R/R-2.11.1", "home/user/R/R-2.12.2") and R.libs=c("home/user/R/R-2.11.1/lib64/R/library", "home/user/R/R-2.12.2/lib64/R/library"). roxy.package will then call itself recursively for each given R installation.

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" and "news2rss", should produce identical results anyway, so they are only considered during the first run. You should always place the R version which should be linked to from the HTML index last in line, because "html" will overwrite previous results. For a similar reason, the "deb" action will only actually build a binary package during the last run, but debianizing it will be done during the first.

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.txt") to the function call.

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] http://cran.r-project.org/web/packages/roxygen2/

See Also

sandbox to run roxy.package() in a sandbox.

Examples

## Not run: 
## package description as data.frame:
pckg.dscrptn <- data.frame(
  Package="SquareTheCircle",
  Type="Package",
  Title="Squaring the circle using Heisenberg compensation",
  Author="E.A. Dölle <[e-mail]>",
  AuthorR="c(person(given=\"Ernst\", family=\"Dölle\",
  email=\"[e-mail]\", role=c(\"aut\", \"cre\")))",
  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",
  stringsAsFactors=FALSE)
# 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)

saurfang/roxyPackage documentation built on May 29, 2019, 3:20 p.m.