pracpac (version 0.2.0)

use_docker: Use docker packaging tools

Description

Wrapper function around other pracpac functions. See help for the functions linked below for detail on individual functions. All arguments to use_docker() are passed to downstream functions. use_docker() will sequentially run:

1. pkg_info to get information about the current R package.

2. create_docker_dir to create the docker/ directory in the specified location, if it doesn't already exist.

3. renv_deps (if use_renv=TRUE, the default) to capture package dependencies with renv and create an renv.lock file

4. add_dockerfile to create a Dockerfile using template specified by use_case

5. add_assets depending on the use_case

6. build_pkg to build the current R package source .tar.gz, and place it into the docker/ directory

7. build_image optional, default FALSE; if TRUE, will build the Docker image.

The default build=FALSE means that everything up to build_image() is run, but the image is not actually built. Instead, use_docker() will message the docker build command, and return that string in $buildcmd in the invisibly returned output.

See vignette("use-cases", package="pracpac") for details on use cases.

Usage

use_docker(
  pkg_path = ".",
  img_path = NULL,
  use_renv = TRUE,
  use_case = "default",
  base_image = NULL,
  other_packages = NULL,
  build = FALSE,
  repos = NULL,
  overwrite_assets = TRUE,
  overwrite_renv = TRUE,
  consent_renv = TRUE
)

Value

Invisibly returns a list with information about the package ($info) and the docker build command ($buildcmd). Primarily called for side effect. Creates docker/ directory, identifies renv dependencies and creates lock file (if use_renv = TRUE), writes Dockerfile, builds package tar.gz, moves all relevant assets to the docker/ directory, and builds Docker image (if build = TRUE).

Arguments

pkg_path

Path to the package directory. Default is "." for the current working directory, which assumes developer is working in R package root. However, this can be set to another path as needed.

img_path

Path to the write the docker image definition contents. The default NULL will use docker/ as a subdirectory of the pkg_path.

use_renv

Logical; use renv? Defaults to TRUE. If FALSE, package dependencies are scraped from the DESCRIPTION file without version information.

use_case

Name of the use case. Defaults to "default", which only uses the base boilerplate.

base_image

Name of the base image to start FROM. Default is NULL and the base image will be derived based on use_case. Optionally override this by setting the name of the base image (including tag if desired).

other_packages

Vector of other packages to be included in renv lock file; default is NULL.

build

Logical as to whether or not the image should be built. Default is TRUE, and if FALSE the docker build command will be messaged. Setting build=FALSE could be useful if additional docker build options or different tags are desired. In either case the docker build command will be returned invisibly.

repos

Option to override the repos used for installing packages with renv by passing name of repository. Only used if use_renv = TRUE. Default is NULL meaning that the repos specified in renv lockfile will remain as-is and not be overridden.

overwrite_assets

Logical; should existing asset files should be overwritten? Default is TRUE.

overwrite_renv

Logical; should an existing lock file should be overwritten? Default is TRUE; ignored if use_renv = TRUE.

consent_renv

Logical; give renv consent in this session with options(renv.consent = TRUE)? Default is TRUE. See renv::consent for details.

Examples

if (FALSE) {

# Specify path to example package source and copy to tempdir()
# Note that in practice you do not need to copy to a tempdir()
# And in fact it may be easiest to use pracpac relative to your package directory root
ex_pkg_src <- system.file("hellow", package = "pracpac", mustWork = TRUE)
file.copy(from = ex_pkg_src, to = tempdir(), recursive = TRUE)

# Run use_docker to create Docker directory and assets for the example package
use_docker(pkg_path = file.path(tempdir(), "hellow"))
# To not use renv
use_docker(pkg_path = file.path(tempdir(), "hellow"), use_renv=FALSE)
# To specify a use case
use_docker(pkg_path = file.path(tempdir(), "hellow"), use_case="pipeline")
# To overwrite the default base image
use_docker(pkg_path = file.path(tempdir(), "hellow"), base_image="alpine:latest")
}