book

R Packages, 2nd Edition

by Hadley Wickham, Jennifer Bryan

June 2023

Intermediate to advanced

381 pages

9h 2m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Welcome!IntroductionPhilosophyIn This BookWhat’s Not HereConventions Used in This BookColophonO’Reilly Online LearningHow to Contact UsAcknowledgments
Load devtools and FriendsToy Package: regexcitePreview the Finished Productcreate_package()use_git()Write the First Functionuse_r()load_all()Commit strsplit1()check()Edit DESCRIPTIONuse_mit_license()document()NAMESPACE Changescheck() Againinstall()use_testthat()use_package()use_github()use_readme_rmd()The End: check() and install()Review
devtools, usethis, and YouPersonal Startup ConfigurationR Build ToolchainWindowsmacOSLinuxVerify System Prep
Package StatesSource PackageBundled Package.RbuildignoreBinary PackageInstalled PackageIn-Memory PackagePackage Libraries
Create a PackageSurvey the Existing LandscapeName Your PackagePackage CreationWhere Should You create_package()?RStudio ProjectsBenefits of RStudio ProjectsHow to Get an RStudio ProjectWhat Makes an RStudio Project?How to Launch an RStudio ProjectRStudio Project Versus Active usethis ProjectWorking Directory and Filepath DisciplineTest Drive with load_all()Benefits of load_all()Other Ways to Call load_all()check() and R CMD checkWorkflowBackground on R CMD check
Alfa: A Script That WorksBravo: A Better Script That WorksCharlie: A Separate File for Helper FunctionsDelta: A Failed Attempt at Making a PackageEcho: A Working PackageFoxtrot: Build Time Versus Run TimeGolf: Side EffectsConcluding ThoughtsScript Versus PackageFinding the Package WithinPackage Code Is Different
Organize Functions Into FilesFast Feedback via load_all()Code StyleUnderstand When Code Is ExecutedExample: A Path Returned by system.file()Example: Available ColorsExample: Aliasing a FunctionRespect the R LandscapeManage State with withrRestore State with base::on.exit()Isolate Side EffectsWhen You Do Need Side EffectsConstant Health Checks
Exported DataPreserve the Origin Story of Package DataDocumenting DatasetsNon-ASCII Characters in DataInternal DataRaw Data FileFilepathspkg_example() Path HelpersInternal StatePersistent User Data

