22

is there any way to display a message when a user loads library(myCustomLibrary)? Upon loading, I want to display a message that tells the user how to run all the test functions.

jogo
  • 12,469
  • 11
  • 37
  • 42
Yannick Wurm
  • 3,617
  • 6
  • 25
  • 28

3 Answers3

33

Quick points (and updated edit in 2021):

  • while if your package has a NAMESPACE, then .onLoad() is where you used to do this: but .onLoad() has been required to be 'silent'

  • if your package has a NAMESPACE, then .onAttach() is where can call, preferably via packageStartupMessage() (which can be suppressed where cat() or message() cannot

  • if your package does not have NAMESPACE, then you must add one now (and .First.lib() was where you used to do this) -- NAMESPACES have been mandatory for a few years now

  • either way, use packageStartupMessage() instead of cat() so that users have a choice of suppressing this.

Dirk Eddelbuettel
  • 360,940
  • 56
  • 644
  • 725
  • 1
    +1 indeed. Where do I have to put this? Which file of my package? – Matt Bannert Feb 20 '14 at 19:06
  • It used to matter, and people used `R/zzz.R` -- which now is mostly a convention. I think you can do `R/onLoad.R` just as well. – Dirk Eddelbuettel Feb 20 '14 at 19:07
  • 2
    in the Hadley's book it is mentioned user *should* use `.onAttach()` instead `.onLoad()` for that purpose. He didn't explain why. http://r-pkgs.had.co.nz/r.html#r-code – jangorecki Sep 01 '14 at 09:53
  • I’m disappointed that even R CMD check now gives a note if it’s in `.onLoad()` instead of `.onAttach()`. My reason is this: if you call a function using `package::function()`, the startup message will not be shown if it’s in `.onAttach()`. In some cases, sources or references then remain unknown. – MS Berends Jan 08 '22 at 22:26
  • I mostly dislike the non-intuitive language around the two functions, but in 20+ years of package writing I have generally found that _Writing R Extensions_ is both authorative, and aligned with that `R CMD check` tests for. Standards change, but as `NAMESPACES` are now common and required these distinctions make some sense. – Dirk Eddelbuettel Jan 08 '22 at 22:57
9

Yes. You can use the .onLoad, .onAttach, or .First.lib functions to do whatever you want when the package is loaded. I suggest looking at the help for those functions. You would use .onLoad with a namespace, and .First.lib without.

One convention is that people will frequently put these commands in a separate zzz.R file, which is just used for package related code.

Shane
  • 98,550
  • 35
  • 224
  • 217
2

Updated answer (2019):

In the help section "Good practice" in ?.onAttach the recommendation is now:

Loading a namespace [= in .onLoad] 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.

R CMD CHECK will complain if .onLoad is not silent...

R Yoda
  • 8,358
  • 2
  • 50
  • 87