pkgload: Simulate Package Installation and Attach

Description

Simulates the process of installing a package and then attaching it. This is a key part of the 'devtools' package as it allows you to rapidly iterate while developing a package.

Author(s)

Maintainer: Lionel Henry lionel@posit.co

Authors:

• Hadley Wickham

• Winston Chang

• Jim Hester

Other contributors:

• Posit Software, PBC [copyright holder, funder]

• R Core team (Some namespace and vignette code extracted from base R) [contributor]

See Also

Useful links:

• https://github.com/r-lib/pkgload

• https://pkgload.r-lib.org

• Report bugs at https://github.com/r-lib/pkgload/issues

Check that the version of an imported package satisfies the requirements

Description

Check that the version of an imported package satisfies the requirements

Usage

check_dep_version(dep_name, dep_ver = "*")

Arguments

Check that the version of an suggested package satisfies the requirements

Description

Check that the version of an suggested package satisfies the requirements

Usage

check_suggested(package, version = NULL, compare = NA, path = inst("pkgload"))

Arguments

Run a examples for an in-development function.

Description

dev_example is a replacement for example. run_example is a low-level function that takes a path to an Rd file.

Usage

dev_example(topic, quiet = FALSE)

run_example(
  path,
  run_donttest = FALSE,
  run_dontrun = FALSE,
  env = new.env(parent = globalenv()),
  quiet = FALSE,
  macros = NULL,
  run,
  test
)

Arguments

Examples

## Not run: 
# Runs installed example:
library("ggplot2")
example("ggplot")

# Runs development example:
dev_example("ggplot")

## End(Not run)

In-development help for package loaded with devtools

Description

dev_help() searches for source documentation provided in packages loaded by devtools. To improve performance, the .Rd files are parsed to create to index once, then cached. Use dev_topic_index_reset() to clear that index. You can manually retrieve the index for a local package with dev_topic_index().

Usage

dev_help(
  topic,
  dev_packages = NULL,
  stage = "render",
  type = getOption("help_type")
)

dev_topic_find(topic, dev_packages = NULL)

dev_topic_index(path = ".")

dev_topic_index_reset(pkg_name)

Arguments

Examples

## Not run: 
library("ggplot2")
help("ggplot") # loads installed documentation for ggplot

load_all("ggplot2")
dev_help("ggplot") # loads development documentation for ggplot

## End(Not run)

Return devtools metadata environment

Description

If the package was not loaded with devtools, returns NULL.

Usage

dev_meta(name)

Arguments

Examples

dev_meta("stats") # NULL

if (has_tests()) {
# Load the test package in directory "testLoadHooks"
load_all(pkgtest("testLoadHooks"))

# Get metadata for the package
x <- dev_meta("testLoadHooks")
as.list(x)

# Clean up.
unload("testLoadHooks")
}

Was devtools installed with tests?

Description

Was devtools installed with tests?

Usage

has_tests()

Drop-in replacements for help and ? functions

Description

The ⁠?⁠ and help functions are replacements for functions of the same name in the utils package. They are made available when a package is loaded with load_all().

Usage

# help(topic, package = NULL, ...)

# ?e2
# e1?e2

Arguments

Details

The ⁠?⁠ function is a replacement for utils::?() from the utils package. It will search for help in devtools-loaded packages first, then in regular packages.

The help function is a replacement for utils::help() from the utils package. If package is not specified, it will search for help in devtools-loaded packages first, then in regular packages. If package is specified, then it will search for help in devtools-loaded packages or regular packages, as appropriate.

Examples

## Not run: 
# This would load devtools and look at the help for load_all, if currently
# in the devtools source directory.
load_all()
?load_all
help("load_all")

## End(Not run)

# To see the help pages for utils::help and utils::`?`:
help("help", "utils")
help("?", "utils")

## Not run: 
# Examples demonstrating the multiple ways of supplying arguments
# NB: you can't do pkg <- "ggplot2"; help("ggplot2", pkg)
help(lm)
help(lm, stats)
help(lm, 'stats')
help('lm')
help('lm', stats)
help('lm', 'stats')
help(package = stats)
help(package = 'stats')
topic <- "lm"
help(topic)
help(topic, stats)
help(topic, 'stats')

## End(Not run)

Return imports environment for a package

Description

