library(devtools)
Loading required package: usethis
library(here)
here() starts at /Users/ericscott/Documents/GitHub/CALS-workshops
ResBazAZ 2023
repo name = package name
Copy https url
library(devtools)
Loading required package: usethis
library(here)
here() starts at /Users/ericscott/Documents/GitHub/CALS-workshops
Get a checklist of what to do to set things up:
git_sitrep()
Git config (global)
⢠Name: 'Eric R. Scott'
⢠Email: 'scottericr@gmail.com'
⢠Global (user-level) gitignore file: '~/.gitignore'
⢠Vaccinated: TRUE
âš Defaulting to 'https' Git protocol
⢠Default Git protocol: 'https'
⢠Default initial branch name: 'main'
GitHub
⢠Default GitHub host: 'https://github.com'
⢠Personal access token for 'https://github.com': '<discovered>'
⢠GitHub user: 'Aariq'
⢠Token scopes: 'gist, repo, user, workflow'
⢠Email(s): 'scottericr@gmail.com (primary)', 'ericscott@ufl.edu', 'ericrscott@email.arizona.edu', 'ericrscott@arizona.edu'
Git repo for current project
⢠Active usethis project: '/Users/ericscott/Documents/GitHub/CALS-workshops'
⢠Default branch: 'main'
⢠Current local branch -> remote tracking branch:
'first-r-package' -> 'origin/first-r-package'
GitHub remote configuration
⢠Type = 'ours'
⢠Host = 'https://github.com'
⢠Config supports a pull request = TRUE
⢠origin = 'cct-datascience/CALS-workshops' (can push)
⢠upstream = <not configured>
⢠Desc = 'origin' is both the source and primary repo.
Read more about the GitHub remote configurations that usethis supports at:
'https://happygitwithr.com/common-remote-setups.html'
Add a global .gitignore
to prevent you from accidentally sharing sensitive files on GitHub:
git_vaccinate()
Introduce yourself to git:
use_git_config(
user.name = "your name",
user.email = "youremail@arizona.com", #email you used to sign up for GitHub account
)
Set a default branch name:
#sets your default branch name to "main"
git_default_branch_configure()
There are some other things to do in git_sitrep()
, but first, letâs make our first commit. Make a commit using the git pane in RStudio. Commit message can be something like âinitial commitâ
#check how we're doing
git_sitrep()
Set up a personal access token (PAT). This is necessary to securely send things between your computer and GitHub.
create_github_token() #takes you to external website. Add description, but keep defaults
Store that token on your computer:
::gitcreds_set()
gitcreds#paste in PAT from GitHub
Double-check that it worked:
git_sitrep()
Now everything should be set (except maybe upstream
) with no âs
Weâll use create_package()
to convert our current project to a package. It takes a path
argument that weâll supply with here::here()
here() #absolute path to current project
create_package(here()) #converts current project to skeleton R package. Overwrites files.
This will open a new RStudio window, so you can close the old one.
Re-load devtools with library(devtools)
.gitignore
- list files you donât want to be on GitHub
.Rbuildignore
- files that you want on GitHub, but that canât be part of your R package
DESCRIPTION
- contains package metadata
<package name>.Rproj
- holds settings for the RStudio Project
NAMESPACE
- read-only file that will be generated once we add some functions
R/
- this is where youâll put R code for your packageâs functions
run use_readme_md()
and edit the README.
You could use use_readme_rmd()
if you want a README that executes some code, like running an example.
Commit (message = âconvert to packageâ) and push
Inspect GitHub repo, notice how README.md is rendered
Notice how files in .gitignore arenât there
New .R file, save as greet.R
Start with super simple:
greet.R
<- function() {
greet cat("Hello!")
}
greet()
Hello!
load_all()
and run greet()
Add argument:
greet.R
<- function(name) {
greet cat("Hello ", name, "!", sep = "")
}
load_all()
and greet("yourname")
greet("Eric")
Hello Eric!
greet()
Error in cat("Hello ", name, "!", sep = ""): argument "name" is missing, with no default
greet()
errors, so letâs add a default
greet.R
<- function(name = "User") {
greet cat("Hello ", name, "!", sep = "")
}
load_all()
and greet()
greet()
Hello User!
check()
Run check()
and address stuff:
Edit author field in DESCRIPTION
run use_mit_license()
document()
then ?greet
@export
mean? When would you not want a function to be exported?check()
againshould pass
Should be able to install the package now, load it with library()
, etc.
Letâs make the output colorful with the cli
package!
greet.R
<- function(name = "User") {
greet cat("Hello ", cli::col_cyan(name), "!\n", sep = "")
}
greet("Eric")
Hello Eric!
Notice the syntaxâpkgname::function()
âthis is essential so that your package knows which package functions are from!
Run check()
and notice the warning:
'::' or ':::' import not declared from: âcliâ
Solution: use_package("cli")
Inspect DESCRIPTION and run check()
again
Read in dataset from URL (paste code into chat I guess?)
use_data()
to add dataset to your package
#read in data as an R object
<- read.csv("https://www.ericrscott.com/files/baked_goods_long.csv")
baked_goods #use_data() on the R object to add to your package
use_data(baked_goods)
Inspect output and see what is changed
lazy data means the dataset is available when you load the package without having to run data(baked_goods)
. Just load your package and baked_goods
is available.
.rda files are for saving R objects
Document the data set. https://r-pkgs.org/data.html#sec-documenting-data
Create a R/data.R
, paste in the example and edit
Never @export
a dataset, theyâre available through lazy loading and this isnât needed.
Run document()
and check ?baked_goods
Run check()
, commit and push
âUnit testsâ check that your code gives desired output, errors when itâs supposed to, etc.
Set up with use_testthat()
Inspect changes
tests/
DESCRIPTION
Add a test for our function with use_test("greet")
Run test with button and with test()
and with check()
Edit test to make sense for greet
test-greet.R
test_that("greet works with names", {
expect_equal(greet("Eric"), "Hello Eric!")
})
test_that("greet works with default", {
expect_equal(greet(), "Hello User!")
})
So youâve got check()
passing on your computer, but will your package work on a different OS? With a different version of R?
How can you find out and be alerted if changes you make will break the package for others?
Continuous Integration (CI) is a practice of automatically building your package (or running an analysis pipeline) on a variety of systems every time you make changes to your code (and push to GitHub)
Weâll use GitHub Actions and usethis
to set this up.
use_github_action_check_release()
sets up a basic action that runs check()
using the latest release of R running on Linux
use_github_action_check_standard()
runs a more intense check of your package on linux, macOs, and Windows using the latest release of R and the development version of R.
Add a badge to your readme with use_github_actions_badge()
Commit, push, and inspect GitHub repo
Add a vignette to your package with use_vignette()
Add a code of conduct to your repo with use_code_of_conduct()
Make a checklist of what you need to do to submit your package to CRAN with use_release_issue()
This may not be strictly necessary until you want to build packages containing C or C++ code. Especially if you are using RStudio, you can set this aside for now. The IDE will alert you and provide support once you try to do something that requires you to setup your development environment
Check if you already have xcode command line tools installed:
xcode-select -p
If you get an error instead of a path like /Library/Developer/CommandLineTools
, then you need to install xcode command line tools with:
xcode-select --install
Install Rtools from https://cran.r-project.org/bin/windows/Rtools/
Do not select the box for âEdit the system PATHâ. devtools and RStudio should put Rtools on the PATH
automatically when it is needed.
Do select the box for âSave version information to registryâ. It should be selected by default.