pkg.qmd

---
title: "Packaging et test"
lang: fr
author: Cédric, Armand, Louis et Baptiste
format: html
toc: true
---

Un package est un projet (`.Rproj`) versionné `usethis::use_git()`. On peut contrôler l'environnement avec `{renv}`.

::: {.callout-warning}
Sur windows il faut installer [RTools](https://cran.r-project.org/bin/windows/Rtools/) (la même version que celle de R).
:::

### Créer un package

``` r
usethis::create_package("~/path/to/mypkg")
```

-   `.Rbuildignore` liste des fichiers ignorés pour le build
-   `.gitignore`
-   `DESCRIPTION` package metadata
-   `NAMESPACE`import et export des fonctions
-   `R` main folder
-   `mypkg.Rproj`

### Versionning

``` r
usethis::use_git()
```

### Écrire des fonctions

``` r
usethis::use_r(name)
```

Les fonctions sont définies dans des fichiers `R/name.R`.

``` r
devtools::load_all()
```

### Dépendances

On doit spécifier les packages qui sont utilisés.

``` r
usethis::use_package('ggplot2')
```

Ils sont ajoutés dans le fichier DESCRIPTION dans la section Import (ou Suggests par exemple).

Pour prévoir la documentation, il est essentiel d'utiliser `roxygen2` (*Code \> Insert Roxygen Skeleton*).

``` txt
#' Add together two numbers
#' 
#' @param x A number.
#' @param y A number.
#' @returns A numeric vector.
#' @examples
#' add(1, 1)
#' add(10, 1)
#' @export
add <- function(x, y) {
  x + y
}
```

-   `@export` permet l'export dans le NAMESPACE
-   `@inherisParams` permet de récupérer la description des paramètres depuis une autre fonction
-   voir [la doc](https://roxygen2.r-lib.org/) pour la suite

Pour contrôler les `@imports` dans le Roxygen Skeleton, on peut utiliser [`{autoimport}`](https://github.com/DanChaltiel/autoimport).

On compile la doc et met a jour les namespaces avec

``` r
devtools::document()
```

### Check

``` r
check()
```

``` txt
── R CMD check results ─────────────────── mypgk 0.0.0.9000 ────
Duration: 8.4s

0 errors ✔ | 0 warnings ✔ | 0 notes ✔
```

Si le *check* est bon, on peut installer le package.

``` r
devtools::install()
```

On peut maintenant charger son package.

``` r
library(mypkg)
```

## Tests

Les tests sont définis dans le dossier `test/testthat`. On y accède avec usethis.

``` r
usethis::use_testthat()

usethis::use_test()

devtools::test()
```

Il faut tester (bonnes pratiques) :

-   les arguments de la fonction (type)
-   le résultat attendu
-   les erreurs
-   ...

**Important : définir un test pour chaque bug observé.** Définir le test avant de corriger le bug. Ensuite on est content quand le test passe (et on est sur de détecter si ce bug est toujours présent).

Pour aller plus loin, on peut faire du *test first*. On défini le test avant d'écrire la fonction.

[Voir la doc](https://r-pkgs.org/testing-basics.html)

### GitHub Actions

Pour optimiser les CI/CD on utilise les github actions (ou gitlab, mais c'est pas le même format).

``` r
usethis::use_github() 
usethis::use_github_action()
usethis::use_pkgdown_github_pages()
```

## Sources

-   [R Packages (2e)](https://r-pkgs.org/)
-   [D'autres tests avant soumission](https://github.com/ThinkR-open/prepare-for-cran)