Contains objects imported from other packages. Is the parent of the package namespace environment, and is a child of ⁠<namespace:base>⁠, which is a child of R_GlobalEnv.

Usage

imports_env(package)

Arguments

See Also

ns_env() for the namespace environment that all the objects (exported and not exported).

pkg_env() for the attached environment that contains the exported objects.

Get the installation path of a package

Description

Given the name of a package, this returns a path to the installed copy of the package, which can be passed to other devtools functions.

Usage

inst(name)

Arguments

Details

It searches for the package in .libPaths(). If multiple dirs are found, it will return the first one.

Examples

inst("pkgload")
inst("grid")

Is the package currently under development?

Description

Returns TRUE or FALSE depending on if the package has been loaded by pkgload.

Usage

is_dev_package(name)

Arguments

Load complete package

Description

load_all() loads a package. It roughly simulates what happens when a package is installed and loaded with library(), without having to first install the package. It:

• Loads all data files in ⁠data/⁠. See load_data() for more details.

• Sources all R files in the R directory, storing results in environment that behaves like a regular package namespace. See load_code() for more details.

• Adds a shim from system.file() to shim_system.file() in the imports environment of the package. This ensures that system.file() works with both development and installed packages despite their differing directory structures.

• Adds shims from help() and ⁠?⁠ to shim_help() and shim_question() to make it easier to preview development documentation.

• Compiles any C, C++, or Fortran code in the ⁠src/⁠ directory and connects the generated DLL into R. See pkgbuild::compile_dll() for more details.

• Loads any compiled translations in inst/po.

• Runs .onAttach(), .onLoad() and .onUnload() functions at the correct times.

• If you use testthat, will load all test helpers so you can access them interactively. devtools sets the DEVTOOLS_LOAD environment variable to the package name to let you check whether the helpers are run during package loading.

is_loading() returns TRUE when it is called while load_all() is running. This may be useful e.g. in .onLoad hooks. A package loaded with load_all() can be identified with with is_dev_package().

Usage

load_all(
  path = ".",
  reset = TRUE,
  compile = NA,
  attach = TRUE,
  export_all = TRUE,
  export_imports = export_all,
  helpers = export_all,
  attach_testthat = uses_testthat(path),
  quiet = NULL,
  recompile = FALSE,
  warn_conflicts = TRUE
)

is_loading(pkg = NULL)

Arguments

Differences to regular loading

load_all() tries its best to reproduce the behaviour of loadNamespace() and library(). However it deviates from normal package loading in several ways.

• load_all() doesn't install the package to a library, so system.file() doesn't work. pkgload fixes this for the package itself installing a shim, shim_system.file(). However, this shim is not visible to third party packages, so they will fail if they attempt to find files within your package. One potential workaround is to use fs::path_package() instead of system.file(), since that understands the mechanisms that devtools uses to load packages.

• load_all() loads all packages referenced in Imports at load time, but loadNamespace() and library() only load package dependencies as they are needed.

• load_all() copies all objects (not just the ones listed as exports) into the package environment. This is useful during development because it makes internal 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.

Examples

## Not run: 
# Load the package in the current directory
load_all("./")

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

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

## End(Not run)

Load R code.

Description

Sources all .R/.r files in the ⁠R/⁠ directory, storing results into the package namespace.

Usage

load_code(path = ".", quiet = NULL)

Arguments

Load data.

Description

Loads all .RData files in the data subdirectory.

Usage

load_data(path = ".")

Arguments

Load a compiled DLL

Description

Load a compiled DLL

Usage

load_dll(path = ".")

Arguments

Load all of the imports for a package

Description

The imported objects are copied to the imports environment, and are not visible from R_GlobalEnv. This will automatically load (but not attach) the dependency packages.

Usage

load_imports(path = ".")

Return the namespace environment for a package.

Description

Contains all (exported and non-exported) objects, and is a descendant of R_GlobalEnv. The hierarchy is ⁠<namespace:pkg>⁠, ⁠<imports:pkg>⁠, ⁠<namespace:base>⁠, and then R_GlobalEnv.

Usage

ns_env(package)

Arguments

Details

If the package is not loaded, this function returns NULL.

See Also

pkg_env() for the attached environment that contains the exported objects.

imports_env() for the environment that contains imported objects for the package.

Find file in a package.

Description

