Package 'roxyPackage' reference manual

Title:	Utilities to Automate Package Builds
Description:	The intention of this package is to make packaging R code as easy as possible. 'roxyPackage' uses tools from the 'roxygen2' package to generate documentation. It also automatically generates and updates files like *-package.R, DESCRIPTION, CITATION, ChangeLog and NEWS.Rd. Building packages supports source format, as well as several binary formats (MS Windows, Mac OS X, Debian GNU/Linux) if the package contains pure R code only. The packages built are stored in a fully functional local R package repository which can be synced to a web server to share them with others. This includes the generation of browsable HTML pages similar to CRAN, with support for RSS feeds from the ChangeLog. Please read the vignette for a more detailed explanation by example.
Authors:	m.eik michalke [aut, cre], Robert Nuske [ctb]
Maintainer:	m.eik michalke <[email protected]>
License:	GPL (>= 3)
Version:	0.10-2
Built:	2024-10-24 04:59:20 UTC
Source:	https://github.com/unDocUMeantIt/roxyPackage

Utilities to Automate Package Builds

Description

The intention of this package is to make packaging R code as easy as possible. 'roxyPackage' uses tools from the 'roxygen2' package to generate documentation. It also automatically generates and updates files like *-package.R, DESCRIPTION, CITATION, ChangeLog and NEWS.Rd. Building packages supports source format, as well as several binary formats (MS Windows, Mac OS X, Debian GNU/Linux) if the package contains pure R code only. The packages built are stored in a fully functional local R package repository which can be synced to a web server to share them with others. This includes the generation of browsable HTML pages similar to CRAN, with support for RSS feeds from the ChangeLog. Please read the vignette for a more detailed explanation by example.

Details

The DESCRIPTION file:

Package:	roxyPackage
Type:	Package
Version:	0.10-2
Date:	2024-07-23
Depends:	R (>= 3.0.0)
Encoding:	UTF-8
License:	GPL (>= 3)
LazyLoad:	yes
URL:	https://reaktanz.de/?c=hacking&s=roxyPackage

Author(s)

m.eik michalke [aut, cre], Robert Nuske [ctb]

Maintainer: m.eik michalke <[email protected]>

Deal with old packages in your local repository

Description

Use this function to move older versions of a package to a specified archive directory, or remove them completely.

Usage

archive.packages(
  repo.root,
  to.dir = "Archive",
  keep = 1,
  keep.revisions = 2,
  package = NULL,
  type = "source",
  archive.root = repo.root,
  overwrite = FALSE,
  reallyDoIt = FALSE,
  graceful = FALSE,
  deb.options = list(distribution = "unstable", component = "main", gpg.version = 2,
    gpg.key = NULL, keyring = NULL, deb.dir = "deb")
)
archive.packages(
  repo.root,
  to.dir = "Archive",
  keep = 1,
  keep.revisions = 2,
  package = NULL,
  type = "source",
  archive.root = repo.root,
  overwrite = FALSE,
  reallyDoIt = FALSE,
  graceful = FALSE,
  deb.options = list(distribution = "unstable", component = "main", gpg.version = 2,
    gpg.key = NULL, keyring = NULL, deb.dir = "deb")
)

Arguments

`repo.root`	Path to the repository root, i.e., the directory which contains the `src` and `bin` directories. Usually this path should start with "`file:///`".
`to.dir`	Character string, name of the folder to move the old packages to.
`keep`	An integer value defining the maximum nuber of versions to keep. Setting this to 0 will completely remove all packages from the repository, which is probably only useful in combination with the option `package`.
`keep.revisions`	An integer value defining the maximum nuber of revisions to keep. This is only used when archiving Debian packages, i.e., if `type` includes `"deb"`. Setting this to 0 or `NULL` will keep all revisions of package versions that are to be kept.
`package`	A character vector with package names to check. If set, `archive.packages` will only take actions on these packages. If `NULL`, all packages are affected.
`type`	A character vector defining the package formats to keep. Valid entries are `"source"`, `"win.binary"`, `"mac.binary"`, and `"deb"`. By default, only the source packages are archived, all other packages are deleted, except for Debian repos, which currently can only be archived or be left as is.
`archive.root`	Path to the archive root, i.e., the directory to which files should be moved. Usually the Archive is kept in `repo.root`.
`overwrite`	Logical, indicates whether existing files in the archive can be overwritten.
`reallyDoIt`	Logical, real actions are only taken if set to `TRUE`, otherwise the actions are only printed.
`graceful`	Logical, if `TRUE` the process will not freak out because of missing files. Use this for instance if you deleted files from the repo but did not update the package indices.
`deb.options`	A named list of options that must be properly set if you want to archive Debian packages. After packages were removed from the repo, all Packages, Sources and Release files must be re-written and signed, and all of the following information is required: `distribution`, `component`, `gpg.key`, `keyring` (which might be `NULL`), and `deb.dir`. If you omit `gpg.version`, version 2 is assumed by default. See `debianize` for details.

Note

This function responds to sandbox.

Examples

## Not run: 
# dry run, only prints what would happen, so you can check
# if that's really what you want
archive.packages("file:///var/www/repo")

# after we've confirmed that the right packages will be moved
# and deleted, let's actually commit the changes
archive.packages("file:///var/www/repo", reallyDoIt=TRUE)

# if we don't want a standard archive, but for instance a parallel
# archive repository, we can have it. let's move all but the latest two
# versions from /var/www/repo to /var/www/archive. to suppress the
# creation of a special archive directory, we set to.dir=""
archive.packages("file:///var/www/repo", to.dir="", keep=2,
  type=c("source", "win.binary", "mac.binary"),
  archive.root="/var/www/archive", reallyDoIt=TRUE)

## End(Not run)
## Not run: 
# dry run, only prints what would happen, so you can check
# if that's really what you want
archive.packages("file:///var/www/repo")

# after we've confirmed that the right packages will be moved
# and deleted, let's actually commit the changes
archive.packages("file:///var/www/repo", reallyDoIt=TRUE)

# if we don't want a standard archive, but for instance a parallel
# archive repository, we can have it. let's move all but the latest two
# versions from /var/www/repo to /var/www/archive. to suppress the
# creation of a special archive directory, we set to.dir=""
archive.packages("file:///var/www/repo", to.dir="", keep=2,
  type=c("source", "win.binary", "mac.binary"),
  archive.root="/var/www/archive", reallyDoIt=TRUE)

## End(Not run)

Convert ChangeLog/NEWS into NEWS.Rd

Description

This function attempts to translate ASCII ChangeLog (or NEWS) files into NEWS.Rd files.

Usage

