Notas sobre los portes de OpenBSD

En este documento se describe cómo crear o cómo actualizar un porte. Es una lista útil para recordar qué cosas se deben hacer. No es exacta ni perfecta. Cualquier comentario o pregunta al respecto debe dirigirse a <ports@openbsd.org>.

1. Si quiere ser un mantenedor, subscríbase a la lista ports@openbsd.org.
   • Aquí tienen lugar todas las dicusiones sobre los portes.
   • La lectura de esta lista es importante, ya que muchos anuncios van a esta lista.
   • Ahí encontrará a muchos mantenedores de portes. A menudo pueden darle buenos consejos o probar su porte.
   
   
2. Ser el mantenedor de un porte es algo más que limitarse a entregar portes al árbol de CVS. También hay que mantenerlos actualizados, y contestar dudas sobre éstos.
   
   
3. Obtenga una copia del árbol de portes del cvs. Puede encontrar las instrucciones sobre cómo hacerlo en la página de CVS anónimo.
   
   
4. Escoja una ubicación en donde poner su porte, y cree una infraestructura básica ahí. Use la plantilla de Makefile que encontrará en /usr/ports/infrastructure/templates/Makefile.template. NEED_VERSION está obsoleto y no debe usarse en los nuevos portes. Los mantenedores de portes deberían actualizar su árbol de portes, incluido bsd.port.mk.
   • Cree el directorio pkg.
   • Cree los ficheros vacíos pkg/DESCR y pkg/PLIST.
   
   
5. Añada las porciones con "fetch" del fichero Makefile.
   • Rellene EXTRACT_SUFX si es algo a parte de un .tar.gz. Otros ejemplos pueden ser .tar.Z o .tgz.
   • Rellene DISTNAME, que es el nombre del fichero menos el sufijo de la extensión. Por ejemplo, si tuviera foo-1.0.tar.gz, DISTNAME sería foo-1.0.
   • Rellene MASTER_SITES, que es una URL para los directorios en donde el fichero distfile está ubicado. Por ejemplo, ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/ . No olvide la barra final. Como mínimo, intente tener tres sitios diferentes. Ponga el de más fácil acceso primero, ya que los recorrerá por orden.
   • Recuerde que fetch hace referencia al fichero como ${MASTER_SITES}${DISTNAME}$EXTRACT_SUFX}. Se usarán las tres. No configure DISTNAME para que apunte al fichero directamente.
   • Puede comprobar si ha rellenado estos valores correctamente, escribiendo make fetch-all.

   Existen opciones y herramientas disponibles para portes más complejos:

   • También puede disponer de la variable PATCHFILES. Ésta es una lista de parches de distribuidores (no de OpenBSD) para el porte. Generalmente son soluciones de fiabilidad, de seguridad, o algo parecido.
   • Si sus portes están disponibles en réplicas públicas grandes como GNU, SunSite, o CPAN, disponemos de una lista de sitios en /usr/ports/infrastructure/templates/network.conf.template para su uso. Configure MASTER_SITES como ${MASTER_SITE_GNU}. o ${MASTER_SITE_SUNSITE}, etc. Para simplificar este proceso, utilice la composición ${MASTER_SITE_FOO:=subdir/} para añadir el subdirectorio de distribución.
   • Generalmente los portes corresponden a versiones específicas de software. Una vez que se han obtenido, se hace una suma de comprobación sobre los ficheros y se compara(n) a la(s) suma(s) de comprobación grabada(s) en distinfo. Así pues, para evitar confusión, DISTFILES y PATCHFILES deberían tener números de versión claramente visibles. No coja foo-latest.tar.gz si es un enlace a foo-1.0.5.tar.gz. Si es necesario, pregúntele gentilmente al autor del programa original para aclarar las distinciones.
   • Si un porte cualquiera necesitara más de unos 5 DISTFILES + PATCHFILES para funcionar, use DIST_SUBDIR para evitar demasiada confusión en /usr/ports/distfiles.
   • No se debe incluir números de versión en DIST_SUBDIR. Cuando se actualiza el porte a una versión posterior, es posible que no cambien algunos ficheros de distfiles, pero si DIST_SUBDIR ha cambiado, fetch los volverá a bajar. Aun en el caso en que todos los ficheros distfile cambiaran, sería más fácil para el usuario hacer un seguimiento completo.
   • No es necesario que todos los DISTFILES y PATCHFILEs vengan del mismo conjunto de MASTER_SITES. Se pueden definir sitios suplementarios usando las variables MASTER_SITES0 hasta MASTER_SITES9. Simplemente, escriba DISTFILES=foo-1.0.5.tar.gz:5 para obtener foo-1.0.5.tar.gz desde MASTER_SITES5.
   • Algunos portes no siempre necesitan obtener todos los ficheros. Por ejemplo, algunos portes pueden tener algunas opciones de compilación, y ficheros asociados que sólo se requieren en el caso concreto. O es posible que necesiten algunos ficheros sólo para algunas arquitecturas y no para otras. En ese caso, esos ficheros suplementarios opcionales deben ser mencionados en la variable SUPDISTFILES. Objetivos como puedan ser makesum o mirror-distfiles obtendrán esos ficheros suplementarios que no son necesarios para los otros.
   
   
