Resumen/xpm — gestor de paquetes

xpm — Uso

Referencia de uso completa del binario xpm, basada en crates/xpm/src/cli.rs, crates/xpm/src/main.rs y el README del proyecto.

Flags globales

Estas flags las acepta cualquier subcomando.

La CLI está definida con clap y exige un subcomando (arg_required_else_help = true).

Comandos

sync — Sincronizar bases de datos de paquetes

Alias: Sy. Descarga los archivos de base de datos .db (y .files best-effort) más recientes de cada repositorio configurado y los parsea en bases de datos de sync locales.

xpm sync [OPTIONS]
xpm Sy [OPTIONS]

Nota de implementación: cmd_sync en main.rs lanza workers de sync por repositorio en chunks paralelos, prueba cada mirror configurado con reintentos, informa qué mirror respondió y luego parsea los .db / .files descargados para poder mostrar el recuento local de paquetes. Los fallos de sync remoto se avisan sin abortar toda la ejecución.

install — Instalar paquetes

Alias: S. Instala uno o más paquetes por nombre desde las bases de datos sincronizadas.

xpm install <PACKAGES>... [OPTIONS]
xpm S <PACKAGES>... [OPTIONS]

Comportamiento (de main.rs): se cargan todas las bases sincronizadas configuradas y los requisitos pedidos (nombre o nombre=versión) se resuelven con el solver SAT, que elige candidatos, respeta depends/conflicts y los provides sin versión, y devuelve el cierre en orden de dependencias. Cada paquete se descarga al directorio de caché, se comprueba contra un .sig remoto según el sig_level efectivo y contra el sha256sum cuando la entrada lo incluye, y luego se commitea como operaciones de instalación sobre un Transaction (los pedidos quedan explícitos; las dependencias arrastradas, como deps; --as-deps/--as-explicit lo sobrescriben). Con --download-only la ejecución se detiene tras descargar. En caso contrario xpm pide confirmación (salvo --no-confirm) y la transacción extrae los archivos y registra cada paquete en la base de datos local.

remove — Eliminar paquetes

Alias: R. Elimina paquetes instalados usando el manifest de archivos registrado en la base de datos local.

xpm remove <PACKAGES>... [OPTIONS]
xpm R <PACKAGES>... [OPTIONS]

El paquete debe estar registrado en la base de datos local (si no, xpm informa de que no está instalado). Se pide confirmación salvo --no-confirm.

upgrade — Actualización del sistema

Alias: Su. Actualiza todos los paquetes instalados a las versiones más recientes disponibles.

xpm upgrade [OPTIONS]
xpm Su [OPTIONS]

upgrade refresca siempre primero las bases de datos (equivalente a pacman -Syu) y luego resuelve el cierre transitivo de los paquetes con versión más nueva, de modo que las dependencias nuevas o que ahora se requieren se instalan en la misma pasada. Los paquetes actualizados conservan su razón de instalación; las dependencias arrastradas se registran como deps. Sin paquetes instalados informa de que no hay nada que hacer.

history — Journal de transacciones

Muestra las transacciones registradas, de la más reciente a la más antigua. Cada install, remove y upgrade escribe una entrada JSON en <db_path>/journal/<epoch>-<pid>.json (por defecto /var/lib/xpm/journal/) antes de tocar el sistema de ficheros, y la finaliza como ok/failed tras el commit.

xpm history [OPTIONS]

xpm history                # Resumen humano (timestamps ISO-8601)
xpm history --json         # Una línea JSON por transacción

Las transacciones que quedan en estado running tras un crash permanecen en el journal como evidencia; la recuperación completa sigue siendo x gen rollback (capa de generaciones), no un comando de xpm.

Alrededor de cada transacción, xpm ejecuta los ejecutables de /usr/lib/xpm/hooks/pre-transaction.d/ y post-transaction.d/ en orden léxico (la raíz se anula con XPM_HOOKS_DIR). El contrato es un conjunto de variables de entorno:

Un fallo en un hook pre aborta la transacción (sin cambios); un fallo en un hook post solo registra un aviso. El runner lo aporta xpm; los scripts de hook los aportará x-scripts cuando xpm sea el gestor activo.

query — Consultar la base de datos local

Alias: Q. Lista los paquetes instalados desde la base de datos local.

xpm query [FILTER] [OPTIONS]
xpm Q [FILTER] [OPTIONS]

Nota de implementación: implementado. query lee la base de datos local (y las entradas remotas sincronizadas para --upgrades); --format tsv imprime name<TAB>version para scripts. Los filtros --explicit/--deps usan la razón de instalación guardada por paquete (<db_path>/local/<pkg>/reason); los paquetes sin fichero reason, o instalados antes de la función, cuentan como explicit. --explicit y --deps juntos son un error. --orphans sigue fallando con un mensaje claro porque la base de datos local aún no registra el grafo inverso de dependencias.

