misc.qmd

# Otros componentes {#sec-misc}

```{r}
#| echo: false
source("common.R")
```

Los dos primeros capítulos de esta parte del libro cubren las dos cosas más obvias que la gente distribuye a través de un paquete R: funciones (@sec-r) y datos (@sec-data).
Pero eso no es todo lo que se necesita para crear un paquete R.
Hay otros componentes del paquete que son necesarios, como un archivo `DESCRIPTION`, o altamente recomendados, como pruebas y documentación.

Las siguientes partes del libro están organizadas en torno a conceptos importantes: dependencias, pruebas y documentación.
Pero antes de profundizar en esos temas, este capítulo desmitifica algunas partes del paquete que no son necesarias en todos los paquetes, pero que es bueno tener en cuenta.

## Otros directorios

A continuación se muestran algunos directorios de nivel superior que puede encontrar en un paquete fuente de R, en orden aproximado de importancia y frecuencia de uso:

-   `src/`: Archivos fuente y de encabezado para código compilado, generalmente C y C++.
    Esta es una técnica importante que se utiliza para hacer que los paquetes de R tengan más rendimiento y desbloquear el poder de las bibliotecas externas para los usuarios de R.
    A partir de la segunda edición, el libro ya no cubre este tema, ya que un tratamiento verdaderamente útil del código compilado requiere más espacio del que podemos darle aquí.
    El tidyverse generalmente utiliza el paquete [cpp11](https://cpp11.r-lib.org) para conectar C++ a R; la mayoría de los otros paquetes usan [Rcpp](https://www.rcpp.org), el paquete mejor establecido para integrar R y C++.

-   `inst/`: para archivos adicionales arbitrarios que desee incluir en su paquete.
    Esto incluye algunos archivos especiales, como `CITATION`, que se describe a continuación en @sec-misc-inst.
    Otros ejemplos de archivos que pueden aparecer debajo de `inst/` incluyen plantillas de R Markdown (consulte `usethis::use_rmarkdown_template()`) o [RStudio add-ins](https://docs.posit.co/ide/user/ide/guide/productivity/add-ins.html).

-   `tools/`: Archivos auxiliares necesarios durante la configuración, que generalmente se encuentran en compañía de un script `configure`.
    Discutimos esto más a continuación en @sec-misc-tools.

-   `demo/`: para demostraciones de paquetes.
    Consideramos las demostraciones como un fenómeno heredado, cuyos objetivos ahora se cumplen mejor con viñetas.
    (@sec-vignettes).
    Para paquetes mantenidos activamente, probablemente tenga sentido reutilizar el contenido de cualquier demostración existente en algún lugar que sea más visible, por ejemplo.
    en `README.Rmd` (@sec-readme) o en viñetas (@sec-vignettes).
    Estas otras ubicaciones ofrecen otras ventajas, como garantizar que el código se ejerza con regularidad.
    Esto no es cierto para las demostraciones reales, lo que las deja vulnerables a la descomposición.

-   `exec/`: para scripts ejecutables.
    A diferencia de los archivos ubicados en otros directorios, los archivos en `exec/` se marcan automáticamente como ejecutables.
    Empíricamente, en la medida en que los paquetes R incluyen scripts para intérpretes externos, el directorio `inst/` parece ser la ubicación preferida en estos días.

-   `po/`: traducciones de mensajes.
    Esto es útil, pero está más allá del alcance de este libro.
    Consulte el capítulo [Internacionalización](https://cran.rstudio.com/doc/manuals/r-devel/R-exts.html#Internationalization) de "Escribir extensiones de R" y el [paquete potools](https://%20michaelchirico.github.io/potools/index.html) para más detalles.

## Archivos instalados {#sec-misc-inst}

Cuando se instala un paquete, todo lo que está en `inst/` se copia en el directorio de nivel superior del paquete instalado (consulte @fig-package-files).
En cierto sentido, `inst/` es lo opuesto a `.Rbuildignore`: donde `.Rbuildignore` le permite eliminar archivos y directorios arbitrarios del paquete compilado, `inst/` le permite agregarlos.

::: callout-warning
Eres libre de poner lo que quieras en `inst/` con una precaución: debido a que `inst/` se copia en el directorio de nivel superior, no crees un subdirectorio que colisione con cualquiera de los directorios que componen la estructura oficial.
de un paquete R.
Recomendamos evitar directorios con significado especial ya sea en la forma fuente o instalada de un paquete, como por ejemplo: `inst/data`, `inst/help`, `inst/html`, `inst/libs`, `inst/man`, `inst/Meta`, `inst/R`, `inst/src`, `inst/tests`, `inst/tools`, and `inst/vignettes`.
En la mayoría de los casos, esto evita que tenga un paquete con formato incorrecto.
Y aunque algunos de los directorios anteriores están técnicamente permitidos, pueden ser una fuente innecesaria de confusión.
:::

Estos son algunos de los archivos y carpetas más comunes que se encuentran en `inst/`:

-   `inst/CITATION`: cómo citar el paquete, consulte a continuación para obtener más detalles.

-   `inst/extdata`: datos externos adicionales para ejemplos y viñetas.
    Consulte la sección @sec-data-extdata para obtener más detalles.

¿Qué sucede si necesita una ruta al archivo en `inst/foo` para usarla, por ejemplo, en el código debajo de `R/` o en su documentación?
La solución predeterminada es utilizar `system.file("foo", package = "tupaquete")`.
Pero esto presenta un dilema en el flujo de trabajo: cuando estás desarrollando tu paquete, interactúas con él en su forma fuente (`inst/foo`), pero tus usuarios interactúan con su forma instalada (`/foo`).
Afortunadamente, devtools proporciona una corrección para `system.file()` que se activa con `load_all()`.
La sección @sec-data-system-file cubre esto con más profundidad e incluye una alternativa interesante, `fs::path_package()` .

### Cita del paquete {#sec-misc-inst-citation}

El archivo `CITATION` vive en el directorio `inst` y está íntimamente conectado a la función `citation()` que le indica cómo citar paquetes R y R.
Llamar a `citation()` sin ningún argumento le indica cómo citar la base R:

```{r}
citation()
```

Llamarlo con un nombre de paquete le indica cómo citar ese paquete:

```{r}
citation("tidyverse")
```

El archivo `inst/CITATION` asociado tiene este aspecto:

```{r}
#| echo: false
#| comment: ""
citation <- readLines(system.file("CITATION", package = "tidyverse"))
cat(citation, sep = "\n")
```

Puede llamar a `usethis::use_citation()` para iniciar este archivo y completar sus datos.
Lea el tema de ayuda `?bibentry` para obtener más detalles.

## Herramientas de configuración {#sec-misc-tools}

Si un paquete tiene un script de configuración (`configure` en sistemas Unix, `configure.win` en Windows), se ejecuta como primer paso mediante `R CMD INSTALL`. Esto generalmente se asocia con un paquete que tiene un subdirectorio `src/` que contiene código C/C++ y el script `configure` es necesario en el momento de la compilación.
Si ese script necesita archivos auxiliares, estos deben ubicarse en el directorio `tools/`.
Los scripts debajo de `tools/` pueden tener un efecto en el paquete instalado, pero el contenido de `tools/` finalmente no estará presente en el paquete instalado.
En cualquier caso, esto es principalmente (pero no exclusivamente) relevante para paquetes con código compilado, lo cual está más allá del alcance de este libro.

Mencionamos esto porque, en la práctica, algunos paquetes usan el directorio `tools/` para un propósito diferente pero relacionado.
Algunos paquetes tienen tareas de mantenimiento periódicas para las cuales resulta útil registrar instrucciones detalladas.
Por ejemplo, muchos paquetes incorporan algún tipo de recurso externo, p. código o datos:

-   Código fuente y encabezados para una biblioteca C/C++ integrada de terceros.

-   Kits de herramientas web.

-   Código R integrado (en lugar de importado).

-   Especificación para una API web.

-   Paletas de colores, estilos y temas.

Estos activos externos también suelen evolucionar con el tiempo, por lo que es necesario reingerirlos periódicamente.
Esto hace que sea particularmente gratificante implementar dicha limpieza de manera programática.

Este es el segundo uso no oficial del directorio `tools/`, caracterizado por dos grandes diferencias con respecto a su propósito oficial: los paquetes que hacen esto generalmente no tienen un script `configure` y enumeran `tools/` en `.Rbuildignore`, lo que significa que estos scripts no están incluidos en el paquete.
Estos scripts se mantienen en el paquete fuente para comodidad del desarrollador, pero nunca se envían con el paquete.

Esta práctica está estrechamente relacionada con nuestra recomendación de almacenar las instrucciones para la creación de datos del paquete en `data-raw/` (sección @sec-data-data-raw) y registrar el método de construcción de cualquier dispositivo de prueba (sección @sec-testing-advanced-concrete-fixture).