| ns-hooks {base} | R Documentation |
Packages can supply functions to be called when loaded, attached, detached or unloaded.
.onLoad(libname, pkgname)
.onAttach(libname, pkgname)
.onUnload(libpath)
.onDetach(libpath)
.Last.lib(libpath)
libname |
a character string giving the library directory where the package defining the namespace was found. |
pkgname |
a character string giving the name of the package. |
libpath |
a character string giving the complete path to the package. |
After loading, loadNamespace looks for a hook function
named .onLoad and calls it (with two unnamed arguments) before
sealing the namespace and processing exports.
When the package is attached (via library or
attachNamespace), the hook function .onAttach is
looked for and if found is called (with two unnamed arguments) before
the package environment is sealed.
If a function .onDetach is in the namespace or .Last.lib
is exported from the package, it will be called (with a single
argument) when the package is detached. Beware that it
might be called if .onAttach has failed, so it should be
written defensively. (It is called within tryCatch, so
errors will not stop the package being detached.)
If a namespace is unloaded (via unloadNamespace), a hook
function .onUnload is run (with a single argument) before final
unloading.
Note that the code in .onLoad and .onUnload should not
assume any package except the base package is on the search path.
Objects in the current package will be visible (unless this is
circumvented), but objects from other packages should be imported or
the double colon operator should be used.
.onLoad, .onUnload, .onAttach and
.onDetach are looked for as internal objects in the namespace
and should not be exported (whereas .Last.lib should be).
Note that packages are not detached nor namespaces unloaded at the end
of an R session unless the user arranges to do so (e.g., via
.Last).
Anything needed for the functioning of the namespace should be
handled at load/unload times by the .onLoad and
.onUnload hooks. For example, DLLs can be loaded (unless done
by a useDynLib directive in the ‘NAMESPACE’ file) and
initialized in .onLoad and unloaded in .onUnload. Use
.onAttach only for actions that are needed only when the
package becomes visible to the user (for example a start-up message)
or need to be run after the package environment has been created.
Loading a namespace should where possible be silent, with startup
messages given by .onAttach. These messages (and any essential
ones from .onLoad) should use packageStartupMessage
so they can be silenced where they would be a distraction.
There should be no calls to library nor require in these
hooks. The way for a package to load other packages is via the
‘Depends’ field in the ‘DESCRIPTION’ file: this ensures
that the dependence is documented and packages are loaded in the
correct order. Loading a namespace should not change the search path,
so rather than attach a package, dependence of a namespace on another
package should be achieved by (selectively) importing from the other
package's namespace.
Uses of library with argument help to display basic
information about the package should use format on the
computed package information object and pass this to
packageStartupMessage.
There should be no calls to installed.packages in startup
code: it is potentially very slow and may fail in versions of R
before 2.14.2 if package installation is going on in parallel. See
its help page for alternatives.
Compiled code should be loaded (e.g., via
library.dynam) in .onLoad or a useDynLib
directive in the ‘NAMESPACE’ file, and not in .onAttach.
Similarly, compiled code should not be unloaded (e.g., via
library.dynam.unload) in .Last.lib nor
.onDetach, only in .onUnload.
setHook shows how users can set hooks on the same events, and
lists the sequence of events involving all of the hooks.
reg.finalizer for hooks to be run at the end of a session.
loadNamespace for more about namespaces.