search — Buscar paquetes

Alias: Ss. Busca paquetes por nombre, descripción o provides.

xpm search <QUERY> [OPTIONS]
xpm Ss <QUERY> [OPTIONS]

Nota de implementación: implementado — busca por nombre, descripción y provides en las bases sync o local.

info — Información de paquete

Alias: Si. Muestra información detallada de un paquete.

xpm info <PACKAGE> [OPTIONS]
xpm Si <PACKAGE> [OPTIONS]

Nota de implementación: implementado. Muestra nombre, versión, razón de instalación y repositorio de origen; cuando la base de datos de sync está disponible añade la descripción y las dependencias del repositorio (gana el repositorio de mayor prioridad). Para paquetes no instalados se muestra solo la entrada de sync. Las instalaciones heredadas sin ficheros reason/origin usan explicit/unknown por defecto en vez de fallar.

files — Listar archivos de un paquete

Alias: Ql. Lista todos los archivos que pertenecen a un paquete instalado.

xpm files <PACKAGE>
xpm Ql <PACKAGE>

Nota de implementación: implementado. Lee <db_path>/local/<pkg>/files, un manifest compatible con pacman (cabecera %FILES%, rutas relativas, directorios con / final) derivado del .MTREE del paquete; es el mismo manifest que consume x gen restore --pkg.

repo — Gestión de repositorios

Gestiona los repositorios añadidos por el usuario (temporales). Los predefinidos vienen de /etc/xpm.conf; los añadidos por el usuario se guardan como archivos TOML bajo /etc/xpm.d/.

xpm repo list                 # repositorios predefinidos + añadidos por el usuario
xpm repo add <NAME> <URL>     # añade un repositorio temporal
xpm repo remove <NAME>        # elimina un repositorio añadido por el usuario

Ejemplos (del help integrado):

xpm repo add chaotic-aur https://cdn-mirror.chaotic.cx/$repo/$arch
xpm repo add my-repo https://username.github.io/my-repo/$arch
xpm repo add local file:///srv/packages/$arch

repo add se niega a sobrescribir una entrada existente del mismo nombre. Tras añadir un repositorio, ejecuta xpm sync para traer su base de datos.

usage — Ayuda integrada

Muestra ayuda de uso detallada para toda la herramienta o para un tema/comando.

xpm usage                    # visión general
xpm usage commands           # lista todos los comandos
xpm usage config             # formato del archivo de configuración
xpm usage repos              # gestión de repositorios
xpm usage <command>          # ayuda de un comando concreto (sync, install, remove, upgrade, ...)

xpm <command> --help también funciona vía clap.

Aliases estilo pacman

Flujo de trabajo típico

xpm sync                       # refresca las bases de datos de paquetes
xpm install <package>          # instala un paquete
xpm upgrade                    # actualiza los paquetes instalados (hace sync primero)
xpm history                    # inspecciona las transacciones registradas
xpm query                      # lista los paquetes instalados
xpm remove <package>           # elimina un paquete

El uso no interactivo (scripts) necesita --no-confirm. Para experimentos aislados/sin root usa --config, --root, --dbpath y --cachedir apuntando a directorios temporales; cuando la raíz de instalación no es /, xpm activa la integración de shell y crea shims de comandos en ~/.local/bin (con líneas de export de PATH en ~/.bashrc y ~/.zshrc).

Variables de entorno y códigos de salida

RUST_LOG se respeta a través del EnvFilter de tracing-subscriber para controlar la verbosidad de los logs. docs/CLI.md documenta además XPM_CONFIG, XPM_CACHE_DIR, XPM_HOOKS_DIR (anula la raíz de los hooks de transacción, por defecto /usr/lib/xpm/hooks) y NO_COLOR.

docs/CLI.md documenta una matriz de códigos de salida (0 éxito, 1 error general, 2 error de uso, hasta 7 base de datos bloqueada). Nota: esa matriz es intención documentada más que un contrato impuesto en el código actual; en la práctica clap reporta errores de uso, anyhow reporta fallos en runtime y el resto de códigos documentados aún no los emite main.rs. Verifícalo contra el código antes de depender de un código concreto.

Referencias

• Referencia CLI existente: ../CLI.md
• Objetivos de fetch y layout de mirrors: ../FETCH_TARGETS.md
• Guía rápida de install/upgrade: ../INSTALL_AND_UPGRADE.md
• Configuración de ejemplo: ../../etc/xpm.conf.example
• Definición de comandos: ../../crates/xpm/src/cli.rs, despacho: ../../crates/xpm/src/main.rs

Editar esta página en GitHub