.onLoad(libname, pkgname) .onAttach(libname, pkgname) .onUnload(libpath) .onDetach(libpath) .Last.lib(libpath)
.onAttach. These messages (and any essential ones from
.onLoad) should use
packageStartupMessageso they can be silenced where they would be a distraction. There should be no calls to
requirein these hooks. The way for a package to load other packages is via the Depends field in the
DESCRIPTIONfile: 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
helpto display basic information about the package should use
formaton the computed package information object and pass this to
packageStartupMessage. There should be no calls to
installed.packagesin 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
useDynLibdirective in the
NAMESPACEfile, and not in
.onAttach. Similarly, compiled code should not be unloaded (e.g., via
.onDetach, only in
loadNamespacelooks for a hook function named
.onLoadand calls it (with two unnamed arguments) before sealing the namespace and processing exports. When the package is attached (via
attachNamespace), the hook function
.onAttachis looked for and if found is called (with two unnamed arguments) before the package environment is sealed. If a function
.onDetachis in the namespace or
.Last.libis exported from the package, it will be called (with a single argument) when the package is
detached. Beware that it might be called if
.onAttachhas 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
.onUnloadis run (with a single argument) before final unloading. Note that the code in
.onUnloadshould 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.
.onDetachare looked for as internal objects in the namespace and should not be exported (whereas
.Last.libshould 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
.onUnloadhooks. For example, DLLs can be loaded (unless done by a
useDynLibdirective in the
NAMESPACEfile) and initialized in
.onLoadand unloaded in
.onAttachonly 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.
setHookshows how users can set hooks on the same events, and lists the sequence of events involving all of the hooks.
reg.finalizerfor hooks to be run at the end of a session.
loadNamespacefor more about namespaces.