cl2news(log, news = NULL, codify = TRUE, overwrite = TRUE)
cl2news(log, news = NULL, codify = TRUE, overwrite = TRUE)

Arguments

`log`	Character string, path to the ChangeLog or NEWS file to be converted.
`news`	Character string, path to the NEWS.Rd file to be written. If `NULL`, results are written to `stdout()`.
`codify`	Logical, whether to try to detect code snippets like function names and markup them accordingly.
`overwrite`	Logical, whether to overwrite an existing NEWS.Rd file.

Details

This should work for ChangeLog and NEWS files that

have entries named "Changes in version <version number>" (and optionally a YYYY-MM-DD date string afterwards)
have single changes properly itemized, by indentation and then either "o", "-" or "*" followed by space
optionally have categories as subsections, like "Fixed" or "Added"

Any text string that isn't indented and doesn't start with "Changes in version" will likely be treated as a subsection. The ChangeLog related functions and methods of this package, e.g. initChangeLog, are a convenient way to maintain R ChangeLogs in a proper format.

This function is basically a wrapper for the internal function tools:::news2Rd.

Value

No return value, writes a file.

Examples

## Not run: 
cl2news(log="~/myFiles/myRPackage/ChangeLog", news="~/myFiles/myRPackage/inst/NEWS.Rd")

# use capture.output() to dump the results into a character vector
NEWS.object <- capture.output(cl2news(log="~/myFiles/myRPackage/ChangeLog"))

## End(Not run)
## Not run: 
cl2news(log="~/myFiles/myRPackage/ChangeLog", news="~/myFiles/myRPackage/inst/NEWS.Rd")

# use capture.output() to dump the results into a character vector
NEWS.object <- capture.output(cl2news(log="~/myFiles/myRPackage/ChangeLog"))

## End(Not run)

Basic Debian package creation from R source packages

Description

This function attempts to 'debianize' your R source package. This means, it will add a debian directory to sources' root directory, and populate it with needed files for Debian package building, as outlined in the Debian R Policy by Eddelbuettel & Bates (2003) and the Debian Policy Manual[1], version 3.9.3.1.

Usage

debianize(
  pck.source.dir,
  repo.root,
  build.dir = tempdir(),
  revision = 1,
  repo.name = "roxypackage",
  origin = paste0("other-", repo.name),
  distribution = "unstable",
  component = "main",
  urgency = "low",
  changelog = c("new upstream release"),
  deb.description = NULL,
  depends.origin = "cran",
  depends.origin.alt = list(),
  actions = c("deb", "bin", "src"),
  overwrite = c("changelog", "control", "copyright", "rules", "compat"),
  bin.opts = "-rfakeroot -b -uc",
  arch = "all",
  compat = 10,
  epoch = NULL,
  gpg.key = NULL,
  keyring = NULL,
  gpg.version = 2,
  deb.keyring.options = NULL,
  compression = "xz",
  keep.build = FALSE,
  keep.existing.orig = FALSE,
  replace.dots = FALSE,
  deb.dir = "deb",
  R.libs.append = NULL
)
debianize(
  pck.source.dir,
  repo.root,
  build.dir = tempdir(),
  revision = 1,
  repo.name = "roxypackage",
  origin = paste0("other-", repo.name),
  distribution = "unstable",
  component = "main",
  urgency = "low",
  changelog = c("new upstream release"),
  deb.description = NULL,
  depends.origin = "cran",
  depends.origin.alt = list(),
  actions = c("deb", "bin", "src"),
  overwrite = c("changelog", "control", "copyright", "rules", "compat"),
  bin.opts = "-rfakeroot -b -uc",
  arch = "all",
  compat = 10,
  epoch = NULL,
  gpg.key = NULL,
  keyring = NULL,
  gpg.version = 2,
  deb.keyring.options = NULL,
  compression = "xz",
  keep.build = FALSE,
  keep.existing.orig = FALSE,
  replace.dots = FALSE,
  deb.dir = "deb",
  R.libs.append = NULL
)

Arguments

