Description

dev_example is a replacement forexample.run_exampleis 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)

Description

dev_help() searches for source documentation provided in packagesloaded by devtools. To improve performance, the.Rd files areparsed to create to index once, then cached. Usedev_topic_index_reset() to clear that index. You can manuallyretrieve the index for a local package withdev_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 ggplotload_all("ggplot2")dev_help("ggplot")# loads development documentation for ggplot## End(Not run)

Description

The⁠?⁠ andhelp functions are replacements for functions of thesame name in the utils package. They are made available when a package isloaded withload_all().

Usage

# help(topic, package = NULL, ...)# ?e2# e1?e2

Arguments

Details

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

Thehelp function is a replacement forutils::help() fromthe utils package. Ifpackage is not specified, it will search forhelp in devtools-loaded packages first, then in regular packages. Ifpackage is specified, then it will search for help in devtools-loadedpackages 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_allhelp("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)

Description

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

Usage

inst(name)

Arguments

Details

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

Examples

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

Description

ReturnsTRUE orFALSE depending on if the package has been loaded bypkgload.

Usage

is_dev_package(name)

Arguments

Description

load_all() loads a package. It roughly simulates what happenswhen a package is installed and loaded withlibrary(), withouthaving to first install the package. It:

• Loads all data files in⁠data/⁠. Seeload_data() for moredetails.

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

• Adds a shim fromsystem.file() toshim_system.file() inthe imports environment of the package. This ensures thatsystem.file()works with both development and installed packages despite their differingdirectory structures.

• Adds shims fromhelp() and⁠?⁠ toshim_help() andshim_question()to make it easier to preview development documentation.

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

• Loads any compiled translations ininst/po.

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

• If you usetestthat, will load all test helpers so you canaccess them interactively. devtools sets theDEVTOOLS_LOADenvironment variable to the package name to let you check whether thehelpers are run during package loading.

is_loading() returnsTRUE when it is called whileload_all()is running. This may be useful e.g. in.onLoad hooks.A package loaded withload_all() can be identified withis_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,  debug=TRUE)is_loading(pkg=NULL)

Arguments

Differences to regular loading

load_all() tries its best to reproduce the behaviour ofloadNamespace() andlibrary(). However it deviates from normalpackage loading in several ways.

• load_all() doesn't install the package to a library, sosystem.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 partypackages, so they will fail if they attempt to find files within yourpackage. One potential workaround is to usefs::path_package()instead ofsystem.file(), since that understands the mechanisms thatdevtools uses to load packages.

• load_all() loads all packages referenced inImports at load time,butloadNamespace() andlibrary() only load package dependencies asthey are needed.

• load_all() copies all objects (not just the ones listed as exports)into the package environment. This is useful during development becauseit makes internal objects easy to access. To export only the objectslisted as exports, useexport_all = FALSE. This more closely simulatesbehavior when loading an installed package withlibrary(), and canbe useful for checking for missing exports.

Controlling the debug compiler flags

load_all() delegates topkgbuild::compile_dll() to perform the actualcompilation, during which by default some debug compiler flags areappended. If you would like to produce an optimized build instead, you canopt out by either usingdebug = FALSE, setting thepkg.build_extra_flagsoption toFALSE, or setting thePKG_BUILD_EXTRA_FLAGS environment variabletoFALSE. For further details see the Details section inpkgbuild::compile_dll().

Examples

## Not run:# Load the package in the current directoryload_all("./")# Running again loads changed filesload_all("./")# With export_all=FALSE, only objects listed as exports in NAMESPACE# are exportedload_all("./", export_all=FALSE)## End(Not run)

Description

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

Usage

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

Arguments

Description

Loads all.RData files in the data subdirectory.

Usage

load_data(path=".")

Arguments

Description

Load a compiled DLL

Usage

load_dll(path=".")

Arguments

Description

It always starts by finding by walking up the path until it finds theroot directory, i.e. a directory containingDESCRIPTION. If itcannot find the root directory, or it can't find the specified path, itwill throw an error.

Usage

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

Arguments

Examples

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

Description

All functions search recursively up the directory tree from the input pathuntil 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 adesc::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.

Description

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

Usage

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

Arguments

Details

Whensystem.file is called from the R console (the globalenvironment), this function detects if the target package was loaded withload_all(), and if so, it uses a customized method of searchingfor the file. This is necessary because the directory structure of a sourcepackage is different from the directory structure of an installed package.

When a package is loaded withload_all, this function is also insertedinto the package's imports environment, so that calls tosystem.filefrom within the package namespace will use this modified version. If thisfunction were not inserted into the imports environment, then the packagewould end up callingbase::system.file instead.

Description

unload() attempts to cleanly unload a package, including unloadingits namespace, deleting S4 class definitions and unloading any loadedDLLs. Unfortunately S4 classes are not really designed to be cleanlyunloaded, and so we have to manually modify the class dependency graph inorder for it to work - this works on the cases for which we have testedbut there may be others. Similarly, automated DLL unloading is best testedfor simple scenarios (particularly withuseDynLib(pkgname) and mayfail in other cases. If you do encounter a failure, please file a bug reportathttps://github.com/r-lib/pkgload/issues.

unregister() is a gentler version ofunload() which removes thepackage from the search path, unregisters methods, and unregistersthe namespace. It doesn't unload the namespace or its DLL to keepit 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 directoryunload()# Unload package that is in ./ggplot2/unload(pkg_name("ggplot2/"))library(ggplot2)# unload the ggplot2 package directly by nameunload("ggplot2")## End(Not run)