Building converts a package source directory into a single bundled file.
If binary = FALSE
this creates a tar.gz
package that can
be installed on any platform, provided they have a full development
environment (although packages without source code can typically be
installed out of the box). If binary = TRUE
, the package will have
a platform specific extension (e.g. .zip
for windows), and will
only be installable on the current platform, but no development
environment is needed.
build(
path = ".",
dest_path = NULL,
binary = FALSE,
vignettes = TRUE,
manual = FALSE,
clean_doc = NULL,
args = NULL,
quiet = FALSE,
needs_compilation = pkg_has_src(path),
compile_attributes = FALSE,
register_routines = FALSE
)
a string giving the location (including file name) of the built package
Path to a package, or within a package.
path in which to produce package. If it is an existing
directory, then the output file is placed in dest_path
and named
according to the current R conversions (e.g. .zip
for Windows binary
packages, .tgz
for macOS binary packages, etc).
If it is an existing file, then it will be overwritten.
If dest_path
does not exist, then it is used as a file name.
If NULL
, it defaults to the parent directory of the package.
Produce a binary (--binary
) or source (
--no-manual --no-resave-data
) version of the package.
For source packages: if FALSE
, don't build PDF
vignettes (--no-build-vignettes
) or manual (--no-manual
).
If TRUE
, clean the files in inst/doc
before building
the package. If NULL
and the Config/build/clean-inst-doc
entry is
present in DESCRIPTION
, then that is used. Otherwise, if NULL
,
and interactive, ask to remove the files prior to cleaning. In most
cases cleaning the files is the correct behavior to avoid stale
vignette outputs in the built package.
An optional character vector of additional command
line arguments to be passed to R CMD build
if binary = FALSE
,
or R CMD install
if binary = TRUE
.
if TRUE
suppresses output from this function.
Usually only needed if the packages has C/C++/Fortran code. By default this is autodetected.
if TRUE
and the package uses Rcpp, call
Rcpp::compileAttributes()
before building the package. It is ignored
if package does not need compilation.
if TRUE
and the package does not use Rcpp, call
register routines with
tools::package_native_routine_registration_skeleton()
before building
the package. It is ignored if package does not need compilation.
DESCRIPTION
entriesConfig/build/clean-inst-doc
can be set to FALSE
to avoid cleaning up
inst/doc
when building a source package. Set it to TRUE
to force a
cleanup. See the clean_doc
argument.
Config/build/copy-method
can be used to avoid copying large
directories in R CMD build
. It works by copying (or linking) the
files of the package to a temporary directory, leaving out the
(possibly large) files that are not part of the package. Possible
values:
none
: pkgbuild does not copy the package tree. This is the default.
copy
: the package files are copied to a temporary directory before
R CMD build
.
link
: the package files are symbolic linked to a temporary
directory before R CMD build
. Windows does not have symbolic
links, so on Windows this is equivalent to copy
.
You can also use the pkg.build_copy_method
option or the
PKG_BUILD_COPY_METHOD
environment variable to set the copy method.
The option is consulted first, then the DESCRIPTION
entry, then the
environment variable.
Config/build/extra-sources
can be used to define extra source files
for pkgbuild to decide whether a package DLL needs to be recompiled in
needs_compile()
. The syntax is a comma separated list of file names,
or globs. (See utils::glob2rx()
.) E.g. src/rust/src/*.rs
or
configure*
.
Config/build/bootstrap
can be set to TRUE
to run
Rscript bootstrap.R
in the source directory prior to running subsequent
build steps.
pkg.build_copy_method
: use this option to avoid copying large
directories when building a package. See possible values above, at the
Config/build/copy-method
DESCRIPTION
entry.
pkg.build_stop_for_warnings
: if it is set to TRUE
, then pkgbuild
will stop for R CMD build
errors. It takes precedence over the
PKG_BUILD_STOP_FOR_WARNINGS
environment variable.
PKG_BUILD_COLOR_DIAGNOSTICS
: set it to false
to opt out of colored
compiler diagnostics. Set it to true
to force colored compiler
diagnostics.
PKG_BUILD_COPY_METHOD
: use this environment variable to avoid copying
large directories when building a package. See possible values above,
at the Config/build/copy-method
DESCRIPTION
entry.
will stop for R CMD build
errors. The pkg.build_stop_for_warnings
option takes precedence over this environment variable.