`pck.source.dir`	Character string, path pointing to the root directory of your package sources, to a local R package source tarball, or a full URL to such a package tarball. Tarballs will be downloaded to a temporary directory, if needed, extracted, and then debianized.
`repo.root`	Character string, valid path to a directory where to build/update a local package repository.
`build.dir`	Character string, valid path to a directory where to build the package. If this directory is not empty, a temporary directory will be created inside automatically.
`revision`	Numeric or a character string, the Debian package revision information.
`repo.name`	Character string, the name for your debian package repository. This can be used to generate an OpenPGP debian package from the given `gpg.key`, unless you change the default behaviour with the parameter `deb.keyring.options`
`origin`	Character string, should be either "noncran" or "other-<yourname>", used for the package name. This indicates that your package is not an official CRAN or BioC package.
`distribution`	Character string, the Debain (based) distribution your package is intended for.
`component`	Character string, the Debain component of the distribution.
`urgency`	Character string, urgency information for this release (refer to [1] if you want to change this).
`changelog`	Character vector, log entries for the `./debian/changelog` file if it is going to be changed.
`deb.description`	A named list or data.frame with further information, especially for the `./debian/control` file. This is similar to the `pck.description` parameter of `roxy.package`, only with different variables. Note that if certain key values are missing, `debianize` will automatically use some defaults: Build.Depends.Indep `"debhelper (>> 9.0.0), r-base-dev (>= <R.vers>), cdbs"`, plus Depends/Imports in `DESCRIPTION` in debianized format; if `arch` is not set to `"all"`, the field `Build.Depends` is used instead Depends `"r-base-core (>= <R vers>)"`, plus Depends/Imports in `DESCRIPTION` in debianized format. Packages build for R 3.5 will depened on `"r-api-3.5"`, for R 3.4 on `"r-api-3.4"`, and since R 3.2 on `"r-api-3"`, too. Suggests Suggests in `DESCRIPTION` in debianized format Maintainer generated from `Sys.info` (`user <login@nodename>`), with a warning. Section `"gnu-r"` Priority `"optional"` Homepage URL in `DESCRIPTION` Refer to [1] for further available fields in the `./debian/control` file. In case you would like to add to the fields definig relations to other packages like `Build.Depends.Indep` or `Depends` rather than replacing them, provide a named list with a character vector called "append". For example: `Depends=list(append=c("libmysql++3"))`.
`depends.origin`	A character string to set the default origin for R packages which are a dependency of this one. In case all dependencies can be met by Debian packages from CRAN releases, you can leave this to the default setting. If you need more control, see `depends.origin.alt`.
`depends.origin.alt`	A named list of alternative origins for R packages which are a dependency of this one. By default, `depends.origin` is used, but if you know that certain dependencies are of different origin (e.g., your own repository), you can set this here. Each list element must be named after the R package you want to set an origin for, and must be a character vector or single string, like `list(foo="other-janedoe")`. If more than one origin is given, they will be set as alternatives (using the pipe `"\|"` as "or"). For full control over the package name use `list(foo=NULL)`, which will fallback to `foo` as the name of the Debian package.
`actions`	Character vector, naming the actions to perform: "deb" Debianize the package sources. "bin" Build the Debian package. "src" Build a Debian source package.
`overwrite`	Character vector, naming the files which should be updated: "changelog" Update `./debian/changelog`, but only if no entry for this package version and revision is there yet "compat" Re-write `./debian/compat` "control" Re-write `./debian/control` "copyright" Re-write `./debian/copyright` "rules" Re-write `./debian/rules` "gpg.key" Re-write the keyring package in the repository (by default present packages are left unchanged)
`bin.opts`	Character string, options to pass through to `dpkg-buildpackage` for the `"bin"` action.
`arch`	Character string, architecture the package is build for.
`compat`	Integer value, specifying the `debhelper` compatibility level.
`epoch`	Integer value, the Debian package epoch information.
`gpg.key`	Character string, the GnuPG key ID for the key that should be used for signing the Release file (secure apt). This key must be available in your keyring (or in the one specified by `keyring`). Note that this function defaults to using the SHA256 algorithm for signing (not SHA1). Mandatory for `"bin"` and `"src"` actions.
`keyring`	Character string, path to an additional keyring file to use.
`gpg.version`	Integer number, specifiying the GnuPG major version number. By default `gpg2` is assumed.
`deb.keyring.options`	Named list, extra options to pass through to `debianizeKeyring`. By default, the value for `maintainer` will be taken from `deb.description`, and the values for `gpg.key`, `repo.name`, `repo.root`, `build.dir`, `distribution`, `component`, `urgency`, `keyring`, and `gpg.version` are taken from the settings given with the `debianize` function call.
`compression`	Character string, compression format for Debian source packages. Currently `"xz"` and `"gzip"` are supported.
`keep.build`	Logical. If `build.dir` is not `pck.source.dir`, work is done in generated folder with a random name. Usually it is removed afterwards, unless you set this option to `TRUE`.
`keep.existing.orig`	Logical, if `TRUE` and there is already a `*.orig.tar.[gz\|xz]` archive in the repository matching this version, it will not be replaced with a re-packaged one but remains as is. This is useful for binary-only rebuilds.
`replace.dots`	Logical. The proposed Debian R Policy actually asks to replace all dots in package names by hyphens. However, this is implemented differently in `r-cran.mk` and will lead to unbuildable packages. So the default here is to ignore the policy draft and keep dots in package names, as is true for a lot of CRAN packages as well (code is law). In case you run into problems here (symptoms include a failing .deb build because the directory `build/<package name>` doesn't exist), try turning this switch. If `TRUE` dots will be replaced by hyphens in both source and binary package names. Note that building a package by calling this function should always work, because it will automatically create a symlink in the build directory if needed.
`deb.dir`	Character string, name to use for the root directory of the debian repository. Defaults to `"deb"`, which is obviously a good choice, but you might want to use different directories for different builds, e.g., a separate one for R 3.5 packages.
`R.libs.append`	An optional vector of paths pointing to R libraries to 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`. This is only only useful if R packages are provided by dependencies but not installed to default locations, so you need to point to them explicitly in order for the packaging to finish successfully.

Details

The file ./debian/source/format will also be created only once. The files ./debian/control, ./debian/copyright and ./debian/rules will be generated from the information found in the DESCRIPTION file of the R package. Once created, these files won't be touched again if they are not defined in the overwrite parameter. This enables you to save files from being re-written, e.g. if you altered them manually.

The ./debian/changelog is special here, as overwrite doesn't mean the whole file will be overwritten, but rather that the function checks if the changelog already contains an entry for this particular package version and revision, and only if this is not the case will add one at the beginning of the file, including the log entries defined by the changelog parameter (each string will become one log entry).

The function will try to detect the license you specified in the DESCRIPTION file, and if it is one of the following licenses, generate some useful info on how to get the full license on a Debian system:

Apache License
Artisitic License
BSD License
GNU General Public License (GPL)
GNU Lesser General Public License (LGPL)

Building the actual package

If you're running the R session on a Debian based system, the function can build the debian package, but it would likely fail when it comes to signing the .changes/.dsc files, because gpg gets invoked without "--no-tty". You'd have to sign those files later, e.g. with debsign, if you really need this. However, secure-apt can still be ensured, if you provide a valid GnuPG key ID from your keyring, which will then be used to sign the generated Release file. If not present yet, a copy of the public key will automatically be saved to the repository, in a file named <key ID>.gpg.

Package building is done in a temporal directory, and the source files a copied there first. Set build.dir=pck.source.dir if you want to build in-place instead.

Package dependencies

This function will make no attempts to guess what package dependencies must be fulfilled. That is, if the defaults don't fit (see below), then you must define these dependencies yourself via the deb.description parameter (setting appropriate values for fields like Build.Depends, Build.Depends.Indep and Depends). In case your R package depends on other R packages, you will have to ensure that these are also available as Debian packages (and define them as dependencies), so the package management can take care of resolving these dependencies transparently. Otherwise users might have a hard time figuring out how to get your package to work, if the building process doesn't fail in the first place.

That said, you should always try to debianize the package without manual dependencies set first. After that, look at the generated control file and see if there are problems at all. Usually the default method is supposed to be quite clever when it comes to detect dependencies from the actual package DESCRIPTION file (it will automatically translate those into proper Debain package names, where tuning is possible via the depends.origin and depends.origin.alt parameters).

Repository access

After you debianized your package and built some Debian packages, debianize will prepare a Debain package repository in the specified directory (can be the same as used with roxy.package). You can now access it locally on your machine, or upload the whole thing to a web server etc. Basically, it should work if you add these lines to your repository configuration:

deb http://<URL you uploaded to>/deb <distribution> <component>

deb-src http://<URL you uploaded to>/deb <distribution> <component>

Debianizing arbitrary packages

With a little luck, this function can almot automatically debianize any R package sources. You can even provide the pck.source.dir parameter with a URL to package sources (e.g., a source package from CRAN), and debianize will do its best to end up with an installable debian package in the specified repository root.

Note

Please note that the package will always be built against the R version installed by your package management! Also, this function responds to sandbox.

References

Eddelbuettel, D. & Bates, D. (2003). Debian R Policy – Draft Proposal v 0.1.3. Available from http://lists.debian.org/debian-devel/2003/12/msg02332.html

[1] Debian Policy Manual: http://www.debian.org/doc/debian-policy

Examples

## Not run: 
debianize(
  pck.source.dir="~/my_R_stuff/SquareTheCircle",
  repo.root="/var/www/repo",
  origin="other-doelle",
  revision=4,
  changelog=c("re-compiled docs"),
  deb.description=list(
    Depends=c("r-base-dev (>= 3.5.0), r-api-3.5, r-cran-foreign"),
    Maintainer="A. Sistent <[email protected]>"),
  actions=c("deb"))

# let's try to debianize some R package from CRAN
debianize(
  pck.source.dir="http://cran.r-project.org/src/contrib/roxygen2_4.0.1.tar.gz",
  repo.root=tempdir(),
  deb.description=list(
    Maintainer="A. Sistent <[email protected]>"
  )
)

## End(Not run)
## Not run: 
debianize(
  pck.source.dir="~/my_R_stuff/SquareTheCircle",
  repo.root="/var/www/repo",
  origin="other-doelle",
  revision=4,
  changelog=c("re-compiled docs"),
  deb.description=list(
    Depends=c("r-base-dev (>= 3.5.0), r-api-3.5, r-cran-foreign"),
    Maintainer="A. Sistent <[email protected]>"),
  actions=c("deb"))

# let's try to debianize some R package from CRAN
debianize(
  pck.source.dir="http://cran.r-project.org/src/contrib/roxygen2_4.0.1.tar.gz",
  repo.root=tempdir(),
  deb.description=list(
    Maintainer="A. Sistent <[email protected]>"
  )
)

## End(Not run)

Package your OpenPGP keyring in Debian package format

Description

Similar to debianize, this function generates a Debian package, but it specialises on packaging OpenPGP/GnuPG keyrings. The resulting package can be used to provide keys in a Debian package repository, hence enabling secure apt. They are probably easier to handle for users.

Usage

debianizeKeyring(
  gpg.key,
  repo.name,
  repo.root,
  maintainer,
  build.dir = tempdir(),
  keyname = paste0(repo.name, "-keyring"),
  pck.source.dir = file.path(tempdir(), keyname),
  version = "0.01",
  revision = 1,
  distribution = "unstable",
  component = "main",
  urgency = "low",
  URL = NULL,
  changelog = c("new upstream release"),
  description = paste0("OpenPGP keyring for the ", repo.name, " repository\n\n",
    "Provides the keyring for Debian packages hosted at the ", repo.name,
    " repository. It is necessary to be able to use secure apt."),
  actions = c("bin", "src"),
  overwrite = c("changelog", "control", "copyright", "install", "rules", "compat"),
  bin.opts = "-rfakeroot -b -uc",
  compat = 10,
  epoch = NULL,
  keyring = NULL,
  gpg.version = 2,
  sign.key = gpg.key,
  compression = "xz",
  keep.build = FALSE,
  deb.dir = "deb"
)
debianizeKeyring(
  gpg.key,
  repo.name,
  repo.root,
  maintainer,
  build.dir = tempdir(),
  keyname = paste0(repo.name, "-keyring"),
  pck.source.dir = file.path(tempdir(), keyname),
  version = "0.01",
  revision = 1,
  distribution = "unstable",
  component = "main",
  urgency = "low",
  URL = NULL,
  changelog = c("new upstream release"),
  description = paste0("OpenPGP keyring for the ", repo.name, " repository\n\n",
    "Provides the keyring for Debian packages hosted at the ", repo.name,
    " repository. It is necessary to be able to use secure apt."),
  actions = c("bin", "src"),
  overwrite = c("changelog", "control", "copyright", "install", "rules", "compat"),
  bin.opts = "-rfakeroot -b -uc",
  compat = 10,
  epoch = NULL,
  keyring = NULL,
  gpg.version = 2,
  sign.key = gpg.key,
  compression = "xz",
  keep.build = FALSE,
  deb.dir = "deb"
)

Arguments

`gpg.key`	Character string or vector, the OpenPGP key ID(s) for the key(s) that should be included in the package. All keys must be available in your keyring (or in the one specified by `keyring`).
`repo.name`	Character string, name of the repository this keyring will be used for. Must not include spaces or special characters!
`repo.root`	Character string, valid path to a directory where to build/update a local package repository.
`maintainer`	Character string, name an mail address of the maintainer of the keyring package, in the format of `firstName lastName <[email protected]>`.
`build.dir`	Character string, valid path to a directory where to build the package. If this directory is not empty, a temporary directory will be created inside automatically.
`keyname`	Character string, a name for keyring. Will be used for both the exported keyring file and debian package name. Using something like `"myrepo-keyring"` is a good choice.
`pck.source.dir`	Character string, path pointing to the root directory of the keyring package sources. If this directory does not exist yet, it will be created and filled with the necessary files.
`version`	Numeric or a character string, the main Debian package version indicator for the keyring package.
`revision`	Numeric or a character string, the Debian package revision information.
`distribution`	Character string, the Debain (based) distribution your package is intended for.
`component`	Character string, the Debain component of the distribution.
`urgency`	Character string, urgency information for this release (refer to [1] if you want to change this).
`URL`	Character string, should point to the repository this keyring package is built for.
`changelog`	Character vector, log entries for the `./debian/changelog` file if it is going to be changed.
`description`	Character string, some description of the keyring package.
`actions`	Character vector, naming the actions to perform: "bin" Build the Debian package. "src" Build a Debian source package.
`overwrite`	Character vector, naming the files which should be updated: "changelog" Update `./debian/changelog`, but only if no entry for this package version and revision is there yet "compat" Re-write `./debian/compat` "control" Re-write `./debian/control` "copyright" Re-write `./debian/copyright` "postinst" Re-write `./debian/postinst` "prerm" Re-write `./debian/prerm` "rules" Re-write `./debian/rules` "gpg.key" Re-write the exported key in `./keyrings/`
`bin.opts`	Character string, options to pass through to `dpkg-buildpackage` for the `"bin"` action.
`compat`	Integer value, specifying the `debhelper` compatibility level.
`epoch`	Integer value, the Debian package epoch information.
`keyring`	Character string, path to an additional keyring file to use.
`gpg.version`	Integer number, specifiying the GnuPG major version number. By default `gpg2` is assumed.
`sign.key`	Character string, the OpenPGP key ID for the key that should be used for signing the Release file (secure apt). This key must be available in your keyring (or in the one specified by `keyring`). Skipped if `NULL`.
`compression`	Character string, compression format for Debian source packages. Currently `"xz"` and `"gzip"` are supported.
`keep.build`	Logical. If `build.dir` is not `pck.source.dir`, work is done in generated folder with a random name. Usually it is removed afterwards, unless you set this option to `TRUE`.
`deb.dir`	Character string, name to use for the root directory of the debian repository. See `debianize` for details.

Examples

## Not run: 
debianizeKeyring(
  gpg.key="DDCDA632",
  repo.name="doelle",
  repo.root="/var/www/repo",
  maintainer="A. Sistent <[email protected]>"
)

## End(Not run)
## Not run: 
debianizeKeyring(
  gpg.key="DDCDA632",
  repo.name="doelle",
  repo.root="/var/www/repo",
  maintainer="A. Sistent <[email protected]>"
)

## End(Not run)

Download package dependencies

Description

Tries to fetch all (missing) R packages to successfully build a Debian package. The packages are downloaded in source format for you to debianize, but dep4deb can try to check for available Debian packages instead.

Usage

dep4deb(
  pck.source.dir,
  pck.name = NULL,
  destdir = file.path(tempdir(), "roxyPackge", "downloads"),
  repos = getOption("repos"),
  all = FALSE,
  check.deb = TRUE,
  origin = "cran",
  origin.alt = list(),
  available = NULL
)
dep4deb(
  pck.source.dir,
  pck.name = NULL,
  destdir = file.path(tempdir(), "roxyPackge", "downloads"),
  repos = getOption("repos"),
  all = FALSE,
  check.deb = TRUE,
  origin = "cran",
  origin.alt = list(),
  available = NULL
)

Arguments

`pck.source.dir`	Character string, path pointing to the root directory of your package sources, to a local R package source tarball, or a full URL to such a package tarball. Tarballs will be downloaded to `destdir`, if needed, extracted, and then checked for dependencies. Will be ignored if `pck.name` is not `NULL`.
`pck.name`	Character string, the package name. This is an alternative to using `pck.source.dir`.
`destdir`	File path to the directory where all downloaded files should be saved to.
`repos`	Character vector, the base URL(s) of the repositories to use (see `download.packages`).
`all`	Logical, if `FALSE` only currently missing packages are downloaded, where "missing" means that there is no Debian package if these packages installed. If `TRUE` and `check.deb=FALSE`, all dependencies will be downloaded.
`check.deb`	Logical, `TRUE` it will be checked if a debian package can be found, and if that is the case, its name is added to the results and the download skipped. If `all=FALSE`, packages will only be listed in the results if they are not installed.
`origin`	A character string for the package origin, see `debianize`.
`origin.alt`	A named list for more complex origin configuration, see `debianize`.
`available`	An object as returned by `available.packages` listing packages available at the repositories, or NULL which makes an internal call to available.packages.

Details

The function works its way recursively through the dependencies of the dependencies, beginning with the original package given. To make it easier for you to debianize the downloaded packages in a proper order, all downloads will be stored in numbered subfolders of the main download folder, and you should work from the highest number backwards.

Value

Returns a list with two elements:

dl: A matrix as returned by download.packages, listing all downloaded sources
deb: A character vector naming already available Debian packages

Examples

## Not run: 
dep4deb(pck.name="roxyPackage")

## End(Not run)
## Not run: 
dep4deb(pck.name="roxyPackage")

## End(Not run)

Translate character string into HTML entities

Description

Translate character string into HTML entities

Usage

entities(string, collapse = TRUE)
entities(string, collapse = TRUE)

Arguments

`string`	Character string to be translated.
`collapse`	Logical, if `TRUE` one single string is returned

Value

Either a named character vector, one element for each character, or a single string.

Examples

entities("foo_bar")
entities("foo_bar")

Read/write ChangeLog objects

Description

This methods can be used to manage ChangeLog objects.

Usage

getChangeLogEntry(log, ...)

## S4 method for signature 'ChangeLog'
getChangeLogEntry(log, version = NULL)
getChangeLogEntry(log, ...)

## S4 method for signature 'ChangeLog'
getChangeLogEntry(log, version = NULL)

Arguments

`log`	An object of class `ChangeLog`.
`...`	Additional options, as of now only `version` is supported (see below).
`version`	Character string, version number to look up.

Details

getChangeLogEntry takes a ChangeLog object and a version number string and returns the according entry.

Value

An object of class ChangeLog.

Examples

## Not run: 
changelog <- readChangeLog("/home/user/myRsources/myRpackage/ChangeLog")
CL.entry <- getChangeLogEntry(changelog, version="0.02-22")

## End(Not run)
## Not run: 
changelog <- readChangeLog("/home/user/myRsources/myRpackage/ChangeLog")
CL.entry <- getChangeLogEntry(changelog, version="0.02-22")

## End(Not run)

Generate RSS feeds from R NEWS files

Description

This function should take either HTML or Rd files and return a valid RSS 2.0 XML file.

Usage

news2rss(
  news,
  rss = NULL,
  html = NULL,
  encoding = "UTF-8",
  channel = c(title = "", link = "", description = "", language = "", atom = "")
)
news2rss(
  news,
  rss = NULL,
  html = NULL,
  encoding = "UTF-8",
  channel = c(title = "", link = "", description = "", language = "", atom = "")
)

Arguments

`news`	Character string, path to the R NEWS file to be converted.
`rss`	Character string, path to the RSS.xml file to be written. If `NULL`, results are written to stdout().
`html`	Logical, whether `news` is in HTML or Rd format. If `NULL`, guess this from the file ending.
`encoding`	Character string, how the feed is encoded.
`channel`	A named character vector with information on this RSS feed: `title`: Title of the feed, probably the package name. `link`: URL to the package web page, e.g. its repository site. `description`: Descriptions of the feed, e.g. the package. `language`: Optional, a valid RSS language code, see `http://www.rssboard.org/rss-language-codes`. `atom`: Optional, full URL to the RSS feed on the web, used for `atom:link rel="self"`.

Value

No return value, writes a file or to stdout()

Examples

## Not run: 
channel.info <- c(
  title="roxyPackage",
  link="http://R.reaktanz.de/pckg/roxyPackage",
  description="Utilities to Automate Package Builds",
  atom="http://R.reaktanz.de/pckg/roxyPackage/rss.xml")
rss.tree <- news2rss("~/R/roxyPackage/NEWS.Rd",
  channel=channel.info)

## End(Not run)
## Not run: 
channel.info <- c(
  title="roxyPackage",
  link="http://R.reaktanz.de/pckg/roxyPackage",
  description="Utilities to Automate Package Builds",
  atom="http://R.reaktanz.de/pckg/roxyPackage/rss.xml")
rss.tree <- news2rss("~/R/roxyPackage/NEWS.Rd",
  channel=channel.info)

## End(Not run)

Download ORCID icon

Description

A simple wrapper for download.file to download the official ORCID icon for use in a repository with authenticated ORCID IDs.

Usage

orcid_icon_fetcher(
  repo,
  filename = "orcid.svg",
  url = "https://ndownloader.figshare.com/files/8439047",
  method = "auto",
  overwrite = FALSE,
  ...
)
orcid_icon_fetcher(
  repo,
  filename = "orcid.svg",
  url = "https://ndownloader.figshare.com/files/8439047",
  method = "auto",
  overwrite = FALSE,
  ...
)

Arguments

`repo`	The repository root directory to save the file.
`filename`	Target filename.
`url`	The URL to fetch the SVG file from.
`method`	The download method to use, see `download.file`.
`overwrite`	If `FALSE` (default) and the target file already exists, it will not be replaced with a newly downloaded one.
`...`	Further arguments to pass to `download.file`, exept for `mode` (see Note).

Note

The mode argument is fixed to "wb" (binary) to ensure successful downloads also on Windows systems.

Examples

## Not run: 
orcid_icon_fetcher("/tmp")

## End(Not run)
## Not run: 
orcid_icon_fetcher("/tmp")

## End(Not run)

Generate a valid package description

Description

Use this function to describe your package. It will do some plausibility checks and make sure you end up with the correct format and all info needed for proper packaging.

Usage

package_description(
  Package,
  Title,
  Description,
  AuthorsR,
  Author = NULL,
  Maintainer = NULL,
  Depends = NULL,
  Imports = NULL,
  Enhances = NULL,
  Suggests = NULL,
  VignetteBuilder = NULL,
  URL = NULL,
  BugReports = NULL,
  Additional_repositories = NULL,
  Type = "Package",
  License = "GPL (>= 3)",
  Encoding = "UTF-8",
  LazyLoad = "yes",
  extra = list()
)
package_description(
  Package,
  Title,
  Description,
  AuthorsR,
  Author = NULL,
  Maintainer = NULL,
  Depends = NULL,
  Imports = NULL,
  Enhances = NULL,
  Suggests = NULL,
  VignetteBuilder = NULL,
  URL = NULL,
  BugReports = NULL,
  Additional_repositories = NULL,
  Type = "Package",
  License = "GPL (>= 3)",
  Encoding = "UTF-8",
  LazyLoad = "yes",
  extra = list()
)

Arguments

`Package`	Mandatory: Name of the package.
`Title`	Mandatory: Short description in one catchy sentence and with proper capitalization.
`Description`	Mandatory: Long description.
`AuthorsR`	Mandatory: A character string that, if parsed and evaluated, will result in a vector of `person` objects (see example). All authors, maintainers and significant comtributors must be given.
`Author`	Optional author field in old format. Should be omitted for CRAN releases, as it is automatically generated from `AuthorsR`.
`Maintainer`	Like `Author`, but for the maintainer field.
`Depends`	Optional: Comma separated names of packages this package depends on.
`Imports`	Optional: Comma separated names of packages this package imports from.
`Enhances`	Optional: Comma separated names of packages this package enhances.
`Suggests`	Optional: Comma separated names of packages this package suggests.
`VignetteBuilder`	Optional: Specify a vignette builder, e.g., `"knitr"` for vignettes in RMarkdown format.
`URL`	Optional: Homepage.
`BugReports`	Optional URL to a bug tracker, mailing list etc.
`Additional_repositories`	Optional URL to additional repositories for suggested packages that are not available from the standard repos.
`Type`	"Package" Package type, mandatory.
`License`	"GPL (>= 3)" Optional: License information.
`Encoding`	"UTF-8" Optional: Default character encoding.
`LazyLoad`	"yes" Optional: Should lazy loading be supported?
`extra`	A named list of character strings with additional extra fields not explicitly defined above, will be added as-is.

Details

It might seem odd that it does not use the dots argument for additional parameters. That is because it would be next to impossible to check for wrong spelling of the default parameters.

All values must be a single character string, except extra (named character vector). Logical values are also possible for LazyLoad and all entries of extra. They will be translated into "yes" or "no".

Value

A data.frame.

Examples

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=\"[email protected]\",
       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 <[email protected]>",
  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"
)
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.a.doelle@example.com\",
       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 <[email protected]>",
  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"
)

