library(devtools)
#> Loading required package: usethis
library(roxygen2)
library(testthat)
#>
#> Attaching package: 'testthat'
#> The following object is masked from 'package:devtools':
#>
#> test_file
devtools::session_info()
#> ─ Session info ───────────────────────────────────────────────────
#> setting value
#> version R version 4.3.0 (2023-04-21)
#> os Ubuntu 22.04.2 LTS
#> system x86_64, linux-gnu
#> ui X11
#> language (EN)
#> collate C.UTF-8
#> ctype C.UTF-8
#> tz UTC
#> date 2023-06-05
#> pandoc 2.9.2.1 @ /usr/bin/ (via rmarkdown)
#>
#> ─ Packages ───────────────────────────────────────────────────────
#> package * version date (UTC) lib source
#> brio 1.1.3 2021-11-30 [1] RSPM
#> cachem 1.0.8 2023-05-01 [1] RSPM
#> callr 3.7.3 2022-11-02 [1] RSPM
#> cli 3.6.1 2023-03-23 [1] RSPM
#> crayon 1.5.2 2022-09-29 [1] RSPM
#> devtools * 2.4.5 2022-10-11 [1] RSPM
#> digest 0.6.31 2022-12-11 [1] RSPM
#> ellipsis 0.3.2 2021-04-29 [1] RSPM
#> evaluate 0.21 2023-05-05 [1] RSPM
#> fastmap 1.1.1 2023-02-24 [1] RSPM
#> fs 1.6.2 2023-04-25 [1] RSPM
#> glue 1.6.2 2022-02-24 [1] RSPM
#> htmltools 0.5.5 2023-03-23 [1] RSPM
#> htmlwidgets 1.6.2 2023-03-17 [1] RSPM
#> httpuv 1.6.11 2023-05-11 [1] RSPM
#> jsonlite 1.8.4 2022-12-06 [1] RSPM
#> knitr 1.43 2023-05-25 [1] RSPM
#> later 1.3.1 2023-05-02 [1] RSPM
#> lifecycle 1.0.3 2022-10-07 [1] RSPM
#> magrittr 2.0.3 2022-03-30 [1] RSPM
#> memoise 2.0.1 2021-11-26 [1] RSPM
#> mime 0.12 2021-09-28 [1] RSPM
#> miniUI 0.1.1.1 2018-05-18 [1] RSPM
#> pkgbuild 1.4.0 2022-11-27 [1] RSPM
#> pkgload 1.3.2 2022-11-16 [1] RSPM
#> prettyunits 1.1.1 2020-01-24 [1] RSPM
#> processx 3.8.1 2023-04-18 [1] RSPM
#> profvis 0.3.8 2023-05-02 [1] RSPM
#> promises 1.2.0.1 2021-02-11 [1] RSPM
#> ps 1.7.5 2023-04-18 [1] RSPM
#> purrr 1.0.1 2023-01-10 [1] RSPM
#> R6 2.5.1 2021-08-19 [1] RSPM
#> Rcpp 1.0.10 2023-01-22 [1] RSPM
#> remotes 2.4.2 2021-11-30 [1] RSPM
#> rlang 1.1.1 2023-04-28 [1] RSPM
#> rmarkdown 2.22 2023-06-01 [1] RSPM
#> roxygen2 * 7.2.3 2022-12-08 [1] RSPM
#> rstudioapi 0.14 2022-08-22 [1] RSPM
#> sessioninfo 1.2.2 2021-12-06 [1] RSPM
#> shiny 1.7.4 2022-12-15 [1] RSPM
#> stringi 1.7.12 2023-01-11 [1] RSPM
#> stringr 1.5.0.9000 2023-04-22 [1] Github (tidyverse/stringr@65b218e)
#> testthat * 3.1.8 2023-05-04 [1] RSPM
#> urlchecker 1.0.1 2021-11-30 [1] RSPM
#> usethis * 2.1.6 2022-05-25 [1] RSPM
#> vctrs 0.6.2 2023-04-19 [1] RSPM
#> xfun 0.39 2023-04-20 [1] RSPM
#> xml2 1.3.4 2023-04-27 [1] RSPM
#> xtable 1.8-4 2019-04-21 [1] RSPM
#>
#> [1] /home/runner/work/_temp/Library
#> [2] /opt/R/4.3.0/lib/R/site-library
#> [3] /opt/R/4.3.0/lib/R/library
#>
#> ──────────────────────────────────────────────────────────────────Preface
Welcome to the 2nd edition of R Packages! If you’re familiar with the 1st edition, this preface describes the major changes so that you can focus your reading on the new areas.
There are several main goals for this edition:
Update to reflect changes in the devtools package, specifically, its “conscious uncoupling” into a set of smaller, more focused packages.
Expand coverage of workflow and process, alongside the presentation of all the important moving parts that make up an R package.
Cover entirely new topics, such as package websites and GitHub Actions.
All content has been completely revised and updated. Many chapters are new or re-organized and a couple have been removed:
New Chapter 2, “The Whole Game”, previews the entire package development process.
New Chapter 3, “System setup”, has been carved out of the previous Introduction and gained more detail.
The chapter formerly known as “Package structure” has been expanded and split into two chapters, one covering package structure and state (Chapter 4) and another on workflows and tooling (Chapter 5).
New Chapter 6, “The package within”, demonstrates how to extract reusable logic out of data analysis scripts and into a package.
The sections “Organising your functions” and “Code style”, from Chapter 7, “R code”, have been removed, in favor of an online style guide, https://style.tidyverse.org/. The style guide is paired with the new styler package (Müller and Walthert 2018) which can automatically apply many of the rules.
The coverage of testing has expanded into three chapters: Chapter 14 for testing basics, Chapter 15 for test suite design, and Chapter 16 for various advanced topics.
Material around the
NAMESPACEfile and dependency relationships has been re-organized into two chapters: Chapter 11 provides technical context for thinking about dependencies and Chapter 12 gives practice instructions for using different types of dependencies in different settings.New Chapter 13, “Licensing”, expands earlier content on licensing into its own chapter.
The chapter on C/C++ has been removed. It didn’t have quite enough information to be useful, and since the first edition of the book, other resources have arisen that are better learning resources.
The “Other components” chapter has been removed.
The chapter on Git/GitHub has been reframed around the more general topic of software development practices (Chapter 21). This no longer includes step-by-step instructions for basic tasks. The use of Git/GitHub has exploded since the first edition, accompanied by an explosion of learning resources, both general and specific to R (e.g. the website Happy Git and GitHub for the useR). Git/GitHub still feature prominently throughout the book, most especially in Chapter 21.
The very short
instchapter has been combined into Chapter 9, with all the other directories that can be important in specific contexts, but that aren’t mission critical to all packages.
Acknowledgments
Since the first edition of R Packages was published, the packages supporting the workflows described here have undergone extensive development. The original trio of devtools, roxygen2, and testthat has expanded to include the packages created by the “conscious uncoupling” of devtools, as described in Section 3.2. Most of these packages originate with Hadley Wickham (HW), because of their devtools roots. There are many other significant contributors, many of whom now serve as maintainers:
- devtools: HW, Winston Chang, Jim Hester (maintainer, >= v1.13.5), Jennifer Bryan (maintainer >= v2.4.3)
- usethis: HW, Jennifer Bryan (maintainer >= v1.5.0), Malcolm Barrett
- roxygen2: HW (maintainer), Peter Danenburg, Manuel Eugster
- testthat: HW (maintainer)
- desc: Gábor Csárdi (maintainer), Kirill Müller, Jim Hester
- pkgbuild: HW, Jim Hester, Gábor Csárdi (maintainer >= v1.2.1)
- pkgload: HW, Jim Hester, Winston Chang, Lionel Henry (maintainer >= v1.2.4)
- rcmdcheck: Gábor Csárdi (maintainer)
- remotes: HW, Jim Hester, Gábor Csárdi (maintainer), Winston Chang, Martin Morgan, Dan Tenenbaum
- revdepcheck: HW, Gábor Csárdi (maintainer)
- sessioninfo: HW, Gábor Csárdi (maintainer), Winston Chang, Robert Flight, Kirill Müller, Jim Hester
This book was written and revised in the open and it is truly a community effort: many people read drafts, fix typos, suggest improvements, and contribute content. Without those contributors, the book wouldn’t be nearly as good as it is, and we are deeply grateful for their help. We are indebted to our colleagues at Posit, especially the tidyverse team, for being perpetually game to discuss package development practices. The book has been greatly improved by the suggestions from our fantastic team of technical reviewers: Malcolm Barrett, Laura DeCicco, Zhian Kamvar, Tom Mock and Maëlle Salmon.
Thanks go to all contributors who submitted improvements via github (in alphabetical order): @aaronwolen, @ablejec, Adam Yormark, @adessy, Adrien Todeschini, Alan Haynes, Alexander Grüneberg, Alison Presmanes Hill, Andrea Cantieni, Andrew Bray, Andrew Craig, Andy Teucher, Andy Visser, @apomatix, Arni Magnusson, Ben Bond-Lamberty, Ben Marwick, Berry Boessenkool, @bm5tev3, Brandon Greenwell, Brett Johnson, Brett K, Brett Klamer, Brian Rice, Brooke Anderson, @btruel, @CAPN, Carl A. B. Pearson, Chao Cheng, Chester Ismay, Choyoung Yim, @chsafouane, @contravariant, Craig Citro, Crt Ahlin, Dan Yavorsky, @danhalligan, Daniel Falbel, Daniel Lee, David Robinson, David Smith, @davidkane9, Dean Attali, @deanbodenhambsse, Douglas K. G. Araujo, @dracodoc, @dryzliang, Earl Brown, Eduardo Ariño de la Rubia, @eipi10, Enrico Spinielli, @eogoodwin, Erik Erhardt, Ewan Dunbar, Federico Marini, Florian Kohrt, Floris Vanderhaeghe, Gerhard Nachtmann, Gerrit-Jan Schutten, Greg Macfarlane, Gustav W Delius, Hadley Wickham, Hannah Frick, @harrismcgehee, Hedderik van Rijn, @helix123, @henningte, Henrik Bengtsson, @heogden, Howard Baek, Hugo Gruson, Ian Gow, @iargent, Iaroslav Domin, Ibrahim Kekec, Ionut Stefan-Birdea, @jacobbien, James Keirstead, James Laird-Smith, Jee Roen, Jennifer (Jenny) Bryan, Jenny Bryan, @Jeremiah, Jim Hester, @jmarshallnz, Jo-Anne Tan, Joanna Zhao, Joe Cainey, Joe Thorley, Johan Larsson, John Baumgartner, John Blischak, @jomuller, Jon Harmon, @Jordan, @jowalski, Justin Alford, Karl Broman, Karthik Ram, @Kasper, @KatherineCox, Katrin Leinweber, Kevin Ushey, Kevin Wright, Kirill Müller, Kristopher Kapphahn, Kun Ren, @kwenzig, @kylelundstedt, @lancelote, Lech Madeyski, @Leon, @lindbrook, Lluis Ramon, Maëlle Salmon, @maiermarco, Malcolm Barrett, Manuel Reif, Mara Averick, Mark Dulhunty, @martin-mfg, Matan Hakim, Matthew Roberts, Mauro Lepore, Michael Boerman, Michael Buckley, @michaelweylandt, Michel Lang, @miguelmorin, @MikeJohnPage, @MikeLeonard, @nareal, Nathan Levett, Nathaniel Phillips, @nattalides, @Nic, Nicholas Tierney, Nick Carchedi, Nick Zeng, @NS, Oliver Keyes, Øystein Sørensen, Pablo Rodríguez-Sánchez, Patrick Kimes, Paul Blischak, Peter Meissner, @PeterDee, Philip Crain, Philip Pallmann, Po Su, @PrzeChoj, R. Mark Sharp, @ramiromagno, Richard M. Smith, Rick Tankard, @rmar073, @rmsharp, Robert Krzyzanowski, Robin Gower, @robiRagan, Ryan Peterson, @ryanatanner, Salim B, Sam Firke, Sascha Holzhauer, @scharne, Scott Rohde, Sean Wilkinson, Sébastien Rochette, Sergey Grechin, @setoyama60jp, Shannon Pileggi, Shantanu Singh, Shaun Walbridge, Shinya Uryu, @SimonPBiggs, Stefan Eng, Stefan Herzog, Stefan Jansson, Stefan Widgren, Stephen Frank, Stephen Rushe, @stevensbr, Tanner Stauss, Telmo Brugnara, Tony Breyal, Tony Fischetti, @TroyVan, @urmils, Vince Knight, Vlad Petyuk, Wenjie Wang, Will Beasley, Winston Chang, @winterschlaefer, Wouter Saelens, @wrathematics, Xiaosong Zhang, Y. Yu, Yihui Xie, @ysdgroot, @yui-knk, Zeki Akyol, @zhaoy, Zhian N. Kamvar, Zhuoer Dong.
Conventions
Throughout this book, we write fun() to refer to functions, var to refer to variables and function arguments, and path/ for paths.
Larger code blocks intermingle input and output. Output is commented so that if you have an electronic version of the book, e.g., https://r-pkgs.org, you can easily copy and paste examples into R. Output comments look like #> to distinguish them from regular comments.
Colophon
This book was authored using Quarto inside RStudio. The website is hosted with Netlify, and automatically updated after every commit by GitHub actions. The complete source is available from GitHub.
This version of the book was built with: