debianize: Basic Debian package creation from R source packages

In unDocUMeantIt/roxyPackage: Utilities to Automate Package Builds

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
)

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

See Also

sandbox to run debianize() in a sandbox.

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 <[e-mail]>"),
  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 <[e-mail]>"
  )
)

## End(Not run)

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