% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dock_from_desc.R
\name{dock_from_desc}
\alias{dock_from_desc}
\title{Create a Dockerfile from a DESCRIPTION}
\usage{
dock_from_desc(
  path = "DESCRIPTION",
  FROM = paste0("rocker/r-ver:", R.Version()$major, ".", R.Version()$minor),
  AS = NULL,
  sysreqs = TRUE,
  repos = c(CRAN = "https://p3m.dev/cran/latest"),
  expand = FALSE,
  update_tar_gz = TRUE,
  build_from_source = TRUE,
  extra_sysreqs = NULL,
  github_pat = c("none", "build_arg", "secret"),
  strict_install = TRUE
)
}
\arguments{
\item{path}{path to the DESCRIPTION file to use as an input.}

\item{FROM}{The FROM of the Dockerfile. Default is
\code{paste0("rocker/r-ver:", R.Version()$major, ".", R.Version()$minor)}.
Validated as a Docker image reference (alphanumerics, dot, slash,
dash, underscore, optional \verb{:tag} and / or \verb{@sha256:<hex>}); other
values raise an error to prevent shell-metacharacter injection
into the generated FROM directive.}

\item{AS}{The build-stage name of the Dockerfile (\verb{FROM ... AS <name>}).
Default is \code{NULL} (no \code{AS}). When non-\code{NULL}, validated as a simple
build-stage name (\verb{^[a-zA-Z0-9][a-zA-Z0-9._-]*$}).}

\item{sysreqs}{boolean. If TRUE, the Dockerfile will contain sysreq installation.}

\item{repos}{character. The URL(s) of the repositories to use for
\code{options("repos")}. Default is \code{c(CRAN = "https://p3m.dev/cran/latest")}
(Posit Public Package Manager). When \code{repos} is a single \code{CRAN}-keyed
PPM URL (\code{packagemanager.posit.co}, \code{packagemanager.rstudio.com}, or
\code{p3m.dev}), the codegen rewrites it to the
\verb{__linux__/$VERSION_CODENAME/} shape (codename resolved from
\verb{/etc/os-release} at image build time) and adds the strict
\code{HTTPUserAgent} PPM requires, so the build pulls pre-compiled Linux
binaries instead of compiling from source. Pass the legacy
\code{c(CRAN = "https://cran.rstudio.com/")} to opt out. Each value must
look like an http(s) URL (no quotes, spaces or newlines); each name
(when set) must be a simple identifier (\verb{^[A-Za-z][A-Za-z0-9._-]*$}).
Other values raise an error to prevent injection into the generated
\verb{echo "options(...)"} shell command.}

\item{expand}{boolean. If \code{TRUE} each system requirement will have its own \code{RUN} line.}

\item{update_tar_gz}{boolean. If \code{TRUE} and \code{build_from_source} is also \code{TRUE},
an updated tar.gz is created.}

\item{build_from_source}{boolean. If \code{TRUE} no tar.gz is created and
the Dockerfile directly mount the source folder.}

\item{extra_sysreqs}{character vector. Extra debian system requirements.
Will be installed with apt-get install. Each entry must be a Debian
package name (\verb{^[a-z0-9][a-z0-9.+-]+$}); other values raise an error
to prevent injection into the generated apt-get RUN.}

\item{github_pat}{character. How to provide a GitHub PAT to
\code{remotes::install_github()} for private dependency repositories.
One of \code{"none"} (default; the generated Dockerfile does not
reference any PAT), \code{"build_arg"} (emit \verb{ARG GITHUB_PAT} + \code{ENV}
propagation; pass with \verb{--build-arg GITHUB_PAT=$GITHUB_PAT}; the
PAT will be visible in the image metadata), or \code{"secret"}
(BuildKit secret mount on each \code{install_github()} / \code{install_local()}
RUN; the PAT is never persisted in the image; requires BuildKit, so
pass with
\verb{DOCKER_BUILDKIT=1 docker build --secret id=github_pat,env=GITHUB_PAT ...}).}

\item{strict_install}{boolean. When \code{TRUE} (the default), every
install RUN in the generated Dockerfile is prefixed with
\code{options(warn = 2);} so that any R warning during install
(missing CRAN package, partial download, archived package,
404 on a remote) becomes a hard error and aborts the docker
build. Set to \code{FALSE} if your build environment routinely emits
benign warnings (locale defaulting, NTP time-verification,
ABI-version notices) that you do not want to fail the build.
Must be a single scalar logical; \code{NA}, character, numeric,
\code{NULL} and length-2+ vectors are rejected with an error.}
}
\value{
Dockerfile
}
\description{
Create a Dockerfile from a DESCRIPTION
}
\details{
Two install strategies are available for the package itself:
\itemize{
\item \code{build_from_source = TRUE} (the default): the generated Dockerfile
mounts the source folder and installs from it directly. \code{update_tar_gz}
is ignored.
\item \code{build_from_source = FALSE}: a source tarball (\verb{<pkg>_<version>.tar.gz})
is \code{COPY}'d into the image and installed with
\code{remotes::install_local()}. When \code{update_tar_gz = TRUE}, a fresh
tarball is built with \code{pkgbuild::build()} first (and any stale
\verb{<pkg>_*.tar.gz} in the current directory is removed); when
\code{update_tar_gz = FALSE}, an already-built tarball is expected
alongside the \code{DESCRIPTION}.
}

The package name and its dependency-field names are read from the
\code{DESCRIPTION} and validated against the CRAN package-name grammar
before being interpolated into the generated directives.
}
\examples{
\dontrun{
# From the DESCRIPTION of the package in the working directory:
dock <- dock_from_desc("DESCRIPTION")
dock

# Pull source packages from the classic CRAN mirror instead of PPM:
dock_from_desc(
  "DESCRIPTION",
  repos = c(CRAN = "https://cran.rstudio.com/")
)
}
}
