class: center, middle .fl.w-40.pa2[ <!-- --> ] .f1[Créer son premier] .yellow.f1[package R] .tr[ .f4[Juliette ENGELAERE-LEFEBVRE - Maël THEULIERE] ] --- # Objectif de cette séquence Après cet atelier vous saurez : - comprendre ce qu’est un package - comprendre la structure d’un package - créer votre premier package --- class: inverse, center, middle # Qu'est ce qu'un package ? --- # Qu'est ce qu'un package ? En R, un package est le moyen le plus adapté pour étendre les fonctionnalités de R. Un package est une collection de fonctions, de données, de documentations et de tests. Un package est facilement partageable avec d'autres. Un package est le plus souvent versionné, c'est à dire qu'il peut exister plusieurs versions d'un même package pas forcément compatibles entre elles. --- # Qu'est ce qu'un package ? Un package peut être hébergé sur le CRAN ou sur une forge logiciel comme github ou gitlab. Quand il est sur le cran, la fonction `install.packages()` permet de l'installer. ```r install.packages("mon_package") ``` Quand il est sur une forge, on utilise les fonctions du package `{remotes}` pour les installer. Dans ce cas, il faut lui spécifier la forge et l'adresse relative de ce package. Exemples : ```r remotes::install_github("auteur_du_package/son_package") ``` ```r remotes::install_gitlab("auteur_du_package/son_package") ``` --- class: inverse, center, middle # Structure d'un package --- ### Structure d'un package # La structure minimale d'un package La structure d'un package va différer suivant le contenu de celui-ci. La structure minimale consiste en : .pull-left[ - un fichier `DESCRIPTION` qui contient la description d'un package et ses dépendances, c'est à dire la liste des packages qui seront nécessaires pour faire fonctionner ce package - un répertoire `R/` qui contient les fichiers sources des fonctions du package - un fichier `NAMESPACE` qui contient les fonctions exportées par le package et la liste des fonctions importées d'autres packages. Ce fichier est généré automatiquement - un répertoire `man/` qui contient la documentation des fonctions du package. Son contenu est généré automatiquement ] .pull-right[  ] --- ### Structure d'un package # Le fichier DESCRIPTION .pull-left[ Le fichier `DESCRIPTION` contient : - la description du package (nom, auteur, licence, version...) - la liste des packages qui seront nécessaires pour faire fonctionner ce package (rubrique `Imports`) ] .pull-right[  ] --- ### Structure d'un package # Le répertoire R/ .pull-left[ Le répertoire `R/` contient les fichiers sources des fonctions du package. Conseil pour bien commencer : créer un fichier R pour chaque fonction nommé de la même façon que la fonction. ] .pull-right[  ] --- ### Structure d'un package # Le répertoire R/ .pull-left[ Chaque fichier R contient : - la définition de la fonction en R - le code roxygen qui permettent de construire la documentation et de définir les dépendances de la fonction. Le code roxygen commence toujours par `#'` ] .pull-right[  ] --- ### Structure d'un package # Le fichier NAMESPACE .pull-left[ Le fichier `NAMESPACE` contient : - les fonctions exportées par le package - la liste des fonctions importées d'autres packages utilisées dans notre package Ce fichier est généré automatiquement grâce à Roxygen. ] .pull-right[  ] --- ### Structure d'un package # Le répertoire man .pull-left[ Le répertoire `man/` contient la documentation des fonctions du package. Pour chaque fonction, il contient un fichier `.Rd` qui sera la documentation de la fonction consultable dans l'aide de R. Son contenu est généré automatiquement grâce à Roxygen. ] .pull-right[  ] --- ### Structure d'un package # Le répertoire man .pull-left[ Le répertoire `man/` contient la documentation des fonctions du package. Pour chaque fonction, il contient un fichier `.Rd` qui sera la documentation de la fonction consultable dans l'aide de R. Son contenu est généré automatiquement grâce à Roxygen. ] .pull-right[  ] --- classe: inverse, center, middle # Créer son premier package --- ### Créer son premier package # Vos compagnons pour créer et développer votre package .left-column[  ] .right-column[ 4 packages vous seront indispensables pour développer vos packages : - `{devtools}` recense les fonctions qui seront utilisées pour compiler ou installer votre package. - `{usethis}` contient un ensemble de fonctions qui vous permetront d'automatiser la plupart des tâches dont vous aurez besoin. - `{roxygen2}` vous permettra de documenter vos fonctions (cf atelier 2). - `{pkgdown}` vous permettra de créer un site de documentation de votre package. - `{testthat}` vous permettra de tester vos fonctions. C'est à dire de définir un ensemble d'instructions qui vous permettront de vérifier que vos fonctions produisent bien le résultat attendu (cf atelier 2). Pour installer ces packages : ```r install.packages(c('devtools','usethis','roxygen2','testthat', 'pkgdown')) ``` ] --- ### Créer son premier package # Configurer votre environnement Avant de créer votre premier package, il va falloir réaliser quelques démarches initiales à faire une bonne fois pour toute pour configurer votre poste : configuration du proxy, de git... Suivez le guide à [cette adresse](../configuration.html) pour cela. --- ### Créer son premier package # Mon premier package Vous êtes maintenant prêt à créer votre premier package. Vous allez pouvoir utiliser `{usethis}` pour faciliter ce travail : 1 - création du package sur ma machine ```r usethis::create_package("monpremierpackage") ``` 2 - utilisation de git comme gestionnaire de version Une invite de commande s'affiche dans la console pour savoir si vous voulez réaliser un premier commit, répondez oui. ```r usethis::use_git() ``` --- ### Créer son premier package # Mon premier package 3 - Créer un repo sur github ou gitlab .panelset[ .panel[.panel-name[github] La fonction `use_github()` créer automatiquement le projet distant sur votre compte github. ```r usethis::use_github() ``` ] .panel[.panel-name[gitlab] La fonction `use_git_remote()` créer automatiquement le projet distant sur votre compte gitlab ou autre en spécifiant l'url que vous souhaitez associer à votre projet. ```r usethis::use_git_remote(url = "https://gitlab.com/MON_ESPACE/monpremierpackage.git"") ``` Il faut ensuite la première fois déclarer cela à git par un premier push. Vous pouvez le faire de la console R grace à [`{gert}`](https://docs.ropensci.org/gert/), un package qui permet de lancer des instructions git depuis un script R. ```r gert::git_push(set_upstream = TRUE) ``` ] ] --- ### Créer son premier package # Mon premier package Vous allez pouvoir utiliser `{usethis}` pour faciliter ce travail : 4 - création d'une fichier `dev_history.R` pour tracer nos développements - Création du fichier ```r usethis::edit_file("dev_history.R") ``` - Ajout du fichier dans les fichiers à exclure lors de la compilation du package ```r usethis::use_build_ignore('dev_history.R') ``` 5 - modification de la licence ```r usethis::use_gpl3_license() ``` --- ### Créer son premier package # Mon premier package Vous allez pouvoir utiliser `{usethis}` pour faciliter ce travail : 6 - modification du fichier description Modifier la description de votre package ```r usethis::edit_file('DESCRIPTION') ``` Et voilà, votre premier package est prêt ! Certes, il ne contient pour l'instant RIEN, mais il peut se compiler et s'installer ```r devtools::check() devtools::install() ``` --- class: inverse,center,middle # Et maintenant ? --- # Et maintenant ? Dans l'atelier suivant nous allons voir comment rajouter une fonction dans votre package, la documenter et la tester. Vous verrez à travers cela le workflow type de travail pour développer votre package.