load_all: Load complete package

Description Usage Arguments Details Namespaces Shim files Examples

View source: R/load.r

Description

load_all loads a package. It roughly simulates what happens when a package is installed and loaded with library().

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
load_all(
  path = ".",
  reset = TRUE,
  compile = NA,
  export_all = TRUE,
  export_imports = export_all,
  helpers = TRUE,
  attach_testthat = uses_testthat(path),
  quiet = FALSE,
  recompile = FALSE,
  warn_conflicts = TRUE
)

Arguments

path

Path to a package, or within a package.

reset

clear package environment and reset file cache before loading any pieces of the package. This largely equivalent to running unload(), however the old namespaces are not completely removed and no .onUnload() hooks are called. Use reset = FALSE may be faster for large code bases, but is a significantly less accurate approximation.

compile

If TRUE always recompiles the package; if NA recompiles if needed (as determined by pkgbuild::needs_compile()); if FALSE, never recompiles.

export_all

If TRUE (the default), export all objects. If FALSE, export only the objects that are listed as exports in the NAMESPACE file.

export_imports

If TRUE (the default), export all objects that are imported by the package. If FALSE export only objects defined in the package.

helpers

if TRUE loads testthat test helpers.

attach_testthat

If TRUE, attach testthat to the search path, which more closely mimics the environment within test files.

quiet

if TRUE suppresses output from this function.

recompile

DEPRECATED. force a recompile of DLL from source code, if present. This is equivalent to running pkgbuild::clean_dll() before load_all

warn_conflicts

If TRUE, issues a warning if a function in the global environment masks a function in the package. This can happen when you accidentally source a .R file, rather than using load_all(), or if you define a function directly in the R console. This is frustrating to debug, as it feels like the changes you make to the package source aren't having the expected effect.

Details

Currently load_all:

Namespaces

The namespace environment <namespace:pkgname>, is a child of the imports environment, which has the name attribute imports:pkgname. It is in turn is a child of <namespace:base>, which is a child of the global environment. (There is also a copy of the base namespace that is a child of the empty environment.)

The package environment <package:pkgname> is an ancestor of the global environment. Normally when loading a package, the objects listed as exports in the NAMESPACE file are copied from the namespace to the package environment. However, load_all by default will copy all objects (not just the ones listed as exports) to the package environment. This is useful during development because it makes all objects easy to access.

To export only the objects listed as exports, use export_all=FALSE. This more closely simulates behavior when loading an installed package with library(), and can be useful for checking for missing exports.

Shim files

load_all also inserts shim functions into the imports environment of the loaded package. It presently adds a replacement version of system.file which returns different paths from base::system.file. This is needed because installed and uninstalled package sources have different directory structures. Note that this is not a perfect replacement for base::system.file.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
## Not run: 
# Load the package in the current directory
load_all("./")

# Running again loads changed files
load_all("./")

# With reset=TRUE, unload and reload the package for a clean start
load_all("./", TRUE)

# With export_all=FALSE, only objects listed as exports in NAMESPACE
# are exported
load_all("./", export_all = FALSE)

## End(Not run)

pkgload documentation built on Oct. 14, 2021, 1:08 a.m.