6. Cree una suma de comprobación en distinfo mediante make makesum, y verifique que la suma de comprobación es correcta mediante make checksum.
   • En algunos casos extraños, las sumas de comprobación de los ficheros no se pueden verificar con fiabilidad. En tales casos es deseable que se comunique con el autor del software y con el mantenedor del sitio del archivo. En el peor de los casos, los ficheros cuyas sumas de comprobación no se puedan verificar, se mencionarán en la variable IGNOREFILES.
   • Todos los ficheros en DISTFILES suelen ser procesados durante la extracción con make extract. Se puede usar EXTRACT_ONLY para limitar la extracción a un subgrupo de ficheros (probablemente vacíos). El uso personal de esta variable es para personalizar la extracción. Por ejemplo, si algunos ficheros DISTFILES necesitaran algún trato especial, bastaría con eliminarlos de EXTRACT_ONLY y gestionarlos de modo manual después de la extracción. Por motivos históricos, make extract configura primero el directorio local junto con los ficheros de extracción. Así, el proveer de un objetivo previo a la extracción es bastante inusual (y un comportamiento muy sospechoso, que indica un alto grado de ofuscación en el porte).
   • Los parches que necesiten un trato específico deben ser mencionados en DISTFILES, y eliminados de EXTRACT_ONLY por motivos históricos.
   
   
7. Extraiga el porte con make extract. Preste atención a la ubicación de la base de los fuentes, que suele ser w-${PKGNAME}${FLAVOR_EXT}/${DISTNAME}. Es probable que tenga que modificar la variable WRKDIST del fichero Makefile si es distinta.
   
   
8. Lea la documentación sobre la instalación y se dará cuenta de lo que debe hacer para construir el porte y de cualquier opción especial que pueda ser necesaria.
   
   
9. Ahora es un buen momento para pensar en qué tipo de restricciones en la licencia se han aplicado a su porte. Muchos serán de libre redistribución, pero muchos otros no. Necesitamos la respuesta a cuatro preguntas para poder distribuir los portes como es debido. Estas respuestas son los valores PERMIT_* en el fichero Makefile.
   • PERMIT_PACKAGE_CDROM nos indica que podemos incluir el paquete en el cdrom.
   • PERMIT_PACKAGE_FTP nos indica que podemos incluir el paquete en los servidores públicos de ftp.
   • PERMIT_DISTFILES_CDROM nos indica si podemos poner una réplica de los distfiles en el cdrom.
   • PERMIT_DISTFILES_FTP nos indica si podemos poner una réplica de los distfiles en los servidores públicos de ftp.

   Configure esos valores con Yes si está permitido, o a una cadena de comentarios que explique porqué no está permitido. Preste atención a cualquier condición especial que pueda tener que cumplir más tarde. Por ejemplo, algunos portes requieren que se instale una copia de la licencia que los acompaña. Le recomendamos que ponga la licencia en /usr/local/share/DISTNAME/.

   Además de los values PERMIT_*, coloca un marcador de licencia como # Licencia arriba de ellos como comentario, de esta manera sabemos por qué los valores PERMIT_* están establecidos como están.
   
   

