---
title: "bigbang en español: guía completa"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{bigbang en español: guía completa}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## Qué hace bigbang

`bigbang` crea un metapaquete a partir de archivos locales `.tar.gz`, `.tar` o
`.zip`. Está pensado para equipos que distribuyen paquetes internos sin depender de
un repositorio en línea. La generación nunca instala componentes ni borra contenido
del directorio de trabajo.

La API pública usa nombres en inglés para ser consistente con el ecosistema de R:

- `create_metapackage()` crea la fuente del metapaquete.
- `install_local_pkg()` instala un archivo local y sus dependencias.
- `diagnose_dependencies()` busca dependencias implícitas.
- `scan_bigbang_artifact()` examina artefactos históricos sin cargarlos.

## Crear un metapaquete

Los nombres de `packages` incluyen la versión pero no la extensión:

```{r, eval = FALSE}
resultado <- create_metapackage(
  name = "equipoverse",
  packages = c("datos_1.2.0", "reportes_0.9.1"),
  pkg_dir = "ruta/a/instalables",
  ext = ".tar.gz",
  dest_dir = tempdir(),
  document = TRUE
)
resultado
```

El destino debe ser nuevo o estar vacío. Esta restricción evita conservar hooks o
scripts generados por versiones antiguas vulnerables. Nunca regenere in-place una
fuente cuya procedencia no haya sido verificada.

## Instalar y adjuntar componentes

La instalación es explícita. `library(equipoverse)` solo adjunta los componentes ya
instalados e informa cuáles faltan. Para instalar desde los archivos locales:

```{r, eval = FALSE}
library(equipoverse)
equipoverse_install()
```

El metapaquete generado lleva adentro los archivos de sus componentes, así que la
llamada no necesita argumentos. Eso también significa que para entregarlo a otra
persona alcanza con el `equipoverse_0.1.0.tar.gz` construido: lo instala y llama a
`equipoverse_install()`, sin la carpeta de archivos al lado y sin acordar ninguna
ruta de antemano. El valor predeterminado de `pkg_dir` es
`system.file("archives", package = "equipoverse")`, que se resuelve al ejecutar el
instalador y por eso apunta a la biblioteca donde quedó instalado.

Genere con `include_archives = FALSE` cuando los archivos deban permanecer en una
ubicación a la que todos los destinatarios ya tengan acceso; en ese caso
`equipoverse_install()` va a pedir un `pkg_dir` explícito.

La política predeterminada `cran_deps = "skip"` no accede a la red. Las alternativas
son `"error"` (falla sin red) e `"install"` (intenta instalar desde `repos`). Los
paquetes locales se instalan una sola vez en orden topológico; los ciclos producen
una condición `bigbang_error_cycle`.

`upgrade = "newer"` instala solo archivos más nuevos; `"always"` reinstala y
`"never"` conserva cualquier versión instalada. `force = TRUE` equivale a
`"always"`. Los metapaquetes generados ofrecen `<meta>_conflicts()` y respetan
`options(<meta>.quiet = TRUE)`. Si `cli` no está disponible, el mensaje de
arranque vuelve al banner ASCII sin fallar.

## Colisiones de reexportación

Cuando varios componentes exportan el mismo símbolo, indique
`reexport_prefer = c(símbolo = "componente")` para elegir el proveedor o
`reexport_exclude = "símbolo"` para excluirlo. Toda colisión requiere una de
esas decisiones porque el análisis estático no puede probar que dos objetos
exportados sean el mismo en tiempo de ejecución. El diagnóstico etiqueta las
colisiones como `probable_same_object`, `distinct_definitions` o `undetermined`;
una colisión probable elegida se verifica contra los dueños instalados mediante
`<meta>_install()` y `<meta>_conflicts()`.
`<meta>_conflicts()` conserva los conflictos de enmascaramiento. En un
metapaquete generado con `reexport = TRUE`, consulte la verificación de
instalación con `<meta>_reexport_verification(<meta>_conflicts())`.

## Actualizaciones interrumpidas y recuperación

Una actualización con `update = TRUE` interrumpida deja un diario durable junto
al proyecto. La actualización siguiente lo revisa antes de escribir y
`dry_run = TRUE` muestra la acción pendiente. Después de confirmar que no sigue
corriendo otra actualización, usá `recover = TRUE` para preservar bytes de
usuario desconocidos y completar la recuperación.

## Archivos ZIP

Un ZIP que contiene `Meta/package.rds` se considera un binario de Windows y solo se
instala en Windows con `type = "win.binary"`. Los demás ZIP con DESCRIPTION se
extraen en un directorio temporal propio y se instalan como fuente.

## Revisar artefactos anteriores

El escáner nunca carga el paquete y funciona en fuentes, tarballs, ZIP e
instalaciones:

```{r, eval = FALSE}
scan_bigbang_artifact("ruta/al/artefacto", dry_run = TRUE)
```

Si detecta firmas V1/V2/V3/V7, no ejecute `library()`, `devtools::document()` ni
hooks del artefacto. Genere una versión nueva en una ruta vacía con la versión actual
de `bigbang`, vuelva a escanearla y recién entonces constrúyala e instálela.

## Más allá del caso simple

Los ejemplos usan la entrada más simple: stems resueltos en un directorio. No es
un requisito. Cualquier elemento de `packages` que sea un archivo existente se usa
como ruta, así que los componentes pueden venir de varios directorios en una misma
llamada, mezclar `.tar.gz`, `.tar` y `.zip`, y no llevar la versión en el nombre
—la identidad y la versión salen del `DESCRIPTION` de cada archivo—. Un componente
también puede ser un directorio fuente, que se empaqueta con el paquete opcional
`pkgbuild`, o la lista entera puede vivir en un manifiesto bajo control de
versiones.

Dos opciones que conviene conocer antes de generar algo en serio:

```r
plan <- create_metapackage(..., dry_run = TRUE)
plan$order      # el orden de instalación que se usaría
plan$findings   # todos los hallazgos de validación, sin escribir nada
```

`dry_run = TRUE` no crea el destino. Y `update = TRUE` regenera un proyecto
existente en el mismo lugar, reescribiendo solo los archivos que bigbang escribió
—se niega si alguno fue modificado a mano, y nunca toca lo que no escribió—.

Vea `?create_metapackage` para el conjunto completo, incluido
`on_component_error` para generar a partir de un conjunto parcialmente roto,
`tolerate` para relajar de a una las verificaciones de prolijidad, e
`install_upgrade` para fijar la política de actualización del instalador emitido.

## Idioma

Los mensajes de ejecución tienen inglés como fuente y traducción completa al
español mediante gettext. En R 4.2 o posterior puede usar
`Sys.setLanguage("es")`; en versiones anteriores, defina `LANGUAGE=es` antes de
iniciar R. La ayuda Rd queda en inglés porque R no tiene un mecanismo nativo
estable para traducirla. Cuando
`rhelpi18n` madure y llegue a CRAN se evaluará publicar un módulo separado
`bigbang.es` para traducir también la ayuda interactiva.