1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pkgbuild.R
\name{build}
\alias{build}
\title{Build package}
\usage{
build(
pkg = ".",
path = NULL,
binary = FALSE,
vignettes = TRUE,
manual = FALSE,
args = NULL,
quiet = FALSE,
...
)
}
\arguments{
\item{pkg}{The package to use, can be a file path to the package or a
package object. See \code{\link[=as.package]{as.package()}} for more information.}
\item{path}{Path in which to produce package. If \code{NULL}, defaults to
the parent directory of the package.}
\item{binary}{Produce a binary (\code{--binary}) or source (
\code{--no-manual --no-resave-data}) version of the package.}
\item{vignettes, manual}{For source packages: if \code{FALSE}, don't build PDF
vignettes (\code{--no-build-vignettes}) or manual (\code{--no-manual}).}
\item{args}{An optional character vector of additional command
line arguments to be passed to \verb{R CMD build} if \code{binary = FALSE},
or \verb{R CMD install} if \code{binary = TRUE}.}
\item{quiet}{if \code{TRUE} suppresses output from this function.}
\item{...}{Additional arguments passed to \link[pkgbuild:build]{pkgbuild::build}.}
}
\value{
a string giving the location (including file name) of the built
package
}
\description{
Building converts a package source directory into a single bundled file.
If \code{binary = FALSE} this creates a \code{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 \code{binary = TRUE}, the package will have
a platform specific extension (e.g. \code{.zip} for windows), and will
only be installable on the current platform, but no development
environment is needed.
}
\details{
\subsection{Configuration}{
\subsection{\code{DESCRIPTION} entries}{
\itemize{
\item \code{Config/build/clean-inst-doc} can be set to \code{FALSE} to avoid cleaning up
\code{inst/doc} when building a source package. Set it to \code{TRUE} to force a
cleanup. See the \code{clean_doc} argument.
\item \code{Config/build/copy-method} can be used to avoid copying large
directories in \verb{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:
\itemize{
\item \code{none}: pkgbuild does not copy the package tree. This is the default.
\item \code{copy}: the package files are copied to a temporary directory before
\verb{ R CMD build}.
\item \code{link}: the package files are symbolic linked to a temporary
directory before \verb{R CMD build}. Windows does not have symbolic
links, so on Windows this is equivalent to \code{copy}.
}
You can also use the \code{pkg.build_copy_method} option or the
\code{PKG_BUILD_COPY_METHOD} environment variable to set the copy method.
The option is consulted first, then the \code{DESCRIPTION} entry, then the
environment variable.
\item \code{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
\code{needs_compile()}. The syntax is a comma separated list of file names,
or globs. (See \code{\link[utils:glob2rx]{utils::glob2rx()}}.) E.g. \verb{src/rust/src/*.rs} or
\verb{configure*}.
\item \code{Config/build/bootstrap} can be set to \code{TRUE} to run
\verb{Rscript bootstrap.R} in the source directory prior to running subsequent
build steps.
\item \code{Config/build/never-clean} can be set to \code{TRUE} to never add \code{--preclean}
to \verb{R CMD INSTALL}, e.g., when header files have changed.
This helps avoiding rebuilds that can take long for very large C/C++ codebases
and can lead to build failures if object files are out of sync with header files.
Control the dependencies between object files and header files
by adding \verb{include file.d} to \code{Makevars} for each \code{file.c} or \code{file.cpp} source file.
}
}
\subsection{Options}{
\itemize{
\item \code{pkg.build_copy_method}: use this option to avoid copying large
directories when building a package. See possible values above, at the
\code{Config/build/copy-method} \code{DESCRIPTION} entry.
\item \code{pkg.build_stop_for_warnings}: if it is set to \code{TRUE}, then pkgbuild
will stop for \verb{R CMD build} errors. It takes precedence over the
\code{PKG_BUILD_STOP_FOR_WARNINGS} environment variable.
}
}
\subsection{Environment variables}{
\itemize{
\item \code{PKG_BUILD_COLOR_DIAGNOSTICS}: set it to \code{false} to opt out of colored
compiler diagnostics. Set it to \code{true} to force colored compiler
diagnostics.
\item \code{PKG_BUILD_COPY_METHOD}: use this environment variable to avoid copying
large directories when building a package. See possible values above,
at the \code{Config/build/copy-method} \code{DESCRIPTION} entry.
}
will stop for \verb{R CMD build} errors. The \code{pkg.build_stop_for_warnings}
option takes precedence over this environment variable.
}
}
}
\note{
The default \code{manual = FALSE} is not suitable for a CRAN
submission, which may require \code{manual = TRUE}. Even better, use
\code{\link[=submit_cran]{submit_cran()}} or \code{\link[=release]{release()}}.
}
|