Other DirectoriesInstalled FilesPackage CitationConfiguration Tools
The DESCRIPTION FileTitle and Description: What Does Your Package Do?Author: Who Are You?URL and BugReportsThe License FieldImports, Suggests, and FriendsMinimum VersionsDepends and LinkingToAn R Version GotchaOther FieldsCustom Fields
When Should You Take a Dependency?Dependencies Are Not EqualPrefer a Holistic, Balanced, and Quantitative ApproachDependency Thoughts Specific to the tidyverseWhether to Import or SuggestNamespaceMotivationThe NAMESPACE FileSearch PathFunction Lookup for User CodeFunction Lookup Inside a PackageAttaching Versus LoadingWhether to Import or Depend
Confusion About ImportsConventions for This ChapterNAMESPACE WorkflowPackage Is Listed in ImportsIn Code Below R/In Test CodeIn Examples and VignettesPackage Is Listed in SuggestsIn Code Below R/In Test CodeIn Examples and VignettesPackage Is Listed in DependsIn Code Below R/ and in Test CodeIn Examples and VignettesPackage Is a Nonstandard DependencyDepending on the Development Version of a PackageConfig/Needs/* FieldExportsWhat to ExportRe-exportingImports and Exports Related to S3
Big PictureCode You WriteKey FilesMore Licenses for CodeLicenses for DataRelicensingCode Given to YouCode You BundleLicense CompatibilityHow to IncludeCode You Use
Why Is Formal Testing Worth the Trouble?Introducing testthatTest Mechanics and WorkflowInitial SetupCreate a TestRun TestsTest OrganizationExpectationsTesting for EqualityTesting ErrorsSnapshot TestsShortcuts for Other Common Patterns
What to TestTest CoverageHigh-Level Principles for TestingSelf-Sufficient TestsSelf-Contained TestsPlan for Test FailureRepetition Is OKRemove Tension Between Interactive and Automated TestingFiles Relevant to TestingHiding in Plain Sight: Files Below R/tests/testthat.Rtestthat Helper Filestestthat Setup FilesFiles Ignored by testthatStoring Test DataWhere to Write Files During Testing
Test FixturesCreate useful_things with a Helper FunctionCreate (and Destroy) a Local useful_thingStore a Concrete useful_thing PersistentlyBuilding Your Own Testing ToolsHelper Defined Inside a TestCustom ExpectationsWhen Testing Gets HardSkipping a TestMockingSecretsSpecial Considerations for CRAN PackagesSkip a TestSpeedReproducibilityFlaky TestsProcess and Filesystem Hygiene
roxygen2 BasicsThe Documentation Workflowroxygen2 Comments, Blocks, and TagsKey Markdown FeaturesTitle, Description, DetailsTitleDescriptionDetailsArgumentsMultiple ArgumentsInheriting ArgumentsReturn ValueExamplesContentsLeave the World as You Found ItErrorsDependencies and Conditional ExecutionIntermixing Examples and TextReusing DocumentationMultiple Functions in One TopicInheriting DocumentationChild DocumentsHelp Topic for the Package
Workflow for Writing a VignetteMetadataAdvice on Writing VignettesDiagramsLinksFilepathsHow Many Vignettes?Scientific PublicationSpecial Considerations for Vignette CodeArticle Instead of VignetteHow Vignettes Are Built and CheckedR CMD build and VignettesR CMD check and Vignettes
READMEREADME.Rmd and README.mdNEWS
Initiate a SiteDeploymentNow What?LogoReference IndexRendered ExamplesLinkingIndex OrganizationVignettes and ArticlesLinkingIndex OrganizationNonVignette ArticlesDevelopment Mode
Git and GitHubStandard PracticeContinuous IntegrationGitHub ActionsR CMD check via GHAOther Uses for GHA
Package EvolutionPackage Version NumberTidyverse Package Version ConventionsBackward Compatibility and Breaking ChangeMajor Versus Minor Versus Patch ReleasePackage Version MechanicsPros and Cons of Breaking ChangeLifecycle Stages and Supporting ToolsLifecycle Stages and BadgesDeprecating a FunctionDeprecating an ArgumentDeprecation HelpersDealing with Change in a DependencySuperseding a Function
Decide the Release TypeInitial CRAN Release: Special ConsiderationsCRAN PoliciesKeeping Up with ChangeDouble R CMD CheckingCRAN Check Flavors and Related ServicesReverse Dependency ChecksRevdeps and Breaking ChangesUpdate Comments for CRANThe Submission ProcessFailure ModesCelebrating Success

Content preview from R Packages, 2nd Edition

Chapter 2. System Setup

To get started, make sure you have the latest version of R (at least 4.2.2, which is the version being used to render this book), then run the following code to get the packages you’ll need:

install.packages(c("devtools", "roxygen2", "testthat", "knitr"))

Make sure you have a recent version of the RStudio integrated development environment (IDE). New versions are released regularly, so we recommend updating often to get access to the latest and greatest features.

Download the current version of RStudio Desktop. Most readers can use the free, open source version of RStudio Desktop.

devtools, usethis, and You

“I am large, I contain multitudes.”

— Walt Whitman, Song of Myself

As mentioned in “Philosophy”, devtools is a “metapackage,” encompassing and exposing functionality maintained in several smaller packages.¹ For example, devtools might provide a wrapper function in order to set user-friendly defaults, introduce helpful interactive behavior, or to combine functionality from multiple subpackages. In some cases it simply re-exports a function from another package to make it easily available when devtools is attached.

What’s our recommended approach to using devtools and its constituent packages? It varies, depending on your intention:

If you are using the functions interactively to help you develop your package, you should think of devtools as the provider of your favorite functions for package development. In this case you should attach devtools with ...