NOMBRE

perlnewmod - Preparar la distribución de un módulo nuevo

DESCRIPCIÓN

Este documento ofrece algunas sugerencias para escribir módulos Perl, preparar su distribución y publicarlos en CPAN.

Uno de los factores que hacen que Perl sea una herramienta realmente eficaz es el hecho de que los hackers que usan este lenguaje suelen compartir el código que desarrollan al solucionar problemas para que sus camaradas no tengan que enfrentarse a esos mismos problemas.

La forma principal de compartir código es abstraer la solución en un módulo Perl. Si no sabe lo que es un módulo Perl, este documento no le va a ser de gran ayuda. Además, eso significa que aún no se está beneficiando de una enorme cantidad de código que puede resultarle muy útil; antes de leer este documento debería leer perlmod, perlmodlib y perlmodinstall.

Si no existe ningún módulo para lo que usted necesita, y ya se ha encargado de escribir el código, sería un detalle que empaquetara la solución en un módulo y lo subiera a CPAN para que otros programadores puedan usarlo.

Aviso

Vamos a centrarnos principalmente en módulos de Perl puro, no en módulos XS. Los módulos XS se usan para otros fines y hay que tener en cuenta varias cosas antes de distribuirlos, como la popularidad de la biblioteca para la que se está creando un enlace, la portabilidad a otros sistemas operativos, etc. Sin embargo, las notas sobre cómo preparar la parte Perl del módulo y la forma de empaquetarlo para su distribución se aplican tanto a un módulo XS como a un módulo Perl puro.

¿Qué se debe incluir en un módulo?

En un módulo debe incluir código que crea que puede ser de utilidad para otros programadores. Todo aquello que llene un vacío en la biblioteca común y que alguien pueda usar directamente en sus programas. También son buenos candidatos los fragmentos de código que pueda aislar y extraer para conectarlos a otro componente.

Veamos un ejemplo. Supongamos que ha escrito un programa que lee datos en un formato local y los almacena en un hash de hashes de Perl. Después los convierte en un árbol, recorre el árbol y canaliza cada nodo hacia un servidor Acme Transmogrifier.

Hay muchos usuarios de Acme Transmogrifier y ha tenido que partir de cero para escribir el código de comunicación del protocolo. Con toda seguridad, este código podría ser un buen candidato a módulo. El nivel al que desee afrontar la tarea es cosa suya: puede que desee crear módulos de nivel de protocolo análogos a Net::SMTP para comunicarse con módulos de nivel superior análogos a Mail::Send. La elección es suya, pero lo que está claro es que debe publicar un módulo para ese protocolo de servidor.

Nadie más en el planeta va a comunicarse con su formato de datos local, por lo que podemos ignorar esta parte. Pero, ¿qué pasa con el resto? Crear estructuras de árbol a partir de variables Perl y después recorrerlas es un problema de aplicación general interesante, y si nadie ha creado un módulo que haga eso, es posible que desee convertir también este código en un módulo.

Ya sabe qué partes podría convertir en módulos. Veamos la manera de hacerlo.

Paso a paso: hacer los preparativos

Antes de empezar a preparar el código debe hacer algunas cosas.

Examine código de otros programadores

Analice minuciosamente unos cuantos módulos para ver cómo los han programado. Es recomendable empezar con Text::Tabs (un módulo interesante y sencillo disponible en la biblioteca estándar) y después pasar a algo un poco más complejo, como File::Copy. WWW::Mechanize y los módulos Email::* son buenos ejemplos de código orientado a objetos.

Estos módulos le proporcionarán una idea general de cómo se estructura y desarrolla un módulo.

Asegúrese de que su contribución es novedosa

En CPAN hay muchos módulos, por lo que es fácil pasar por alto alguno similar al que pretende publicar. Investigue a fondo en http://search.cpan.org y asegúrese de que no va a reinventar la rueda.

Evalúe la necesidad