Generate package file skeletons

Description

Writes a new file with some basic comments and documentation hints, according to the type of R object to cover.

Usage

package_file_skeleton(
  name,
  type = c("function", "S4Class", "S4Method", "data")
)
package_file_skeleton(
  name,
  type = c("function", "S4Class", "S4Method", "data")
)

Arguments

`name`	Character string, name of the object the file should cover (i.e., a function or class name).
`type`	One of `"function"`, `"S4Class"`, `"S4Method"`, or `"data"`, categorizing the object to be documented.

Read/write ChangeLog files

Description

These functions ans methods can be used to manage ChangeLog files.

Usage

readChangeLog(
  file,
  head = "ChangeLog for package",
  change = "changes in version",
  item = "  -"
)

writeChangeLog(
  log,
  file = NULL,
  head = "ChangeLog for package",
  change = "changes in version",
  item = "  -",
  lineEnd = 78
)

initChangeLog(
  entry = list(changed = c("initial release"), fixed = c("missing ChangeLog")),
  package = "unknown",
  version = "0.01-1",
  date = Sys.Date()
)
readChangeLog(
  file,
  head = "ChangeLog for package",
  change = "changes in version",
  item = "  -"
)

writeChangeLog(
  log,
  file = NULL,
  head = "ChangeLog for package",
  change = "changes in version",
  item = "  -",
  lineEnd = 78
)

