generated from r4ds/bookclub-template
-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Notes for ch 9 Cohort 6 * Fit things onto slides * Remove extra tick in chapter 17. * More chapter 9 tweaks --------- Co-authored-by: Jon Harmon <[email protected]>
- Loading branch information
1 parent
9192c6d
commit cafb249
Showing
4 changed files
with
119 additions
and
136 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,25 +2,29 @@ | |
|
|
||
| # DESCRIPTION | ||
|
|
||
| Note: These slides were written for an old version of this chapter, which incorporated NAMESPACE. The NAMESPACE section should likely be moved to chapter 11 and/or 12. | ||
|
|
||
| **Learning objectives:** | ||
|
|
||
| - Understand the `DESCRIPTION` file and the most important package metadata | ||
| - Understand the `DESCRIPTION` file and the most important package metadata | ||
| - Declare dependencies with `Imports`, `Suggests`, `Depends`, `LinkingTo`, and `Enhances` fields | ||
| - Add title, description, authors | ||
| - Preview license, version | ||
|
|
||
| ## `DESCRIPTION` File | ||
|
|
||
| - Every package has a `DESCRIPTION` and if it has a `DESCRIPTION` file then it is a package | ||
| - `usethis::create_package("mypackage")` adds a `DESCRIPTION` file | ||
| - You can set a custom `DESCRIPTION` file with `usethis.description` | ||
| - Add `Title`, `Description`, `Authors` | ||
| - Preview `License`, `Version` | ||
|
|
||
| ## `DESCRIPTION` File {-} | ||
|
|
||
| - `DESCRIPTION` file stores important metadata about a package. | ||
| - Required pkgs, what pkg does, maintainer contact info, etc | ||
| - Every package has `DESCRIPTION`; anything with `DESCRIPTION` is a package | ||
| - `usethis::create_package("mypackage")` adds `DESCRIPTION` file | ||
| - Set `DESCRIPTION` defaults as named list in `usethis.description` (see [usethis setup](https://usethis.r-lib.org/articles/usethis-setup.html)) | ||
| - `DESCRIPTION` file format = DCF (Debian Control Format) | ||
| - Each line is a field name & value sep by `:` | ||
| - If a value has multiple lines indent following lines 4 spaces. | ||
| - [{desc}](https://desc.r-lib.org/) can help with `DESCRIPTION`s programmatically. | ||
|
|
||
|  | ||
| Example `DESCRIPTION` file: | ||
|
|
||
| ```r | ||
| ## Example `DESCRIPTION` File {-} | ||
|
|
||
| ``` | ||
| Package: mypackage | ||
| Title: What the Package Does (One Line, Title Case) | ||
| Version: 0.0.0.9000 | ||
|
|
@@ -37,31 +41,31 @@ Roxygen: list(markdown = TRUE) | |
| RoxygenNote: 7.2.0 | ||
| ``` | ||
|
|
||
| ## Title and description | ||
| ## Title {-} | ||
|
|
||
| What does your package do? | ||
| `Title` = 1-line description of the package | ||
|
|
||
|  | ||
| - Plain text | ||
| - Title Case | ||
| - Does not end in a period | ||
| - Shows on CRAN download page & `Packages` tab in RStudio | ||
| - Keep it short (ideally < 65 characters) | ||
| - Do not include package name | ||
| - Put the names of R packages, software, and APIs inside 'single quotes' | ||
| - Do not start with "A package for..." or "This package does...". | ||
|
|
||
| ## Description {-} | ||
|
|
||
| ### Title | ||
| `Description` can be up to a paragraph | ||
|
|
||
| - `Title` is a one line description of the package | ||
| - Plain text | ||
| - Capitalized title | ||
| - Does not end in a period | ||
| - Shows up on CRAN download page | ||
| - Do not include package name | ||
| - Put the names of R packages, software, and APIs inside single quotes | ||
| - Do not start with "A package for..." or "This package does...". | ||
|
|
||
| ### Description | ||
| - Each line up to 80 characters | ||
| - Indent subsequent lines with 4 spaces | ||
| - Put the names of R packages, software, and APIs inside 'single quotes' | ||
| - Can use acronyms here | ||
| - If you want more detailed info, add it to `README.md` | ||
|
|
||
| ## Title & Description Example {-} | ||
|
|
||
| - `Description` can be up to a paragraph | ||
| - Each line up to 80 characters | ||
| - Indent subsequent lines with 4 spaces | ||
| - Put the names of R packages, software, and APIs inside single quotes | ||
| - You can use acronyms here | ||
|
|
||
| ``` | ||
| Title: Create Elegant Data Visualisations Using the Grammar of Graphics | ||
| Description: A system for 'declaratively' creating graphics, | ||
|
|
@@ -70,40 +74,44 @@ Description: A system for 'declaratively' creating graphics, | |
| and it takes care of the details. | ||
| ``` | ||
|
|
||
| Shows up on CRAN like so: | ||
| ## On CRAN {-} | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ## Author | ||
|  | ||
|
|
||
| Who are you? | ||
| ## Author: who are you? {-} | ||
|
|
||
| - Use the `Authors@R` field | ||
| - Contains executable R code `utils::person()` | ||
| - Fields are used to generate citation for package | ||
| - Use email that you will have access for a while. | ||
|
|
||
| ``` | ||
| person(given = NULL, family = NULL, middle = NULL, | ||
| email = NULL, role = NULL, comment = NULL, | ||
| first = NULL, last = NULL) | ||
| ``` | ||
|
|
||
| ## Authors@R in Practice {-} | ||
|
|
||
| ``` | ||
| Authors@R: person("Hadley", "Wickham", email = "[email protected]", | ||
| role = c("aut", "cre")) | ||
| role = c("aut", "cre"), comment = c(ORCID = "0000-0001-1234-5678")) | ||
| ``` | ||
|
|
||
| - Name (given, family) | ||
| - Email address | ||
| - Role: | ||
| - `cre`: the current maintainer* | ||
| - `aut`: authors who have made significant contributions* | ||
| - `ctb`: contributors who have made smaller contributions | ||
| - Role: Every packages needs at least one author (aut) and one maintainer (cre) | ||
| - **`cre`: current maintainer** | ||
| - **`aut`: authors who have made significant contributions** | ||
| - `ctb`: made smaller contributions | ||
| - `cph`: copyright holder if someone other than author | ||
| - `fnd`: funder | ||
| - Comment | ||
| - Can use this to add ORCID | ||
| * need at least one | ||
|
|
||
| ## Multiple authors {-} | ||
|
|
||
| List multiple authors with `c()`: | ||
|
|
||
|
|
@@ -114,134 +122,109 @@ Authors@R: c( | |
| person("RStudio", role = c("cph", "fnd"))) | ||
| ``` | ||
|
|
||
| ## License | ||
|
|
||
| If you want to share your package, include a license. | ||
|
|
||
| You can use `usethis::use_*_license()` for configuration. | ||
|
|
||
| More in Chapter 9! -> now chapter 12 TODO see if the note from this session need to stay here or move to chapter 12 | ||
| ## License {-} | ||
|
|
||
| **Notes from session** | ||
| - License field is mandatory | ||
| - If you want to share your package, include a license. | ||
| - You can use `usethis::use_*_license()` for configuration. | ||
| - More in Chapter 12! | ||
|
|
||
| Jon: | ||
| Be sure to check the license of the source package. Fortunately that's the next chapter! You want to make sure it's a permissive license. | ||
| Still give credit to where you found it in your source code, regardless of how permissive the license might be. For example, I use %||% from {rlang} in a bunch of packages, and, if I'm not importing anything else from {rlang}, I just copy/paste the (very simple) definition and note that I copy/pasted it from {rlang}. | ||
| ## `Imports` & `Suggests` {-} | ||
|
|
||
| The thing Collin Berke showed is called re-exporting, and that's different from copy/pasting code. It is completely ok to re-export functions; it still requires the user to have the other package, and it explicitly gives credit to the other package. See usethis::use_pipe() for an example of that. usethis::use_tidy_eval() is another one. | ||
| - `Imports` = packages users need at runtime; will be installed or updated when users install your package | ||
| - `Suggests` = packages needed for dev tasks or optional functionality (not required) | ||
| - Both use comma-separated list of package names (ideally 1 pkg/line, alphabetical) | ||
|
|
||
| Tan: | ||
| re-exporting also avoids some of the permissive licensing issues! | ||
| ## `usethis::use_package()` {-} | ||
|
|
||
| ## Version | ||
| - Can also indicate specific package version (`arrow (>= 14.0.0)`) | ||
| - User will be asked to update (if necessary) when they install your package | ||
| - What min version to indicate requires careful consideration! | ||
|
|
||
| - Determines if dependencies are satisfied | ||
| - Two integers and separated by `.` or `-` (recommended to use `.`) | ||
| - Starts at `0.0.0.9000` | ||
| - Based on Semantic Versioning and by the X.Org versioning schemes | ||
|
|
||
| Equivalent examples: | ||
| ``` | ||
| numeric_version("1.9") == numeric_version("1.9.0") | ||
| ```{r, eval=FALSE} | ||
| # Default is 'Imports' | ||
| usethis::use_package('dplyr', min_version = "1.0.0") | ||
| # Use whatever you have installed as minimum | ||
| usethis::use_package('ggplot2', 'Suggests', min_version = TRUE) | ||
| ``` | ||
|
|
||
| Can update version number by running `usethis::use_version()` or `usethis::use_dev_version()`. | ||
|
|
||
| ## Other fields | ||
|
|
||
| ### `URL` and `BugReports` | ||
| ## `Depends` and `Linking to` {-} | ||
|
|
||
| - The `URL` field is commonly used to advertise the package’s website and to link to a public source repository | ||
| - `BugReports` is the URL where bug reports should be submitted | ||
| - `Depends` = packages your package depends on (BUT you usually want `Imports`, not `Depends, why in Ch10) | ||
| - `Depends` also used to indicate a min version of R itself: `Depends: R (>= 4.0.0)` | ||
| - **Main takeaway:** if you state minimum R version, have a reason & take reasonable measures to test your claim regularly | ||
| - `Linking to` indicates if your packages uses C or C++ code from another package. | ||
| - `Enhances` = packages are 'enhanced' by your package | ||
| - It's sometimes hard to define this so we recommend not to use it. | ||
|
|
||
| `usethis::use_github()` will automatically create these for you; `usethis::use_github_links()` can add them for you. | ||
| ## An R version gotcha {-} | ||
|
|
||
| ### `Encoding` | ||
|
|
||
| - Required if DESCRIPTION does not consist entirely of ASCII character | ||
| - Default is `Encoding: UTF-8` | ||
|
|
||
| ### `Collate` | ||
|
|
||
| - Controls the order in which files are sourced | ||
| - Most common if you're using S4 (a system for object oriented programming) | ||
|
|
||
| ### `LazyData` | ||
|
|
||
| - If true, data is lazy loaded so users don't have to run `data()` | ||
| - `usethis::use_data()` does this for you | ||
|
|
||
| ### `Roxygen*` | ||
|
|
||
| `create_package()` creates fields related to the roxygen package | ||
|
|
||
| ## NAMESPACE file | ||
| - Before April 2018: `.rds` files used `version 2` serialization format | ||
| - Since April 2019: `.rds` files use `version 3` serialization format | ||
| - R < 3.5.0 (before April 2018) can't read `.rds` v3 | ||
| - When `.rds` saved as v3, package depends on R >= 3.5.0 | ||
|
|
||
| ``` | ||
| # Generated by roxygen2 (4.0.2): do not edit by hand | ||
| S3method(as.character,expectation) | ||
| S3method(compare,character) | ||
| export(auto_test) | ||
| export(auto_test_package) | ||
| export(colourise) | ||
| export(context) | ||
| exportClasses(ListReporter) | ||
| exportClasses(MinimalReporter) | ||
| importFrom(methods,setRefClass) | ||
| useDynLib(testthat,duplicate_) | ||
| useDynLib(testthat,reassign_function) | ||
| NB: this package now depends on R (>= 3.5.0) | ||
| WARNING: Added dependency on R >= 3.5.0 because serialized objects in | ||
| serialize/load version 3 cannot be read in older versions of R. | ||
| File(s) containing such objects: | ||
| 'path/to/some_file.rds' | ||
| ``` | ||
|
|
||
| Each line contain a directive. 8 directives exist and can be divided in: | ||
| - If you want to support R < 3.5.0, be careful about `.rds` version | ||
|
|
||
| - exported from this package: | ||
| * `export()`: export function | ||
| * `exportPattern()`: export all functions that match a pattern | ||
| * `exportClasses()`, `exportMethodsFrom()`: S4 classes and methods | ||
| * `S3method()`: S3 methods | ||
| ## Other fields {-} | ||
|
|
||
| - imported from another package: | ||
| * `import()`: import **all** function from a package | ||
| * `importFrom()`: import select functions | ||
| * `importClassesFrom()`, `importMethodsFrom()`: import S4 Classes and methods | ||
|
|
||
|
|
||
| Better not to do it by "hand" but with {roxygen2} : | ||
| - `Version` where pkg is in lifecycle / how it's evolving (Ch21) | ||
| - `LazyData: true` if pkg has data for users (won't need `data()`) | ||
| - `Encoding: UTF-8` by default (most common) | ||
| - `Collate` controls the order in which R files are sourced | ||
| - `VignetteBuilder` lists pkg your pkg needs as a vignette engine (Ch17) | ||
| - `SystemRequirements` dependencies external to R | ||
|
|
||
| - Namespace definitions live next to the function: ie reading the function you know if it is imported or not | ||
|
|
||
| - one tag `@export` : generate the correct dirrective | ||
| ``` | ||
| SystemRequirements: C++17 | ||
| SystemRequirements: GNU make | ||
| SystemRequirements: TensorFlow (https://www.tensorflow.org/ | ||
| ``` | ||
|
|
||
| - {roxygen2} make NAMESPACE tidy: even if you do more than one `@importFrom foo bar` you only get one directive `importFrom(foo, bar)` | ||
| - Don't use `Date` field, will auto-populate on build | ||
|
|
||
| {roxygen2} vignette on how to do it: https://roxygen2.r-lib.org/articles/namespace.html | ||
|
|
||
| ## Final notes | ||
| ## Custom fields {-} | ||
|
|
||
| Full list of what can be in the `DESCRIPTION` file is in the [R extensions manual](https://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file). | ||
| Full list of `DESCRIPTION` options in the [Writing R Extensions](https://rstudio.github.io/r-manuals/r-exts/Creating-R-packages.html#the-description-file). | ||
|
|
||
| You can also created your own but CRAN does have constraints | ||
| You can also created your own, but CRAN has constraints: | ||
|
|
||
| - Don't re-purpose official field names used by R | ||
| - Only English words | ||
| - Use `Config/` prefix or `Note` suffix | ||
| - `create_package()` writes to more fields related to the use of roxygen2 package for documentation (Ch16) | ||
|
|
||
| ``` | ||
| Roxygen: list(markdown = TRUE) | ||
| RoxygenNote: 7.2.1 | ||
| ``` | ||
|
|
||
|
|
||
| ## Meeting Videos | ||
| ## Meeting Videos {-} | ||
|
|
||
| ### Cohort 1 | ||
| ### Cohort 1 {-} | ||
|
|
||
| `r knitr::include_url("https://www.youtube.com/embed/BN0mBuuLKz8")` | ||
|
|
||
| `r knitr::include_url("https://www.youtube.com/embed/C_H1oQZD7m8")` | ||
|
|
||
|
|
||
| ### Cohort 2 | ||
| ### Cohort 2 {-} | ||
|
|
||
| `r knitr::include_url("https://www.youtube.com/embed/--GzGdfhCsI")` | ||
|
|
||
| `r knitr::include_url("https://www.youtube.com/embed/8PU_KT5IpWg")` | ||
|
|
||
|
|
||
| ### Cohort 3 | ||
| ### Cohort 3 {-} | ||
|
|
||
| `r knitr::include_url("https://www.youtube.com/embed/vQSYeGwX9yQ")` | ||
|
|
||
|
|
@@ -259,6 +242,6 @@ You can also created your own but CRAN does have constraints | |
| </details> | ||
|
|
||
|
|
||
| ### Cohort 4 | ||
| ### Cohort 4 {-} | ||
|
|
||
| `r knitr::include_url("https://www.youtube.com/embed/Dohr28WYaX0")` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.