10. Añada las opciones de configuración al fichero Makefile y/o genere el guión de configuración.
    • Puede añadir un guión de configuración del porte con el nombre `configure' a un directorio que llamará scripts/. Esto será ejecutado antes de ejecutar cualquier configuración especificada por CONFIGURE_STYLE.
    • Si usa GNU configure, es probable que antes quiera ejecutar './configure --help' para ver qué opciones hay disponibles.
    • Cualquier otra cosa que quiera anular se puede cambiar añadiendo los indicadores --option al parámetro CONFIGURE_ARGS en el fichero Makefile.
    • Use CONFIGURE_ARGS+= para añadir a la variable. Use CONFIGURE_ARGS= para anularla.
    
    
11. Intente construir el porte con make build.
    • Si está de suerte, el porte se compilará sin errores.
    • Si termina el proceso con un error, tendrá que generar parches para su porte. Intente imaginar qué cambios puede necesitar y haga un parche para ellos.
    • Los parches deben ser relativos a ${WRKDIST}.
    • El modo más fácil de reconfigurar un porte y probar los parches es make clean patch. Esto eliminará el directorio local, hará la reextracción, y aplicará los parches.
    
    
12. Empiece un ciclo de make build, genere un parche (o use make update-patches), y make clean patch.
    • Los parches van en el directorio patches/, y deben llevar nombre del tipo patch-* (en donde * sea algo con sentido). Le recomendamos que nombre sus parches patch-FILENAME, en donde FILENAME sea el nombre del fichero al que se esté aplicando el parche (make update-patches hace esto automáticamente).
    • La aplicación de PATCHFILES es la primera mitad de 'make patch'. Se puede invocar por separado como 'make dispatch', que es un objetivo conveniente para los mantenedores de parches. Ignore esto si no lo ha configurado.
    • Parchee sólo un fichero fuente por cada patchfile.
    • Use make update-patches para generar parches.
    • Todos los parches DEBEN ser relativos a ${WRKDIST}.
    • Compruebe que los parches NO contengan indicadores que puedan ser reemplazados por cvs. Si contiene alguno, entonces sus parches no serán aplicados después de haberlos entregado. Puede entregar sus cambios con -kk para evitar esto.
    • Escriba una pequeña explicación al principio del ficheo del parche sobre su propósito (no es obligatorio).
    • Por favor, envíe sus parches al autor original del software.
    
    
13. Intente activar SEPARATE_BUILD.
    
    • Si el porte se puede construir con ficheros objeto fuera de su árbol de fuentes, será más limpio (muchos programas que usan CONFIGURE_STYLE=gnu pueden), y puede ayudar a los usuarios que montan su árbol de portes en varias arquitecturas.
    • Esto también le puede evitar algún esfuerzo, ya que es posible que pueda reiniciar el ciclo en configure la mayoría de las veces.
    
    
14. Lea detenidamente la salida (si es que produce alguna) y retoque cualquier opción necesaria en el fichero Makefile. Para repetir, invoque la orden `make clean configure'.

    Nota: asegúrese de que los ficheros dependientes del anfitrión van a /etc o /etc/<nombre>, pero NUNCA SUBSTITUYA O MODIFIQUE ficheros que existan en /etc. Es mejor poner install en /usr/local/share/<nombre> y que los copie a /etc o /etc/<nombre>, sólo si los ficheros no existen. Si los ficheros existen, muestre un mensaje que indique que tal y tal fichero necesita ser modificado. Esto también garantiza que los ficheros sean incluidos en el paquete, ya que todo lo que haya en /usr/local se incluye en PLIST. Después de que un paquete haya sido instalado, se mostrará el contenido de pkg/MESSAGE, si es que existe.

    Las ubicaciones de los ficheros de OpenBSD son:

       ejecutables del usuario:		/usr/local/bin
       ejecutables del adminstrador:	/usr/local/sbin
       ejecutables por programas:		/usr/local/libexec
       bibliotecas:				/usr/local/lib
       datos dep. arquitectura:		/usr/local/lib/<nombre>
       ficheros include instalados:		/usr/local/include o
    					/usr/local/include/<nombre>
       datos de máqina
       únicos:	       			/etc o /etc/<nombre>
       estado local:			/var/run
       ficheros de
       puntuación de juegos:		/var/games
       ficheros GNU info:			/usr/local/info
       páginas del manual:			/usr/local/man/...
       sólo lectura indep. 
       arquitectura:			/usr/local/share/<nombre>
       documentación 
       miscelánea:				/usr/local/share/doc/<nombre>
       archivos de ejemplo:				/usr/local/share/examples/<name>
    