initChangeLog(
  entry = list(changed = c("initial release"), fixed = c("missing ChangeLog")),
  package = "unknown",
  version = "0.01-1",
  date = Sys.Date()
)

Arguments

`file`	Character string, path to the ChangeLog file to read.
`head`	Character string, the headline text of the ChangeLog file (without the package name).
`change`	Character string, the text introducing each ChnageLog entry for a package version.
`item`	Character string, the text marking each entry item.
`log`	An object of class `ChangeLog`.
`lineEnd`	Integer number, indicates where to do line breaks.
`entry`	A (named) list of character vectors. The element names will become the ChangeLog sections, each vector element an item.
`package`	Character string, the package name.
`version`	Character string, version number to look up.
`date`	The date of the ChangeLog entry in `YYYY-MM-DD` format. will be coerced into character. To keep the date stamp of a present entry, set `date=NULL`.

Details

The ChangeLog files used for R packages are usually required to have a standard format, if they are supposed to be parsed by functions like tools::news2Rd:

entries are named "Changes in version <version number>" (and optionally a YYYY-MM-DD date string afterwards). The date string is mandatory if you want to use the ChageLog functions in roxyPackage. The version number can be given in both <major>.<minor>-<revision> or <major>.<minor>.<revision> format.
they have single changes properly itemized, by indentation and then either "o", "-" or "*" followed by space
optionally have categories as subsections, like "Fixed", "Changed" or "Added"

