I am building an R package.
I have an rmarkdown file at vignettes/mydoc.Rmd.
Using devtools::build_vignettes() results in files appearing at inst/doc.
No warnings or errors appear when I use R CMD build ..
However, when I use vignette() from within R, I do not see any vignette for the package.
My DESCRIPTION file includes:
Suggests: knitr,
rmarkdown,
VignetteBuilder: knitr
It's not clear how/if you're installing in between steps. I'll quote from Hadley's R Packages website, the Vignettes chapter, mostly from the Development Cycle section:
To create your first vignette, run:
devtools::use_vignette("my-vignette")
This will:
Create a vignettes/ directory.
Add the necessary dependencies to DESCRIPTION (i.e. it adds knitr to the Suggests and VignetteBuilder fields).
Draft a vignette, vignettes/my-vignette.Rmd.
The above can be done manually or via the use_vignette() command, but it does need to be done.
After authoring your vignette, it will need to be built.
You can build all vignettes from the console with devtools::build_vignettes(), but this is rarely useful. Instead use devtools::build() to create a package bundle with the vignettes included. RStudio’s "Build & reload" does not build vignettes to save time. Similarly, devtools::install_github() (and friends) will not build vignettes by default because they’re time consuming and may require additional packages. You can force building with devtools::install_github(build_vignettes = TRUE). This will also install all suggested packages.
I believe that devtools::install() will include any vignettes that are already built, the extra argument is only needed if you want rebuild them at the time of installation.
R CMD BUILD makes a tarball, it doesn't modify your development directories, and R CMD INSTALL installs the package in your library, it also doesn't modify your development directories.
For development you can use just devtools::install(..., build_vignettes = T) when you want to rebuild vignettes and install a package.
You really only need to build the package itself (generate zip or tarball depending on your system) when you're ready to release to CRAN. At that point, I'd use devtools::build(..., vignettes = T) as a wrapper for R CMD BUILD, but that's just a preference.
I've been experiencing very erratic behaviour with
R CMD build myPackage
R CMD INSTALL myPackage
sometimes this installs the vignettes, and sometimes not.
devtools::install(build_vignettes = TRUE) seems like a more robust alternative. It also has the advantage of offering to update any outdated packages involved in the installation.
Related
I've downloaded the source code of an R package (You may use this R package by git-cloneing or downloading zipped version). I want to install the package via the Install and Restart button (4) in the Build tab (1). In configuration (2) I selected "Vignettes" (3).
Other configuration options I use:
Unfortunately, when I press Install and Restart, the package is installed but without its vignettes,i.e., no vignettes in the package's help page are displayed:
When I install the same package from CRAN, the vignettes are present:
Question: Is there a way to install a package with its vignettes by using this Install and Restart button. Maybe some configuration options are missing?
I use RStudio 1.3.1091, R 4.0.2 on Windows 10.
Update:
I'm aware of the solutions like:
devtools::install_github("r-lib/pkgdown", build_vignettes = TRUE)
Or in the Terminal window:
R CMD build .
R CMD INSTALL pkgdown_1.6.1.9000.tar.gz
But my question is about the functionality of the Install and Restart button (or similar tools in RStudio).
I installed this package in RStudio using devtools::install_github("r-lib/pkgdown", build_vignettes = TRUE). The vignettes are installing using this method.
vignette(package = "pkgdown")
Vignettes in package ‘pkgdown’:
linking Auto-linking (source, html)
pkgdown Introduction to pkgdown (source, html)
metadata Metadata (source, html)
search Search (source, html)
Furthermore, vignette("pkgdown") brings up the main vignette for the package. However, the help documentation landing page for the package appears to have been updated to no longer link to the vignettes.
Report this as a potential issue: https://github.com/r-lib/pkgdown/issues
If the vignettes are not installing when using RStudio's menu- and GUI-based approach, perhaps the issue is a bug in RStudio and not in the package.
I am currently working on an R package that is going to be submitted CRAN within a few weeks. The package needs some latex packages to run. Those latex packages are available on CTAN and injected in the preamble of RMarkdown documents via rmarkdown::latex_dependency().
This is the concept of my actual knit_print method.
#' #export
knit_print.my_class <- function(obj, ...) {
knitr::raw_latex(
to_latex(obj),
meta = list(
rmakrdown::latex_dependency(
"ragged2e"
)
)
)
}
My question is how those dependencies can be specified in a way such that CRAN is going to accept this submission. As far as I can tell, there are four options
submit the package as-is and add installation instructions via the documentation and the SystemRequirements field of the DESCRIPTION file.
include all necessary latex packages in my R package and somehow make them available to the client's latex compiler
add a dependency to tinytex which can install CTAN packages automatically
Throw an error during installation if the dependencies are not met
So far, I used option (1).
My configuration for travis (ubuntu 14.04) is
apt install texlive-latex-extra
tlmgr install standalone
For appveyor (Windows Server 2012 R2 x64), I unpack miktex-portable.exe and add it to the PATH. Then I get the following packages.
mpm --install=standalone
mpm --install=ms
mpm --install=pbox
mpm --install=xcolor
mpm --install=colortbl
mpm --install=mptopdf
What I found out so far
using google to search for external dependencies and CRAN sumbissions only yielded information about C and C++ dependencies, which didn't help my cause.
Looking at some source code revealed that rticles include certain .sty files directly in inst/ which leads me to believe, that (2) is the correct answer. However, rticles defines custom output formats and those don't have to "install" the latex packages since the .sty files are copied to the render directory as part of a template.
magick uses a config file that prevents the installation in case (system) dependencies are not met. It also throws an informative error message that instructs the client how the dependencies can be met.
the tinytex package did not run any compile tests on CRAN when it was submitted. I also can't make tinytex it work on appveyor
I am reasonably familiar with the CRAN Repository Policy and there is generally no provision for external dependencies off CRAN etc.
That said I stretched CRAN a little to by downloading pre-built libraries off GitHub as needed. You could model your package after that.
But what I really think you should do is to ... prepare your pdf vignette locally and then have the R package 'inject' it as is. How to do that is explained eg in this post by Mark and I just converted my RcppAnnoy package to do just that. Of course, YMMV.
I'm running R CMD INSTALL --build package on a windows computer. My package imports a couple of other packages which themselves depend on some more packages. I have all dependencies installed in the local r_libs folder and everything works.
Now sometimes I have the my package source code on a different windows computer. On this computer I don't have all the dependency packages installed.
When I try to use R CMD INSTALL --build package, I get the obvious "ERROR: dependencies 'package a', 'package b', etc, are not available for package".
My question is: Can I build the package using R CMD INSTALL --build without the dependency checks and without removing the Import and Depends entries in the DESCRIPTION file?
After consulting --help, I tried the --no-test-load option but no luck.
I reckon you want to build a .zip binary version of the package on a computer where not all dependencies are installed. And I'm afraid I'll have to disappoint you, as this won't be possible.
Building a binary package is done in two steps: first the package is installed from source (that's why you have to use R CMD INSTALL and then the created binaries are zipped in a convenient format for installation on a windows machine. The dependencies are checked at time of installation from source, and any missing dependencies will throw the error you're facing.
As R needs information from the dependencies at time of installation from source, you can't get around installing them before building the whole thing. This also makes sense. An installed package in R contains a set of .rds files which contain package information in a more convenient format for R. In order to create that information for the NAMESPACE file, it needs to be able to access the packages from which functions are imported. If not, it can't construct the correct information about the namespace.
So your only option is to install the dependencies on the computer you use to build. And if you actually want to use the package on that computer, you'll have to install those dependencies anyway.
More information:
R Internals : https://cran.r-project.org/doc/manuals/r-release/R-ints.html#Package-Structure
Writing R Extensions: https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Package-namespaces
In a package I'm developing with R Studio, I create vignettes via devtools::use_vignette("mydoc.Rnw"), which gives a standard vignette header like
---
title: "Title"
author: "Michael Friendly"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
I have followed all the instructions in http://yihui.name/knitr/demo/vignette/ and http://r-pkgs.had.co.nz/vignettes.html. The vignettes are listed on the CRAN page for the package, yet they seem inaccessible in an R session with the package loaded.
> browseVignettes("matlib")
No vignettes found by browseVignettes("matlib")
> library(tools)
> names(vignetteEngine(package = 'matlib'))
Error in getEngine(name, package) :
None of packages ‘matlib’ have registered vignette engines
I know that other packages with knitr-processed .Rmd vignettes are accessible from the package, but can't figure out why mine are not.
What is missing?
My vignettes/ directory contains only the .Rmd files (no PDFs), but that seems the same as, e.g., https://github.com/yihui/knitr/tree/master/vignettes.
Note devtools does not build vignettes by default when you devtools::install() (same thing for some install_* functions like install_github()) a package from a directory. You have to specify the argument build_vignettes = TRUE when you install the package. Currently there is no way to build vignettes using devtools if you just use the RStudio button Build & Reload. You have to Build Source Package, and run R CMD INSTALL on the tarball. Or run devtools::install(build_vignettes = TRUE) in the R console.
Well, I find a dark magic which can work around this situation.
From Configure Build Tools..., RStudio allows us to custom options for R CMD INSTALL when you click the Build & Reload button. In current implementation, it behaves like running R CMD INSTALL [options] pkg at the parent directory of the package directory.
It turns out that these options can be arbitrary strings, even including ;, thus enable us to run bash commands.
For example, we can specify -v; cd pkg; cp vignettes/*html inst/doc; R CMD INSTALL --no-multiarch --with-keep.source .; echo
In this way, -v nullify RStudio's R CMD INSTALL. Then we can copy built html files in vignette/ to inst/doc/ before we install the package using our own R CMD INSTALL. (cd pkg; frees us from type package name multiple times in subsequent commands. echo nullify the package name appended by RStudio.
I know there are many drawbacks in this trick, such as hard-coding package name which is error prone if the package name is changed latter.
Use it at your own risk.
Hope RStudio will comes out a elegant solution soon.
On my end, using devtools::install(build_vignettes = TRUE) would solve the vignettes problem: browseVignettes("mypackage") would work normally. But every time I tried to open a help file ?myfunction, there would be an error message:
Error in fetch(key) : lazy-load database
'/Library/Frameworks/R.framework/Versions/3.6/Resources/library/mypackage/help/mypackage.rdb' is corrupt
The safest way to solve both issues, in my opinion, is to do R CMD build mypackage and R CMD INSTALL mypackage.1.0.tar.gz.
From the Writing R Extensions Manual, I read that
As from R 2.14.0 the preferred location for the Sweave sources is the
subdirectory vignettes of the source packages, but for compatibility
with earlier versions of R, vignette sources will be looked for in
inst/doc if vignettes does not exist.
However, when I create a vignettes subdirectory of the package source, when I run devtools::check() or R CMD check I get a warning for Package vignette(s) without corresponding PDF. If I put the vignette (.Rnw and .pdf) in inst/doc the check completes without complaints. I tried looking in my library at installed packaged and did not see any directories named vignettes. Should I still use the deprecated location?
You put the .Rnw sources in vignettes/ as you did, but you missed out a critical step; don't check the source tree. The expected workflow is to build the source tarball and then check that tarball. Building the tarball will create the vignette PDF.
R CMD build ../foo/pkg
R CMD check ./pkg-0.4.tar.gz
for example will build a source package tarball from the sources in ../foo/pkg creating the .tar.gz package in the current directory with the package name and version appended. Then you run R CMD check on that source package.
If you want your vignette built for you put it in vignettes/ and build the source package. At some future date, R Core may remove the ability to build vignettes from inst/doc so go with the advised location now and avoid check the sources directly.
I had a hard time interpreting this too.
I believe the intention is that you should put the .Rnw file in vignettes/ and the PDF (suitably compacted) in inst/doc/, which technically agrees with the documentation if you read carefully enough. (That is, it says the sources should go in vignettes/. I don't see where it says in so many words that you ought to put the corresponding PDF in inst/doc/, but it doesn't not say it, and that interpretation seems to make R CMD check happy ...)
The resolution is in #GavinSimpson's answer (i.e. one is expected to build the tarball and then check it, rather than checking the source directory itself). (My two cents is that it might be best if R-core officially deprecated (and eventually removed) direct source checking rather than confusing all of us groundlings ...)