15. Empiece un ciclo de makes hasta que el porte esté listo. Use Patch (ver arriba), clean, y make hasta generar el porte. Líbrese de todos los avisos si es posible, especialmente de los avisos relacionados con la seguridad.
    
    
16. Controle la semántica de SEPARATE_BUILD. Debe hacerlo sólo si el porte se compila con SEPARATE_BUILD definido. Lo ideal sería que el porte no modificara ningún fichero en ${WRKSRC} después de make patch. Puede comprobarlo asegurándose de que usted no tenga acceso de escritura a ${WRKSRC}. Entonces puede configurar SEPARATE_BUILD=concurrent... alguien podría usar el mismo árbol de fuentes para compilarlo en arquitecturas diferentes de forma simultánea. De otro modo, configure SEPARATE_BUILD=simple... compilar en distintas arquitecturas de forma simultánea puede acarrear problemas, ya que muchos ficheros de fuentes pueden ser regenerados en momentos difíciles.
    
    
17. Añada COMMENT en el fichero Makefile. COMMENT es una CORTA descripción en una línea del porte (60 caracteres máximo). NO incluya el nombre del paquete (o el número de la versión del software) en el comentario. NO lo empiece con mayúscula a menos que tenga un significado semántico, y NO lo termine con un punto. NI SIQUIERA EMPIECE CON UN ARTÍCULO INDETERMINADO COMO "a" o "an" (inglés, por supuesto); elimine el artículo del todo.
    
    
18. Edite pkg/DESCR, pkg/PLIST.
    • DESCR es una descripción más larga del porte. Desde uno hasta unos cuantos párrafos que expliquen brevemente lo que hace el porte será suficiente. Se recomienda usar un máximo de 72 caracteres por línea. Esto se puede hacer editando primero el fichero DESCR y ejecutándolo a continuación mediante fmt -w 72.
    • PLIST se mantendrá vacío de momento.
    
    