readChangeLog tries to read a given ChangeLog file and parse its content to generate a special ChangeLog object.

writeChangeLog takes such a ChangeLog object to write it back to a file. If file=NULL, the log will be returned to stdout.

initChangeLog generates a ChangeLog object from scratch, e.g., to get started with a new package.

Value

An object of class ChangeLog.

Examples

## Not run: 
changelog <- readChangeLog("/home/user/myRsources/myRpackage/ChangeLog")

## End(Not run)
## Not run: 
changelog <- readChangeLog("/home/user/myRsources/myRpackage/ChangeLog")

## End(Not run)

Convert vognettes from .Rnw to .Rmd

Description

This is a much enhanced R port of Perl code gists from GitHub [1, 2]. It tries its best to convert old Sweave vignettes into R markdown. Please do not expect it to do wonders, but to give you a good starting point for conversions.

Usage

rnw2rmd(
  file,
  output = "rmarkdown::html_vignette",
  output_options = c(toc = "true"),
  engine = "knitr::rmarkdown",
  csl = NULL,
  eval = FALSE,
  replace = NULL,
  flattr_id = NULL,
  write_file = FALSE,
  overwrite = FALSE
)
rnw2rmd(
  file,
  output = "rmarkdown::html_vignette",
  output_options = c(toc = "true"),
  engine = "knitr::rmarkdown",
  csl = NULL,
  eval = FALSE,
  replace = NULL,
  flattr_id = NULL,
  write_file = FALSE,
  overwrite = FALSE
)

