| % File src/library/base/man/ns-hooks.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{ns-hooks} |
| \alias{.onLoad} |
| \alias{.onUnload} |
| \alias{.onAttach} |
| \alias{.onDetach} |
| \alias{.Last.lib} |
| \title{Hooks for Namespace Events} |
| \description{ |
| Packages can supply functions to be called when |
| loaded, attached, detached or unloaded. |
| } |
| |
| \usage{ |
| .onLoad(libname, pkgname) |
| .onAttach(libname, pkgname) |
| .onUnload(libpath) |
| .onDetach(libpath) |
| .Last.lib(libpath) |
| } |
| \arguments{ |
| \item{libname}{a character string giving the library directory where |
| the package defining the namespace was found.} |
| \item{pkgname}{a character string giving the name of the package.} |
| \item{libpath}{a character string giving the complete path to the package.} |
| } |
| \details{ |
| After loading, \code{\link{loadNamespace}} looks for a hook function |
| named \code{.onLoad} and calls it (with two unnamed arguments) before |
| sealing the namespace and processing exports. |
| |
| When the package is attached (via \code{\link{library}} or |
| \code{\link{attachNamespace}}), the hook function \code{.onAttach} is |
| looked for and if found is called (with two unnamed arguments) before |
| the package environment is sealed. |
| |
| If a function \code{.onDetach} is in the namespace or \code{.Last.lib} |
| is exported from the package, it will be called (with a single |
| argument) when the package is \code{\link{detach}}ed. Beware that it |
| might be called if \code{.onAttach} has failed, so it should be |
| written defensively. (It is called within \code{\link{tryCatch}}, so |
| errors will not stop the package being detached.) |
| |
| If a namespace is unloaded (via \code{\link{unloadNamespace}}), a hook |
| function \code{.onUnload} is run (with a single argument) before final |
| unloading. |
| |
| Note that the code in \code{.onLoad} and \code{.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. |
| |
| \code{.onLoad}, \code{.onUnload}, \code{.onAttach} and |
| \code{.onDetach} are looked for as internal objects in the namespace |
| and should not be exported (whereas \code{.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., \emph{via} |
| \code{\link{.Last}}). |
| |
| Anything needed for the functioning of the namespace should be |
| handled at load/unload times by the \code{.onLoad} and |
| \code{.onUnload} hooks. For example, DLLs can be loaded (unless done |
| by a \code{useDynLib} directive in the \file{NAMESPACE} file) and |
| initialized in \code{.onLoad} and unloaded in \code{.onUnload}. Use |
| \code{.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. |
| } |
| |
| \section{Good practice}{ |
| Loading a namespace should where possible be silent, with startup |
| messages given by \code{.onAttach}. These messages (and any essential |
| ones from \code{.onLoad}) should use \code{\link{packageStartupMessage}} |
| so they can be silenced where they would be a distraction. |
| |
| There should be no calls to \code{library} nor \code{require} in these |
| hooks. The way for a package to load other packages is via the |
| \samp{Depends} field in the \file{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 \code{library} with argument \code{help} to display basic |
| information about the package should use \code{format} on the |
| computed package information object and pass this to |
| \code{packageStartupMessage}. |
| |
| There should be no calls to \code{\link{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., \emph{via} |
| \code{\link{library.dynam}}) in \code{.onLoad} or a \code{useDynLib} |
| directive in the \file{NAMESPACE} file, and not in \code{.onAttach}. |
| Similarly, compiled code should not be unloaded (e.g., \emph{via} |
| \code{\link{library.dynam.unload}}) in \code{.Last.lib} nor |
| \code{.onDetach}, only in \code{.onUnload}. |
| } |
| \seealso{ |
| \code{\link{setHook}} shows how users can set hooks on the same events, and |
| lists the sequence of events involving all of the hooks. |
| |
| \code{\link{reg.finalizer}} for hooks to be run at the end of a session. |
| |
| \code{\link{loadNamespace}} for more about namespaces. |
| } |
| \keyword{utilities} |