Crear una CLI en Rust con clap y clap_mangen: guía práctica para generar man pages automáticamente
En este artículo explicamos cómo definir una CLI una sola vez con clap derive, ejecutarla en tiempo de ejecución y generar automáticamente páginas man en tiempo de compilación con clap_mangen, todo desde la misma fuente de verdad. Este enfoque evita documentación desactualizada y facilita el empaquetado y la distribución de aplicaciones a medida y software a medida.
Qué es una página man y por qué importa: man viene de manual. En sistemas similares a Unix ejecutar man tema abre la documentación en la terminal. Incluir páginas man con tu CLI aporta ayuda integrada y offline para el usuario, coherencia en la experiencia de uso entre mycli, mycli --help y man mycli, y facilidad de descubrimiento mediante comandos como man -k.
Instalación rápida de dependencias: añade las librerías necesarias al proyecto Rust con comandos como cargo add clap --features derive cargo add clap --build --features derive cargo add clap_mangen --build Este paso actualiza el Cargo.toml para incluir clap en dependencias y en build-dependencies y añade clap_mangen para generar las páginas man durante la compilación.
Por qué es una buena idea: una sola fuente de verdad. Usando derive de clap, los tipos que describen la CLI controlan tanto el parseo en tiempo de ejecución como la generación de documentación. Las páginas man se regeneran al compilar cuando cambias la definición de la CLI, y el resultado es perfecto para empaquetado: puedes distribuir target/man/*.1 o instalarlas en /usr/share/man. Funciona con subcomandos anidados sin configuraciones adicionales.
Definición de la CLI: coloca la definición en src/cli.rs usando clap derive y comparte ese archivo con el binario y con build.rs. En tiempo de ejecución parseas una vez con Cli::parse y haces un dispatch sencillo por match hacia el subcomando elegido. En el build script incluyes el mismo src/cli.rs utilizando include! para que el layout de Command sea idéntico durante la generación de man pages.
Generación recursiva de man pages: clap_mangen puede generar la página man raíz y todas las páginas de subcomandos relacionadas con una sola llamada. En build.rs crea el directorio target/man, obtiene el Command desde Cli as CommandFactory y llama a clap_mangen::generate_to pasando el directorio de salida. El script escribe archivos como mycli.1, mycli-config.1, mycli-config-get.1 y muestra una advertencia cargo indicando dónde se guardaron.
Cómo encaja todo: 1) Tiempo de ejecución en src/main.rs parsea la CLI y ejecuta la lógica de cada subcomando. 2) Tiempo de compilación en build.rs incluye src/cli.rs y llama a clap_mangen para producir documentación en target/man. 3) Beneficios: sin duplicidad entre ayuda y docs, regeneración automática de man pages y facilidades para instalar páginas en sistemas Unix.
Caveats y recomendaciones: build.rs se ejecuta en cada build, así que generación pesada puede ralentizar ciclos iterativos. Para proyectos grandes considera usar un cargo xtask o ejecutar la generación en CI. Algunos hosts de documentación pueden restringir efectos colaterales del build script, así que mantén la generación ligera. Si necesitas nombres o secciones personalizados puedes usar clap_mangen::Man::new(cmd).render y recorrer los subcomandos manualmente.
Prueba local: tras compilar con cargo build lista target/man y visualiza páginas con man -l target/man/mycli.1 o man -l target/man/mycli-config-get.1 para comprobar la salida de subcomandos anidados.
Sobre Q2BSTUDIO: en Q2BSTUDIO somos una empresa de desarrollo de software especializada en crear aplicaciones a medida y software a medida para clientes que necesitan soluciones personalizadas y escalables. Ofrecemos servicios de inteligencia artificial, ia para empresas y desarrollo de agentes IA, junto con ciberseguridad y pentesting, servicios cloud aws y azure, y servicios de inteligencia de negocio y power bi. Si buscas integrar una CLI robusta en una solución empresarial o necesitas una aplicación a medida podemos ayudarte, consulta nuestros servicios de desarrollo en desarrollo de aplicaciones y software multiplataforma y explora nuestras capacidades en inteligencia artificial en servicios de inteligencia artificial.
Palabras clave: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi.