It always starts by finding by walking up the path until it finds the root directory, i.e. a directory containing DESCRIPTION. If it cannot find the root directory, or it can't find the specified path, it will throw an error.

Usage

package_file(..., path = ".")

Arguments

Examples

## Not run: 
package_file("figures", "figure_1")

## End(Not run)

Helper functions for working with development packages.

Description

All functions search recursively up the directory tree from the input path until they find a DESCRIPTION file.

Usage

pkg_path(path = ".")

pkg_name(path = ".")

pkg_desc(path = ".")

pkg_version(path = ".")

pkg_version_raw(path = ".")

pkg_ns(path = ".")

Arguments

Functions

• pkg_path(): Return the normalized package path.

• pkg_name(): Return the package name.

• pkg_desc(): Return the package DESCRIPTION as a desc::desc() object.

• pkg_version(): Return the parsed package version.

• pkg_version_raw(): Return the raw package version (as a string).

• pkg_ns(): Return the package namespace.

Parse package dependency strings.

Description

Parse package dependency strings.

Usage

parse_deps(string)

Arguments

Value

list of two character vectors: name package names, and version package versions. If version is not specified, it will be stored as NA.

Examples

parse_deps("httr (< 2.1),\nRCurl (>= 3)")
# only package dependencies are returned
parse_deps("utils (== 2.12.1),\ntools,\nR (>= 2.10),\nmemoise")

Parses the NAMESPACE file for a package

Description

Parses the NAMESPACE file for a package

Usage

parse_ns_file(path = ".")

Arguments

Examples

if (has_tests()) {
parse_ns_file(pkgtest("testLoadHooks"))
}

Return package environment

Description

This is an environment like ⁠<package:pkg>⁠. The package environment contains the exported objects from a package. It is attached, so it is an ancestor of R_GlobalEnv.

Usage

pkg_env(package)

Arguments

Details

When a package is loaded the normal way, using library(), this environment contains only the exported objects from the namespace. However, when loaded with load_all(), this environment will contain all the objects from the namespace, unless load_all is used with export_all=FALSE.

If the package is not attached, this function returns NULL.

See Also

ns_env() for the namespace environment that all the objects (exported and not exported).

imports_env() for the environment that contains imported objects for the package.

Return the path to one of the packages in the devtools test dir

Description

devtools comes with some simple packages for testing. This function returns the path to them.

Usage

pkgtest(package)

Arguments

Examples

if (has_tests()) {
pkgtest("testData")
}

Run user and package hooks.

Description

Run user and package hooks.

Usage

run_pkg_hook(package, hook)

run_user_hook(package, hook)

Arguments

Replacement version of system.file

Description

This function is meant to intercept calls to base::system.file(), so that it behaves well with packages loaded by devtools. It is made available when a package is loaded with load_all().

Usage

shim_system.file(..., package = "base", lib.loc = NULL, mustWork = FALSE)

Arguments

Details

When system.file is called from the R console (the global environment), this function detects if the target package was loaded with load_all(), and if so, it uses a customized method of searching for the file. This is necessary because the directory structure of a source package is different from the directory structure of an installed package.

When a package is loaded with load_all, this function is also inserted into the package's imports environment, so that calls to system.file from within the package namespace will use this modified version. If this function were not inserted into the imports environment, then the package would end up calling base::system.file instead.

Unload a package

Description

unload() attempts to cleanly unload a package, including unloading its namespace, deleting S4 class definitions and unloading any loaded DLLs. Unfortunately S4 classes are not really designed to be cleanly unloaded, and so we have to manually modify the class dependency graph in order for it to work - this works on the cases for which we have tested but there may be others. Similarly, automated DLL unloading is best tested for simple scenarios (particularly with useDynLib(pkgname) and may fail in other cases. If you do encounter a failure, please file a bug report at https://github.com/r-lib/pkgload/issues.

unregister() is a gentler version of unload() which removes the package from the search path, unregisters methods, and unregisters the namespace. It doesn't unload the namespace or its DLL to keep it in working order in case of dangling references.

Usage

unload(package = pkg_name(), quiet = FALSE)

unregister(package = pkg_name())

Arguments

Examples

## Not run: 
# Unload package that is in current directory
unload()

# Unload package that is in ./ggplot2/
unload(pkg_name("ggplot2/"))

library(ggplot2)
# unload the ggplot2 package directly by name
unload("ggplot2")

## End(Not run)