9

I wrote an R package for internal purposes and also added some vignettes. When I use devtools::install(build_vignettes = TRUE), all vignettes are installed properly on my machine. But in order to distribute the package to colleages, I would like to generate a windows binary.

But when I use Build binary package from the RStudio Build pane, the vignettes will not show up when the package is installed from the generated binary. I figured that I could move the vignettes from doc to inst/doc before building the binary package, but this needs to be done manually whenever a vignette changes.

From R CMD INSTALL --help I could not figure if there is an option to include building the vignettes.

Is there any better option available than manually copying the files from doc to inst/doc?

I already tried devtools::build_vignettes(). This is the output in the console:

> devtools::build_vignettes()
Building archivR vignettes
Moving vig1.html, vig2.html, vig1.R, vig2.R to doc/
Copying vig1.Rmd, vig2.Rmd to doc/
Building vignette index

It says that the files are copied to doc/. They do not appear in inst/doc.

Paul Roub
  • 36,322
  • 27
  • 84
  • 93
der_grund
  • 1,898
  • 20
  • 36

3 Answers3

7

If you use 

devtools::build()
devtools::build("../package_name.tar.gz", binary=TRUE)

then the vignettes will be build into the tar.gz file, first and then into the binary.

No need to move any files about

Simon Bond
  • 81
  • 1
  • 2
  • 1
    Could you add more detail @der_grund ? I'm using windows btw. To be clearer "../package_name.tar.gz" needs to be edited to match the file that was created by devtools::build() – Simon Bond Oct 24 '19 at 15:20
  • 2
    I ran into this same problem and surprised it's not better addressed in the RStudio materials. I found this to be the easiest way, at the time of writing this comment – mkirzon Sep 01 '20 at 19:56
  • 1
    The above can be combined as such: `devtools::build(devtools::build(), binary = TRUE)` – mkirzon Sep 01 '20 at 20:01
6

Just for reference:

The most robust way is to build a source package (.tar.gz file) and then use the command tools instead of RStudio to build the binary. If you're in the directory where the source package can be found, you can use the following command at the command line (provided R is in your PATH):

R CMD INSTALL --build pkgname_x.y.z.tar.gz

with pkgname_x.y.z.tar.gz the name of the tar file containing the source package.

Note that you should create the source package first and build from the source package if you want to have the vignettes added correctly.

Joris Meys
  • 106,551
  • 31
  • 221
  • 263
  • 1
    This works. Just a sidenote: In order for this command work on Windows, the `bin` folder from RTools has to be included in the PATH environment variable. – der_grund Jan 07 '20 at 09:55
3

I have also been struggling with the same question.

  • Previously, devtools::build_vignettes() put the results in inst/doc (for example, as recommended in the last bullet point here).
  • Since version 2.0.0 (released in October 2018), devtools::build_vignettes() now puts the results in doc (the specific change appears to be here). The reasons for this change are given in the issues linked to this commit.

I can't find a way of accomplishing the previous workflow using only devtools, so I used the following code. It will overwrite any files that are already in inst/doc or inst/Meta.

build_vignettes_to_inst <- function() {
  devtools::build_vignettes() # Builds vignettes to 'doc' and 'Meta'. Updates '.gitignore'.
  unlink(c("inst/doc", "inst/Meta"), recursive = TRUE) # Remove the directories if they exist
  dir.create("inst/doc"); dir.create("inst/Meta") # Create empty directories
  has_worked <- c( # Copy files to 'inst' subfolders
    file.copy(list.files("doc", full.names = TRUE), to = "inst/doc") 
    , file.copy(list.files("Meta", full.names = TRUE), to = "inst/Meta")
  )
  unlink(c("doc", "Meta"), recursive = TRUE) # Optional: Remove unwanted directories
  return(all(has_worked)) # Returns TRUE if everything worked OK
}

build_vignettes_to_inst() # Call the function

You can now call devtools::build() with binary = TRUE, and it will include the built (i.e. HTML) vignettes.

A-Breeze
  • 31
  • 3
  • @tshimkus Yes, this solution worked for me, using the above code. – A-Breeze Feb 19 '19 at 18:45
  • Thanks for sharing your approach. However, this looks quite complicated compared to `robocopy doc inst/doc` which I type into RStudio's Windows Terminal. Since you only need it before generating the binary package. – der_grund Feb 20 '19 at 06:50
  • Good point. My answer uses base R functionality to avoid the need for manually copying the files. – A-Breeze Feb 28 '19 at 09:26