Es posible que su módulo le encante y que crea que a todo el mundo le vendría bien, pero puede ocurrir que a nadie le interese. Si no está seguro de la demanda que puede tener su módulo, puede sondear opiniones en el grupo de noticias comp.lang.perl.modules o, como último recurso, preguntar en la lista sobre módulos, escribiendo a la dirección modules@perl.org. Recuerde que se trata de una lista cerrada con un tiempo de respuesta largo; seguramente tardarán en contestar.

Elija un nombre

Los módulos Perl incluidos en CPAN tienen una jerarquía de nomenclatura; procure respetarla. Encontrará los detalles sobre esta nomenclatura en perlmodlib. Puede examinar CPAN y la lista de módulos para familiarizarse con ella. Como mínimo, debe recordar que las palabras que componen el nombre de un módulo deben escribirse con la letra inicial mayúscula (Este::Programa) y que cada módulo debe pertenecer a una categoría e incluir una descripción de su propósito.

Compruébelo otra vez

Y al hacerlo asegúrese de que no ha pasado por alto ningún módulo similar al que va a escribir.

Cuando se haya decidido por un nombre y esté seguro de que su módulo es necesario y que actualmente no hay nada parecido disponible, puede empezar a programar.

Paso a paso: crear el módulo

Para empezar, use module-starter o h2xs

La utilidad module-starter se distribuye como parte del paquete de CPAN Module::Starter. Crea un directorio con el esqueleto de todos los archivos necesarios para iniciar un nuevo módulo, según las "prácticas recomendadas" actuales para el desarrollo de módulos, y se invoca desde la línea de comandos de la siguiente manera:

module-starter --module=Foo::Bar \
   --author="Su nombre" --email=sunombre@cpan.org

Si no desea instalar el paquete Module::Starter de CPAN, puede usar h2xs, una herramienta más antigua que se creó originalmente para desarrollar módulos XS, y que se incluye en la distribución de Perl.

Una invocación típica de h2xs para crear un módulo Perl puro es:

h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar 

El modificador -A omite el código de Autoloader, -X omite los elementos XS, --skip-exporter omite el código de Exporter, --use-new-tests configura un entorno de pruebas moderno y -n especifica el nombre del módulo.

Use strict y warnings

Debe usar los pragmas warnings y strict en el código de su módulo, ya que no sabe en qué condiciones se va a usar. Además, no querrá distribuir código que no respete los pragmas warnings y strict, ¿no?

Use Carp

El módulo Carp permite presentar los mensajes de error desde la perspectiva del código que llama; esto permite indicar que el problema está en el código que hace la llamada y no en su módulo. Por ejemplo, si escribe:

warn "No se ha especificado un nombre de host";

el usuario verá algo similar a:

No se ha especificado un nombre de host en /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
línea 123.

que parece indicar que su módulo ha producido un error. En lugar de ello, tiene que atribuir la culpa al usuario y decir esto:

No se ha especificado ningún nombre de host en programa_deficiente, línea 10.

Para ello debe usar Carp y reemplazar warn por carp. Asimismo, si el código incluye die, debe usar croak en su lugar. Sin embargo, mantenga las instrucciones warn y die necesarias para realizar comprobaciones (para los casos en que la culpa la tenga realmente su módulo).

Use Exporter con sensatez

Exporter ofrece una manera estándar de exportar símbolos y subrutinas de su módulo al espacio de nombres del autor de la llamada. Por ejemplo, use Net::Acme qw(&frob) importará la subrutina frob.

La variable de paquete @EXPORT determina qué símbolos se exportan cuando en el código que llama solo se usa use Net::Acme. Es muy probable que nunca tenga que colocar nada aquí. Por otra parte, @EXPORT_OK le permite especificar los símbolos que desea exportar. Si desea exportar un conjunto de símbolos, use %EXPORT_TAGS y defina un conjunto de exportación definido. Encontrará más detalles en Exporter.

Use Documentación en texto simple (Plain Old Documentation)