Arguments

`file`	Path to an *.Rnw file to convert.
`output`	Character string defining the R markdown output format.
`output_options`	A named character vector with additional options. If you need more than the default indentaion, you have to provide it directly (see default values for `toc_float`).
`engine`	Character string defining the `VignetteEngine` value.
`csl`	Character string defining a CSL style file for the bibliography. Please note that you will have to provide an existing file of that name in an appropriate location, like the *.Rmd file's directory. Ignored if `NULL`, or if no bibliography was detected.
`eval`	Logical, a default value for all R code chunks that are found. This is like a safety net to be able to disable all code by default. Setting the default value will be omitted if set to `NULL`.
`replace`	An optional list of named character vectors with regular expressions to do custom replacements in the text body. The list must contain vectors with two character elements named `from` and `to`, to define what expressions should be replaced and with what.
`flattr_id`	Character string, the ID value of your Flattr meta tag. If set will be added to the header of the resulting HTML file of the vignette.
`write_file`	Logical, if set to `TRUE` results will be written to a file in the same directory as the input `file`, but with *.Rmd file ending. Default is `FALSE`, meaning results are returned as a character string.
`overwrite`	Logical, whether existing files should be overwritten if `write_file=TRUE`.

References

[1] https://gist.github.com/mikelove/5618f935ace6e389d3fbac03224860cd

[2] https://gist.github.com/lgatto/d9d0e3afcc0a4417e5084e5ca46a4d9e

Examples

## Not run: 
rnw2rmd(file.path(find.package("roxyPackage"),"doc","roxyPackage_vignette.Rnw"))

# use a fancy theme (not so good for CRAN, bloats the HTML file)
rnw2rmd(
  file.path(find.package("roxyPackage"),"doc","roxyPackage_vignette.Rnw"),
  output="html_document",
  output_options=c(
    theme="cerulean",
    highlight="kate",
    toc="true",
    toc_float="\n      collapsed: false\n      smooth_scroll: false",
    toc_depth=3
  )
)

## End(Not run)
## Not run: 
rnw2rmd(file.path(find.package("roxyPackage"),"doc","roxyPackage_vignette.Rnw"))

# use a fancy theme (not so good for CRAN, bloats the HTML file)
rnw2rmd(
  file.path(find.package("roxyPackage"),"doc","roxyPackage_vignette.Rnw"),
  output="html_document",
  output_options=c(
    theme="cerulean",
    highlight="kate",
    toc="true",
    toc_float="\n      collapsed: false\n      smooth_scroll: false",
    toc_depth=3
  )
)

## End(Not run)

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,
  ...
)
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

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=\"[email protected]\",
       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 <[email protected]>",
  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)
## 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.a.doelle@example.com\",
       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 <[email protected]>",
  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)

Run actions in a sandbox

Description

If you want to test the effects of roxy.package, archive.packages or debianize, you can activate a sandbox with this function.

Usage

sandbox(
  active = FALSE,
  sandbox.dir = file.path(tempdir(), "roxyPackge", "sandbox"),
  pck.source.dir = TRUE,
  R.libs = TRUE,
  repo.root = TRUE,
  archive = repo.root,
  clean = FALSE
)
sandbox(
  active = FALSE,
  sandbox.dir = file.path(tempdir(), "roxyPackge", "sandbox"),
  pck.source.dir = TRUE,
  R.libs = TRUE,
  repo.root = TRUE,
  archive = repo.root,
  clean = FALSE
)

Arguments

`active`	Logical, whether sandboxing should be active or not
`sandbox.dir`	Character string, full path to the sandbox root directory to use. Will be created if necessary (at first use, not when setting this here!).
`pck.source.dir`	Logical, whether to sandbox the package sources. If `TRUE` the full package sources will be copied to `file.path(sandbox.dir, "src")` (at first use, not when setting this here!).
`R.libs`	Logical, whether to sandbox the R library directory, that is, the directory to install the package to. Since this needs also to provide all package dependencies, those packages will be copied to `file.path(sandbox.dir, "R")` (at first use, not when setting this here!).
`repo.root`	Logical, whether to sandbox the repository. This repository will be set up in `file.path(sandbox.dir, "repo")` (at first use, not when setting this here!).
`archive`	Logical, whether to sandbox the repository archive. The archive will be set up in `file.path(sandbox.dir, "repo_archive")` (at first use, not when setting this here!).
`clean`	Logical, whether to always clean the defined `sandbox.dir` completely before any other action is taken. Be aware that this will wipe everything that resides in the current sandbox! Ignored if `active=FALSE`.

