README.md

In kevinushey/configure: Configure R Packages for Installation

configure

Configure R packages for installation with R.

Motivation

Writing portable package configure scripts is painful. It's even more painful because you often need to do it twice: once for Unix, and once for Windows (with configure.win). And the same tools you might use to generate a configure script (say, autoconf) might not be available when you want to write configure.win. This package seeks to solve that problem by:

• Allowing you to configure your R package directly with R; and
• Providing a set of functions for accomplishing common configuration tasks.

Usage

First, prepare your package by invoking:

configure::use_configure()

This will write out a few files to your package's directory.

• configure
• configure.win
• cleanup
• cleanup.win
• tools/config.R

The configure{.win} and cleanup{.win} scripts invoke the tools/config.R script. This script performs some automatic package configuration (described later), and also sources a user-defined configure script at tools/config/configure.R, or a cleanup script at tools/config/cleanup.R.

It is not necessary for your package to import or explicitly depend on the configure package. The use_configure() function will copy all required files directly to tools/config.R, so in essence your package will embed all of the functionality provided by configure.

Understanding configure and cleanup

Here's a rough timeline of what happens when R attempts to install your package from a source tarball. When R CMD INSTALL is invoked (either directly by the user, or perhaps from a helper function like install.packages() or one of the devtools::install_*() functions), the following occurs:

• If the --preclean option was supplied, the cleanup{.win} script will be run. This is off by default.

• Next, unless --no-configure was passed, the configure{.win} script is run, to prepare the package for installation.

• Finally, if installation was invoked with --clean, the cleanup{.win} script will be run.

Note that the default behavior is not to run cleanup{.win} during install (one must explicitly request it from R); however, CRAN compliance checks will still ensure that you do clean up artefacts generated by configure{.win}. In other words, if you write a configure{.win} script, you almost certainly need a cleanup{.win} script as well -- hence why this package generates both.

Configure

The main goal during the configure stage is to generate, or modify, files for compilation or installation on the current platform. The primary mechanism through which this is accomplished is through translating .in files, with the configure_file() helper function.

configure_file("src/Makevars.in")

This will substitute variables of the form @VAR@ with the associated definition discovered in the configuration database. By default, the configuration database is empty, but you can populate it using the configure_define() function. For example, you might use the following to define the value for a variable called STDVER:

define(STDVER = "c++11")

If you want to read R's configuration -- for example, to discover what C compiler should be used for compilation -- you can use the read_r_config() function:

read_r_config("CC", "CXX")

The configuration database will automatically be populated with the values requested by R for CC and CXX in this case.

Cleanup

The cleanup stage's primary purpose is to remove files created during the configure stage. For example, we might want to remove the generated Makevars files generated earlier:

unlink("src/Makevars")

Automatic Configuration

The configure package tries to perform some of the most common configuration and cleanup steps automatically, to avoid overburdening the user when possible. In particular, all .in files discovered within the package top-level directory, R/, and src/ folders are automatically configured and cleaned up as required. This implies that, in many cases, it should be sufficient for a user to write a configure.R script whose only purpose is to define configuration variables.

As an example, the configure package uses itself to manage configuration. The file R/zzz.R.in contains the single line:

.PACKAGE <- "@PACKAGE_NAME@"

And the file at tools/config/configure.R contains only:

define(PACKAGE_NAME = "configure")

and the existing machinery automatically generates and cleans up zzz.R as appropriate.

Licensing

These components are licensed to you under the MIT license, which should be compatible with all other major open-source licenses. However, if you prefer, you are free to instead re-license these components using the same open-source license you're releasing your R package under, as long as that license is a CRAN-compatible license.

kevinushey/configure documentation built on March 26, 2021, 12:21 p.m.