distinction between `devtools::load_all()` and `devtools::install()`

[bvreede]

here is an example of the distinction between devtools::load_all() and devtools::install()

#' hello
#'
#' @param name name to say hello to
#' @param birth_year year of birth of `name`
#'
#' @return says hello and tells you the age
#' @export
hello <- function(name, birth_year) {
  age <- calculate_age(birth_year)
  print(paste0("Hello ", name, ". You are ", age, " years old."))
}

#' calculate_age
#'
#' @param birth_year year of birth
#'
#' @return age as of today. NOTE: no export
calculate_age <- function(birth_year) {
  current_year <- as.numeric(format(Sys.Date(), "%Y"))
  return(current_year - birth_year)
}

then try:

load_all()
calculate_age(2000) # success
hello("luke", 2000) # success
# then click `Build>Install>Clean & Install; or `devtools::install()`
hello("luke", 2000) # success
calculate_age(2000) # fails 

I am not sure what the difference between devtools::install() and Build > Install > Clean and install is. Both install the package locally. After Build > Install > Clean and install , I also get a message "Restarting R session" in the console, but I it seems to be that devtools::install() does the same. In both cases, local variables and functions that I defined interactively are preserved after the process, which is a bit surprising to me.

To cut a long story short, in line with the documentation of devtools I would suggest to mostly use devtools::load_all(), and install() only "when necessary". I have no clear rules when exactly, but for instance after adding a new feature, corresponding tests and documentation, it makes sense to install() and see what the package looks like for the user.

Here are some useful insights:

• load_all() simulates installing and reloading your package, loading R code in R/, compiled shared objects in src/ and data files in data/. During development you would usually want to access all functions (even un-exported internal ones) so load_all() works as if all functions were exported in the package NAMESPACE.
• install() reinstalls the package, detaches the currently loaded version then reloads the new version with library(). Reloading a package is not guaranteed to work: see the documentation for unload() for caveats.

What do you think?

Originally posted by @f-hafner in https://github.com/carpentries-incubator/lesson-R-packaging/issues/92#issuecomment-1408264508

[PabRod]

My two cents:

• To export or not to export is advanced material. If I remember properly, our approach in this course was: export always, but be aware you don't have to. This will satisfy the needs of 99% of scientific programmers, and the 1% who worked with private functions in C++ will not need further explanation.
• All the consequences of the export/not export problem are advanced too. So I suggest not writing more than an optional callout talking about this difference.

[multimeric]

Exporting is already explained here: https://carpentries-incubator.github.io/lesson-R-packaging/documentation.html#the-export-field.

At most I think there could be another callout that distinguishes between load_all() and install() in the Documenting section.