No habrá acabado el trabajo hasta que tenga listo el papeleo. Tiene que dedicar algo de tiempo a escribir la documentación del módulo. module-starter y h2xs proporcionan un esqueleto que puede rellenar; si no conoce el formato POD y desea ver una introducción, consulte perlpod. Debe incluir una sinopsis adecuada que explique cómo se usa el módulo, una descripción, notas sobre la sintaxis y el propósito de las subrutinas o los métodos individuales. Use los comentarios del código Perl como notas de desarrollo y la documentación POD como notas para los usuarios finales.

Escriba pruebas

Le animamos a crear pruebas automáticas del módulo para asegurarse de que funciona de la manera prevista en las distintas plataformas compatibles con Perl; si sube el módulo a CPAN, una legión de comprobadores dedicará tiempo a compilar su módulo y enviarle los resultados de las pruebas. module-starter y h2xs proporcionan un entorno de pruebas que puede ampliar; no debe limitarse a comprobar que el módulo se compila. Test::Simple y Test::More son buenos puntos de partida para escribir una batería de pruebas.

Escriba el archivo README (LÉAME)

Si va a subir el módulo a CPAN, los enanitos automatizados extraerán el archivo README y lo colocarán en su directorio de CPAN. También aparecerá en los directorios principales by-module (por módulo) y by-category (por categoría) si registra el módulo en la lista de módulos. Es recomendable incluir en el README una descripción detallada de lo que hace el módulo, así como los cambios visibles para el usuario con respecto a la versión anterior.

Paso a paso: distribuir el módulo

Obtenga un identificador de usuario de CPAN

Para poder publicar módulos en CPAN, un programador necesita un identificador de CPAN. Visite http://pause.perl.org/, seleccione "Request PAUSE Account" (Solicitar cuenta de PAUSE) y espere a que los administradores de PAUSE aprueben su solicitud.

perl Makefile.PL; make test; make dist

Una vez más, module-starter (o h2xs) se encarga de todo. Crea el archivo Makefile.PL estándar que se usa para instalar los módulos descargados, y que produce un archivo Makefile con un destino dist.

Cuando se haya asegurado de que el módulo supera todas las pruebas (algo que siempre es recomendable), puede ejecutar make dist para que Makefile produzca un paquete tar del módulo, listo para enviarlo a CPAN.

Suba el paquete tar

En el mensaje de correo electrónico que recibió con el identificador de CPAN se incluyen instrucciones sobre cómo iniciar sesión en PAUSE (Perl Authors Upload Server, el servidor de carga para autores de módulos Perl). Puede usar los menús de PAUSE para subir el módulo a CPAN.

Anuncie el módulo en la lista de módulos

Una vez subido, el módulo se alojará en su directorio de autor sin hacer ruido. Si desea conectarlo con el resto de CPAN, tendrá que registrar el espacio de nombres a través de "Register Namespace" en PAUSE. Una vez registrado, el módulo figurará en las listas by-module y by-category de CPAN.

Anuncie el módulo en clpa

Si está impaciente por dar a conocer su módulo, publique un anuncio en el grupo de noticias moderado comp.lang.perl.announce.

Corrija los errores

Cuando empiece a acumular usuarios, también empezará a recibir informes de error. Con suerte, hasta le enviarán parches. Así probará las mieles del mantenimiento de un proyecto de software...

AUTOR

Simon Cozens, simon@cpan.org

Actualizado por Kirrily "Skud" Robert, skud@cpan.org

VEA TAMBIÉN

perlmod, perlmodlib, perlmodinstall, h2xs, strict, Carp, Exporter, perlpod, Test::Simple, Test::More ExtUtils::MakeMaker, Module::Build, Module::Starter, http://www.cpan.org/ , y el tutorial de Ken Williams sobre cómo crear su propio módulo en http://mathforum.org/~ken/perl_modules.html

TRADUCTORES

• Joaquín Ferrero (Tech Lead)

• Enrique Nell (Language Lead)