{attachment} v0.2.4: fill the Remotes field

Author : Sébastien Rochette
Tags : development, package, thinkrverse
Date :

A new version of {attachment} is available on CRAN. Get dependencies installed from GitHub, GitLab, … and add the link to the ‘Remotes’ field in the DESCRIPTION file of your package.

install.packages("attachment")

While waiting for CRAN release, you can install from GitHub: remotes::install_github("ThinkR-open/[email protected]")

{attachment} helps you deal with dependencies during your package development.
All packages used in your code needs to be declared in the DESCRIPTION file, so that other users can install your package with required dependencies. {attachment} will extract packages declared in your codes and list them in the correct place (‘Imports’, ‘Suggests’ and now ‘Remotes’) in your DESCRIPTION file.

Note that {attachment} can be used out of package development if you want to extract the list of dependencies used in your R scripts or Rmarkdown files, wherever they are stored.

TL;DR – NEWS

EDIT (2021-11-16): Combines v0.2.3 and v0.2.4 (coming soon on CRAN)

Breaking changes

  • (broken in 0.2.3) – att_to_desc_from_is() can now run with must.exist = FALSE to be used to fill DESCRIPTION file during bookdown CI process. CI YAML files, like the ones coming from gitlabr::use_gitlab_ci() for bookdown outputs must be updated with this parameter.

Major changes

  • Allow to add Remotes field to DESCRIPTION with set_remotes_to_desc()
  • Split vignette in two: package development and other dependencies management

Minor changes

  • Check for packages names misspelled before filling DESCRIPTION.
  • Allow vector of R files in att_from_rscripts()
  • Move default git branch from master to main
  • Allow to clean remotes list before updating with set_remotes_to_desc(clean = TRUE)

Bug fixes

  • Add NAMESPACE if missing with att_amend_desc(document = TRUE)
  • Add DESCRIPTION with empty skeleton if missing with att_amend_desc()
  • Default to remove NAMESPACE before updating to get rid of corrupted ones in att_from_namespace()
  • Fix detection of multiple render outputs in Rmd YAML with att_from_rmd()

Reminder: during package development

The star function of {attachment} is attachment::att_amend_desc() to be run each time before devtools::check(). This will save you some warnings and errors !

att_amend_desc()

New in v0.2.4

Propose content for the “Remotes” field in DESCRIPTION

set_remotes_to_desc() adds packages that were installed on your computer from other sources than CRAN to Remotes: field in DESCRIPTION, according to the list in ‘Imports’ and ‘Suggests’.

For instance:

  • For GitHub : Remotes: thinkr-open/attachment
  • For GitLab : Remotes: gitlab::jimhester/covr

You may want to run it after att_amend_desc() in your package development.

att_amend_desc(dummypackage) %>%
  set_remotes_to_desc()

Let’s create a small DESCRIPTION file

desc_file <- tempfile(pattern = "desc")
cat("
Imports:
    attachment,
    glue
Suggests:
    desc
", file = desc_file) 

Let me install {attachment} from GitHub and run set_remotes_to_desc() on the exemple file.

# install from GitHub
remotes::install_github("ThinkR-open/attachment", 
                        upgrade = "never", quiet = TRUE)
# Add 'Remotes' field
set_remotes_to_desc(desc_file)
## Remotes for attachment were added to DESCRIPTION.
# Read the DESCRIPTION file
cat(readLines(desc_file), sep = "\n")
## Imports:
##     attachment,
##     glue
## Suggests:
##     desc
## Remotes:  
##     thinkr-open/attachment

The ‘Remotes’ field was correctly added!

Find remote installations on your computer

If you only want to find if packages were installed from other source than CRAN, without amending DESCRIPTION, you can use find_remotes().

You can use it on a vector of packages names

# install from GitHub
remotes::install_github("ThinkR-open/attachment",
                        upgrade = "never", quiet = TRUE)
find_remotes(pkg = c("attachment", "desc", "glue"))
## $attachment
## [1] "thinkr-open/attachment"
# install from CRAN
remotes::install_cran("attachment", 
                      upgrade = "never", quiet = TRUE)
find_remotes(pkg = c("attachment", "desc", "glue"))
## NULL

You may also want to combine it to att_from_description() or any other att_from_*()

att_from_description() %>%
  find_remotes()
att_from_rscripts(path = "R/") %>%
  find_remotes()
att_from_rmds(path = "vignettes/") %>%
  find_remotes()

Fill a bookdown DESCRIPTION file

You can use a similar approach for a {bookdown} description file using attachment::att_to_desc_from_is().
Indeed, you can use it in your CI to automatically build your HTML pages while parsing dependencies required. Note that to include it directly in CI (as proposed in {gitlabr} templates), you may need to set att_to_desc_from_is(must.exist = FALSE).

# bookdown Imports are in Rmds
imports <- c("bookdown", attachment::att_from_rmds("."))
attachment::att_to_desc_from_is(
  path.d = "DESCRIPTION",
  imports = imports, suggests = NULL, 
  must.exist = FALSE
)

Then, you can install dependencies from the DESCRIPTION file.

remotes::install_local()

Propose content for “Remotes” field in bookdown

An interest of using DESCRIPTION to list your bookdown dependencies is to use packages from other sources than CRAN and list them in the ‘Remotes’ field.
Here comes set_remotes_to_desc(), which adds packages that were installed from other source than CRAN to Remotes: field in DESCRIPTION.

You can run it after att_to_desc_from_is().

attachment::att_to_desc_from_is(
  path.d = "DESCRIPTION",
  imports = imports, suggests = NULL, 
  must.exist = FALSE
) %>%
  set_remotes_to_desc()

To go further

Note that {attachment} is used in {fusen}, a package that reduces package development to a simple Rmarkdown file. Find out more in the dedicated documentation: https://thinkr-open.github.io/fusen/


About the author

Sébastien Rochette

Sébastien Rochette

Expert du langage R – Défenseur du 'Rmd first', joueur de cartographies


Comments


Also read