usethis
usethis 是一个工作流程包:它自动化了在项目设置和开发过程中出现的重复性任务,适用于 R 包和非包项目。
安装
从 CRAN 安装 usethis 的发布版本:
install.packages("usethis")
或者从 GitHub 安装开发版本:
# install.packages("pak")
pak::pak("r-lib/usethis")
使用
大多数 use_*()
函数在活动项目上操作:实际上就是你计算机上的一个目录。如果你刚刚使用 usethis 创建了一个新的包或项目,那就是活动项目。否则,usethis 会验证当前工作目录是否为有效的项目目录或其子目录,然后将其设为活动项目。使用 proj_get()
或 proj_sitrep()
手动查询项目,并在文档中阅读更多内容。
少数 usethis 函数与项目没有强关联,它们会要求你提供路径。
usethis 非常健谈,会解释它正在做什么并为你分配任务。✔
表示 usethis 已经为你完成的事项。☐
表示你需要自己完成一些工作。
以下是 usethis 如何帮助设置包的快速概览。但请记住,许多 usethis 函数也适用于非包的分析项目。
library(usethis)
# 创建新包 -------------------------------------------------
path <- file.path(tempdir(), "mypkg")
create_package(path)
#> ✔ 创建 '/tmp/RtmpCJHMlj/mypkg/'。
#> ✔ 将活动项目设置为 "/private/tmp/RtmpCJHMlj/mypkg"。
#> ✔ 创建 'R/'。
#> ✔ 写入 'DESCRIPTION'。
#> Package: mypkg
#> Title: 包的功能(一行,标题大小写)
#> Version: 0.0.0.9000
#> Authors@R (parsed):
#> * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
#> Description: 包的功能(一段话)。
#> License: 使用 `use_mit_license()`、`use_gpl3_license()` 或其他函数选择许可证
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.3.2
#> ✔ 写入 'NAMESPACE'。
#> ✔ 将活动项目设置为 "<无活动项目>"。
# 仅在此会话不是交互式时需要
proj_activate(path)
#> ✔ 将活动项目设置为 "/private/tmp/RtmpCJHMlj/mypkg"。
#> ✔ 将工作目录更改为 '/tmp/RtmpCJHMlj/mypkg/'
# 修改描述文件 ----------------------------------------------
use_mit_license("My Name")
#> ✔ 将 "MIT + file LICENSE" 添加到 'License' 中。
#> ✔ 写入 'LICENSE'。
#> ✔ 写入 'LICENSE.md'。
#> ✔ 将 "^LICENSE\\.md$" 添加到 '.Rbuildignore'。
use_package("ggplot2", "Suggests")
#> ✔ 将 ggplot2 添加到 DESCRIPTION 的 'Suggests' 字段。
#> ☐ 使用 `requireNamespace("ggplot2", quietly = TRUE)` 测试是否安装了 ggplot2。
#> ☐ 然后直接使用 `ggplot2::fun()` 引用函数。
# 设置其他文件 -------------------------------------------------
use_readme_md()
#> ✔ 写入 'README.md'。
#> ☐ 更新 'README.md' 以包含安装说明。
use_news_md()
#> ✔ 写入 'NEWS.md'。
use_test("my-test")
#> ✔ 将 testthat 添加到 DESCRIPTION 的 'Suggests' 字段。
#> ✔ 将 "3" 添加到 'Config/testthat/edition'。
#> ✔ 创建 'tests/testthat/'。
#> ✔ 写入 'tests/testthat.R'。
#> ✔ 写入 'tests/testthat/test-my-test.R'。
#> ☐ 编辑 'tests/testthat/test-my-test.R'。
x <- 1
y <- 2
use_data(x, y)
#> ✔ 将 R 添加到 DESCRIPTION 的 'Depends' 字段。
#> ✔ 创建 'data/'。
#> ✔ 在 'DESCRIPTION' 中将 'LazyData' 设置为 "true"。
#> ✔ 将 "x" 和 "y" 保存到 "data/x.rda" 和 "data/y.rda"。
#> ☐ 为你的数据编写文档(参见 <https://r-pkgs.org/data.html>)。
# 使用 git ------------------------------------------------------------
use_git()
#> ✔ 初始化 Git 仓库。
#> ✔ 将 ".Rproj.user"、".Rhistory"、".Rdata"、".httr-oauth"、".DS_Store" 和
#> ".quarto" 添加到 '.gitignore'。
行为准则
请注意,usethis 项目发布时附带贡献者行为准则。通过为该项目做出贡献,你同意遵守其条款。