source.pkg: Quickly load code and data of a package

Description Usage Arguments Details Value Side effects Note Author(s) References See Also Examples


source() all of the source files and data files in a package into an environment on the search path. If an environment is not already attached by a previous invocation of source.pkg(), one will be created and attached. It also loads DLLs if requested, and if those DLLs can be found. This function is intended for use in code development, in situations where code from a package can be tested without worrying about imports, namespaces, etc.


source.pkg(pkg.dir = getOption("scriptests.pkg.dir", "pkg"),
           pattern = ".*",
           suffix = "\\.R$",
           dlls = c("no", "check", "build", "src"),
           unload=FALSE, pos = NA, all = FALSE,
           path=getOption("scriptests.pkg.path", default=getwd()),



The directory where the package code lives. This is remembered and the same value used as the default in subsequent invocations. This can be different from the package name, which is read from <pkg.dir>/DESCRIPTION.


A regular expression specifying the R files to source


The suffix for the R code files. Files are sourced only if they match both pattern and suffix.


Indicates where to look for DLLs or shared-objects:

  • no: don't load any DLLs

  • check: look in <pkg.dir>.Rcheck/<>/libs and <>.Rcheck/<>/libs

  • build: look in the directory build (can be created with R CMD INSTALL -l build <package-tarball>, and before loading each time, it may be necessary to do dyn.unload(...), using the path of the DLL as printed.)


Which environment on the search path to source R code into


Should compiled object files be unloaded?


If TRUE, all files matching the pattern and suffix are sourced, if FALSE, only files that have changed since last sourced are sourced again.


If TRUE the environments on all functions sourced are set to the global environment. See NOTE below for explanation.


The file system path to the directory in which the package is located. Can be a semi-colon separated list of paths. The initial default for path is the current directory. By default, R source files are looked for in the directory found by appending pkg.dir to path, i.e. <path>/<pkg.dir>/R/*.R. If path contains the string $PKG, pkg.dir is substituted for $PKG instead of being appended to path. path is remembered and the same value used as the default in subsequent invocations.


The name of the program that outputs the source-code-control version number, e.g., for SVN, svnversion.


The package directory (pkg.dir) does not need to be the same as the package name. The package name (refered to here as is found by reading the DESCRIPTION file.

All the objects created by the .R files are created in a special environment named pkgcode:<>. If this environment does not already exist, it will be created and attached to the search path in position pos. If it does exist, no attempt is made to clean it before sourcing the .R files. All functions and objects defined in the .R files will be visible – namespaces are not implemented.

The easiest way to use this function is when the working directory of the R session is the directory where each package lives, i.e., the R code for package mypackage will be in the directory ./mypackage/R (relative to the working directory of the R session.) However, if the package directory is located elsewhere, supply it as path=, and this will be remembered for future invocations of source.pkg().

This function does not attempt to replicate all the actions involved in creating and attaching a package. It does the following:


This function is executed for its side effects, which may include attaching a new environment to the search path, or moving an existing one, and reading function and object definitions into that environment. source.pkg() returns as its value a list of the problems encountered when sourcing the files.

Side effects

An environment is created and attached to the search path (or if it already exists, it is modified.) A variable named scriptests.pkg.dir is set in the global environment to the directory of the package whose code was sourced.


If reset.function.envirs=FALSE is supplied, the environments on the functions sourced will be the environment where they live on the search path. Functions with their environment set like this will not be able to see objects in the global environment or in any environment earlier on the search path. The default behavior of setting their environment to be the global environment produces behavior that is more similar to when the functions are sourced directly into the global environment.


Tony Plate


See Also

runtests() shares the options() variables scriptests.pkg.dir and scriptests.pkg.path that provide defaults for the pkg.dir and path arguments.

scriptests-package gives and overview of the package.


## Not run: 
# sourcing the code in a package stored in <mypackage>/{DESCRIPTION,R,man,tests}:
# sourcing the code in a package stored in path/to/dir/<mypackage>/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>", path="path/to/dir")
# sourcing the code in a package stored in pkg/{DESCRIPTION,R,man,tests}:
# where "pkg" is unrelated to the name of the pacakage
source.pkg("pkg", path="path/to/dir")
# sourcing the code in a package stored in <mypackage>/pkg/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>", path="$PKG/pkg")

## End(Not run)

scriptests documentation built on May 1, 2019, 6:51 p.m.