19. Si la aplicación necesita crear un usuario o un grupo, hay que escoger el id de menor rango de /usr/ports/infrastructure/db/user.list para que lo use el porte y asegurarse de que el porte se añade a este fichero en el momento de la entrega por cvs.
    
    
20. Instale la aplicación con make install. Si el porte instala bibliotecas dinámicas, compruebe sus tablas de símbolos con nm, ya que algún software equivocado quita las bibliotecas dinámicas, lo que puede conllevar fallos extraños más tarde. Por otra parte, los binarios ejecutables DEBERÍAN ser eliminados; se puede usar file para determinar cuáles. Si el porte ya incluyera código para eliminar los binarios (o sea, el objetivo install-strip), utilílicelo; en caso contrario, debe incluirlo en el fichero Makefile.
    
    
21. Verifique los agujeros de seguridad del porte otra vez. Esto es especialmente importante para programas de red y setuid. Lea nuestras recomendaciones de seguridad. Registre en el fichero pkg/SECURITY todo aquello que pueda ser interesante y las soluciones. Este fichero debe ser una lista de problemas potenciales auditados, junto con parches importantes, de modo que otra persona pueda ver a primera vista lo que se ha hecho. Por ejemplo:

     
          $OpenBSD$
    
          ${WRKDIR}/receiver.c
             call to mktemp (wrapper function do_mktemp) does seem to be correct.
    
          The server makes extensive use of strlcpy/strlcat/snprintf.
    