Details

Sandboxing means that you are able to specify which groups of actions should only be run in a separate environment. This can be useful if you don't want to make changes to your actual package code, but inspect the result first.

With this function, you can turn sandboxing on and off. This setting has effects only in the currently running R session. By default, sandboxing is off.

Value

Settings are stored in an internal environment, so there is no actual return value.

Note

When using sandboxing for your source code, be aware that changes to the original code will not be updated in the sandbox automatically. For example, if you run roxy.package to check your package, fix an issue in the original source location and run roxy.package again, your changes will not have affected the code in the sandbox directory. For those cases, it might be advisable to use the clean=TRUE option.

Examples

## Not run: 
# turn sandboxing on
sandbox(active=TRUE)

## End(Not run)
## Not run: 
# turn sandboxing on
sandbox(active=TRUE)

## End(Not run)

Show sandboxing status

Description

This function prints the current sandbox settings. It has no parameters.

Usage

sandbox.status()
sandbox.status()

Value

The function invisibly returns the sandbox root directory path (sandbox.dir). If sandboxing is inactive, this is an empty character string ("").

Examples

## Not run: 
sandbox.status()

## End(Not run)
## Not run: 
sandbox.status()

## End(Not run)

Create template file for new function/class/method

Description

This function can be used to generate template files for new functions, S4 classes or methods.

Usage

templateFile(
  name,
  path = getwd(),
  pck.description = data.frame(Package = "", Author = "", License = "GPL (>= 3)",
    stringsAsFactors = FALSE),
  year = format(Sys.time(), "%Y"),
  params = list(obj = "someClass", ... = "\\code{\\link[somepackage]{somefunction}}"),
  seealso = list(aPackage = "aFunction"),
  return = list(aPackage = "aFunction"),
  type = "function",
  write = FALSE,
  overwrite = FALSE
)
templateFile(
  name,
  path = getwd(),
  pck.description = data.frame(Package = "", Author = "", License = "GPL (>= 3)",
    stringsAsFactors = FALSE),
  year = format(Sys.time(), "%Y"),
  params = list(obj = "someClass", ... = "\\code{\\link[somepackage]{somefunction}}"),
  seealso = list(aPackage = "aFunction"),
  return = list(aPackage = "aFunction"),
  type = "function",
  write = FALSE,
  overwrite = FALSE
)

Arguments

`name`	Character string, name of the function/method/class.
`path`	Full path to the directory where the file should be added if `write=TRUE`.
`pck.description`	Data frame holding the package description. Only the fields "Package", "Author" and "License" are needed/used (see Examples section).
`year`	Character string, the year to use in the copyright information.
`params`	A named list of parameters, where the element name is the parameter name and its value is the type of object expected as input. Some objects types are recognized, like "c", "character", "numeric", "logical", "matrix" or "data.frame". If an element is called `"..."`, the value is assumend to point to a function or method where additional arguments are passed to. If `type="S4class"`, this argument is used to define the slots.
`seealso`	A named list, where element names define packages and values objects of that package to link.
`return`	A named list, similar to `seealso`, but generating references for returned objects.
`type`	Character string, either `"function"`, `"S4class"`, or `"S4method"`, depending on the template you want to create.
`write`	Logical, if `TRUE` output will be written to a file in `path`, otherwise returned as a character string.
`overwrite`	Logical, if `TRUE` and the output file already exists, it will be replaced with the generated template. Otherwise you'll just get an error.

Details

Set the parameters to your needs, perhaps setwd into the target directory, and set write=TRUE if you like what you see so far. The result should include a copyright note, insitial roxygen-style documentation and some useful first lines of code, guessed from the provided arguments.

Value

If write=TRUE, writes a file in the path directory. If write=FALSE, returns a character string.

Examples

pckg.dscrptn <- data.frame(
  Package="SquareTheCircle",
  Author="E.A. Dölle <[email protected]>",
  License="GPL (>= 3)",
  stringsAsFactors=FALSE
)
cat(
  templateFile(
    name="exampleFunction",
    pck.description=pckg.dscrptn
  )
)
pckg.dscrptn <- data.frame(
  Package="SquareTheCircle",
  Author="E.A. Dölle <[email protected]>",
  License="GPL (>= 3)",
  stringsAsFactors=FALSE
)
cat(
  templateFile(
    name="exampleFunction",
    pck.description=pckg.dscrptn
  )
)

Update ChangeLog objects

Description

This method can be used to update ChangeLog objects.

Usage

updateChangeLog(log, entry, version, date = Sys.Date(), append = TRUE)

## S4 method for signature 'ChangeLog'
updateChangeLog(log, entry, version, date = Sys.Date(),
      append = TRUE)
updateChangeLog(log, entry, version, date = Sys.Date(), append = TRUE)

## S4 method for signature 'ChangeLog'
updateChangeLog(log, entry, version, date = Sys.Date(),
      append = TRUE)

Arguments

`log`	An object of class `ChangeLog`.
`entry`	A (named) list of character vectors. The element names will become the ChangeLog sections, each vector element an item.
`version`	Character string, version number to look up.
`date`	The date of the ChangeLog entry in `YYYY-MM-DD` format. will be coerced into character. To keep the date stamp of a present entry, set `date=NULL`.
`append`	Logical, whether a present entry should be replaced or added to.

Details

updateChangeLog takes a ChangeLog object and a version number string, replaces the complete entry with the contents of entry and updates the time stamp to date.

Value

An object of class ChangeLog.

Package 'roxyPackage'

Help Index

Utilities to Automate Package Builds

Description

Details

Author(s)

See Also

Deal with old packages in your local repository

Description

Usage

Arguments

Note

See Also

Examples

Convert ChangeLog/NEWS into NEWS.Rd

Description

Usage

Arguments

Details

Value

See Also

Examples

Basic Debian package creation from R source packages

Description

Usage

Arguments

Details

Building the actual package

Package dependencies

Repository access

Debianizing arbitrary packages

Note

References

See Also

Examples

Package your OpenPGP keyring in Debian package format

Description

Usage

Arguments

See Also

Examples

Download package dependencies

Description

Usage

Arguments

Details

Value

Examples

Translate character string into HTML entities

Description

Usage

Arguments

Value

Examples

Read/write ChangeLog objects

Description

Usage

Arguments

Details

Value

See Also

Examples

Generate RSS feeds from R NEWS files

Description

Usage

Arguments

Value

Examples

Download ORCID icon

Description

Usage

Arguments

Note

Examples

Generate a valid package description

Description

Usage

Arguments

Details

Value

Convert vognettes from .Rnw to .Rmd