debianize: Basic Debian package creation from R source packages

In saurfang/roxyPackage: Utilities to automate package builds

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,
  origin = "other-roxypackage", 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"),
  bin.opts = "-rfakeroot -b -uc", arch = "all", compat = 7,
  epoch = NULL, gpg.key = NULL, keep.build = FALSE,
  replace.dots = FALSE)

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.
revision	Numeric or a character string, the Debian package revision information.
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 (>> 7.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 Suggests Suggests in DESCRIPTION in debianized format Maintainer generated from Sys.info (user <login@nodename>), with a warning. Section "math" 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 or Depends rather than replacing them, provide a named character vector with a value called "append". For example: Depends=c(append="libmysql++3").
actions	Character vector, naming the actions to perform: "deb" Debianize the package sources. "bin" Build the Debian package. "src" Build a Debian source package (currently not implemented).
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 "control" Re-write ./debian/control "copyright" Re-write ./debian/copyright "rules" Re-write ./debian/rules "gpg.key" Re-write <key ID.asc> in the repository (by default present keys are left unchanged)
depends.origin	A character string to set the default origin for 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 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").
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. Skipped if NULL.
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.
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.

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>.asc.

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 (>> 2.12.0), r-cran-foreign"),
    maintainer="A. Sistent <[e-mail]>"),
  actions=c("deb"))

## End(Not run)

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