22. Cree el fichero pkg/PLIST. Después de que la instalación se haya completado use la orden de desarrollador make plist, que compila el fichero PLIST en el directorio pkg. Este fichero es un candidato a la lista de paquetes.

    ¡Atento! Los ficheros se encuentran por la marca de tiempo (timestamp). Esto significa que NO DEBE:

    • listar ningún fichero instalado con 'tar' ya que su marca de tiempo no cambiará y por lo tanto no será encontrado por 'find';
    • actualizar el fichero info/dir si se añaden los ficheros .info. Asegúrese también de que info/dir no forma parte de PLIST;
    • intentar hacer nada especial con enlaces o enlaces simbólicos. Una prueba rápida de 'tar' muestra que hace lo correcto con los enlaces y enlaces simbólicos, así que no hay razón para ningún caso especial en la lista de paquetes. Aún así...

    Lea detenidamente PLIST y verifique que se haya instalado todo, y que la instalación haya tenido lugar en las ubicaciones pertinentes. Se puede añadir cualquier parte que no se haya instalado a una regla `post-install' en el fichero Makefile del porte.

    Los portes que instalen bibliotecas compartidas tendrán otro fichero llamado PFRAG.shared.

    • PLIST describe los ficheros independientemente de si la arquitectura tiene soporte para bibliotecas compartidas o no.
    • PFRAG.shared describe sólo aquellos ficheros que se hayan instalado en las arquitecturas con soporte para bibliotecas compartidas.
    • PFRAG.noshared describe sólo aquellos ficheros que se hayan instalado en las arquitecturas sin soporte para bibliotecas compartidas.
    
    
23. Siga desinstalando y reinstalando hasta que esté perfecto. Perfecto es cuando todo instala y desinstala en su ubicación correcta. Para desinstalar se usa la orden 'pkg_delete' <nombre_paquete>'. Para reinstalar se usa la orden 'sudo make reinstall'. Lea la página de manual de pkg_create(1) para ver otras órdenes que se pueden añadir a PLIST para asegurarse de que está todo limpio. Después de una desinstalación, la orden

        find /usr/local -newer w-${PKGNAME}${FLAVOR_EXT}/fake-${MACHINE_ARCH}[-${FLAVOR}]/.install_started -print
        

    debería mostrar sólo la lista de nombre de directorios típicos.
    
    
24. Pruebe el paquete. Después de que el porte haya instalado correctamente, use la orden make package para crear un paquete. Para probar el paquete, primero use pkg_delete y a continuación pkg_add. Los resultados después de pkg_add deberían ser EXACTAMENTE los mismos que los resultados después de make install.
    
    
25. Envíe una breve nota a ports@openbsd.org para pedir comentarios y pruebas. Adjunte el porte a este mensaje y envíelo.

    Intente que otros usuarios lo prueben en varias plataformas.

    • La plataforma de DEC Alpha es buena porque sólo tiene bibliotecas estáticas y porque sizeof(int) != sizeof(long).
    • La plataforma de Sun SPARC es buena porque es muy común y porque su orden de byte es al revés que en i386; si hubiera llevado a cabo el desarrollo en SPARC, entonces querrá probarlo en i386.
    
    
26. Incorpore cualquier información que reciba. Pruébelo de nuevo en su plataforma. Consiga que quienes le enviaron información sobre la primera prueba, vuelvan a probar el nuevo porte.
    
    
27. Finalmente, inclúyalo en el árbol de portes. Si no tiene acceso al CVS, pida a alguien en ports@openbsd.org que haga la entrega.
    
    
28. Si es un desarrollador con acceso a CVS, entréguelo Vd. mismo. Generalmente usamos "import" para un porte nuevo, en lugar de usar "add" para cada uno de tropecientos (o una docena) ficheros. "import" usa números de versión "vendor branch" como 1.1.1.1, pero no se preocupe por eso. Si efectúa cambios a un fichero específico (editar y entregar por cvs), será 1.2 y se usará ese número.

    De un modo breve, "cvs import" se suele usar cuando un se crea un porte. A partir de ahí se suele usar "cvs add" y "cvs rm" para añadir o eliminar ficheros individuales, y el ciclo normal editar->entregar para los cambios. Puede usar algo como esto:

    $ cd kaffe1
    $ make clean	# ¡en realidad no querrá 
                    # comprobar todo el trabajo!
    $ cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
    	SuNombre SuNombre_YYYY-MMM-DD
    

    • -d cvs.openbsd.org:/cvs indica la dirección de cvs. Se puede omitir esto si se ha definido una variable de entorno CVSROOT.
    • -m 'kaffe port' es su mensaje de registro. Ponga lo que quiera
    • ports/lang/kaffe1 es el camino relativo a /cvs, en donde reside el porte.
    • SuNombre (substituir con su nombre de ingreso) es el "vendor tag" (etiqueta del distribuidor). Vd. lo importó, así que Vd. es el distribuidor.
    • SuNombre_YYYY-MMM-DD (v.g., ian_2000-jan-01) es el "vendor release tag" (etiqueta de lanzamiento del distribuidor). Tan buena como cualquier otra.

    A modo de ejemplo real, he aquí la salida de la comprobación del porte Kaffe1, que uno de nosotros hizo el 8 de septiembre de 1.998:

    $ cd kaffe1
    $ make clean >/dev/null
    $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
    ian@cvs.openbsd.org's password: (lógicamente no se muestra)
    I ports/lang/kaffe1/CVS
    I ports/lang/kaffe1/files/CVS
    I ports/lang/kaffe1/pkg/CVS
    N ports/lang/kaffe1/Makefile
    cvs server: Importing /cvs/ports/lang/kaffe1/files
    N ports/lang/kaffe1/files/md5
    cvs server: Importing /cvs/ports/lang/kaffe1/pkg
    N ports/lang/kaffe1/pkg/COMMENT
    N ports/lang/kaffe1/pkg/DESCR
    N ports/lang/kaffe1/pkg/PLIST
    
    No conflicts created by this import
    $ 
    

29. Por último, añada una entrada de una línea para el nuevo porte en el fichero Makefile de su directorio de primer nivel; por ejemplo, para ports/lang/kaffe1, añádala en ports/lang/Makefile.
    
    
30. ¡Mantenga el porte! Según pase el tiempo pueden surgir problemas, o pueden aparecer nuevas versiones del software. Debe intentar mantener su porte actualizado: en otras palabras, «probar, comprobar, verificar, probar, ...»
    
    
31. Cuando actualice un porte, recuerde gestionar las dependencias. No debe dejar que ningún otro porte que dependa del suyo pueda quedar «roto». En caso de que surjan problemas, comuníquese con los mantenedores de estos portes. Asimismo, esté atento a las actualizaciones de otros portes de los que pueda depender el suyo, y compruebe que el mantenedor haya hecho bien su trabajo.