| | 1 | = Reglas de construcción y comentarios acerca de paquetes y repositorios = |
| | 2 | |
| | 3 | * Un paquete es un tipo de NameBlock especial que se carga con la orden |
| | 4 | #Require nombre_de_paquete y que se carga directamente de un archivo .oza |
| | 5 | almacenado previamente en un directorio local predeterminado por el sistema. |
| | 6 | * Los paquetes están disponibles en repositorios remotos o locales desde los |
| | 7 | cuales es posible instalarlos y manejarlos mediante las utilidades de |
| | 8 | StdLib::TolPackage::Client |
| | 9 | * Las correspondientes funciones de creación y mantenirmiento de los |
| | 10 | respositorios están disponibles en StdLib::TolPackage::Server |
| | 11 | * Los nombres de los paquetes deben seguir el estilo CamelCase |
| | 12 | * Un paquete se crea como un NameBlock en un fichero principal del mismo |
| | 13 | nombre con extensión .tol y dentro de un directorio raíz llamado igual. El |
| | 14 | fichero principal puede cargar con #Embed los archivos auxiliares que |
| | 15 | necesite con nombre libre pero ubicación paralela o en subdirectorios del |
| | 16 | raíz. |
| | 17 | * Cuando un paquete requiere de otros se debe incluir las correspondientes |
| | 18 | sentencias #Require antes de la declaración del primer miembro. |
| | 19 | * Los miembros obligatorios del NameBlock de un paquete son: |
| | 20 | * Text _.autodoc.brief = "Descripción cortísima en una línea". |
| | 21 | * Text _.autodoc.description = "Descripción detallada"; |
| | 22 | * Text _.autodoc.url = "http://.../"; |
| | 23 | * Set _.autodoc.keys = [["Palabras","Clave", ...]]; |
| | 24 | * Set _.autodoc.authors = [[ "fulanito@mail.tal", "menganito@mail.cual"]]; |
| | 25 | * Text _.autodoc.minTolVersion = TolPackage::_.currentTolVersion; |
| | 26 | * Real _.autodoc.version.high = 1; |
| | 27 | * Real _.autodoc.version.low = 1; |
| | 28 | * Set _.autodoc.dependencies = [["paquete1","paquete2", ...]]; |
| | 29 | * El nombre del archivo de una versión concreta de un paquete se obtiene |
| | 30 | como la concatenación del nombre del paquete seguido de un punto, el número |
| | 31 | _.autodoc.version.high, otro punto y el número _.autodoc.version.low |
| | 32 | * Si no se especifica números de versión el #Require cargará la versión más |
| | 33 | actual que corresponderá siempre al archivo con el nombre del paquete nada |
| | 34 | más. En este caso los paquetes que requiera directa o indirectamente serán |
| | 35 | también las últimas versiones y no hace falta hacer nada previamente. |
| | 36 | * Si se especifica una versión concreta entonces se debe cargar previamente |
| | 37 | cada uno de los paquetes requeridos directa o indirectamente mediante el método |
| | 38 | StdLib::TolPackage::Client::ForceExactRequirements, antes de que se llame al |
| | 39 | #Require de ninguno de ellos. |
| | 40 | * La definición del paquete siempre debe usar #Require sin especificar una |
| | 41 | versión concreta. |
| | 42 | * Obsérvese que los paquetes requeridos se deben especificar por duplicado: |
| | 43 | primero en los #Require sin comillas y luego en Set _.autodoc.dependencies |
| | 44 | entre comillas pues esta información la necesita el gestor de repositorios. |
| | 45 | * No puede haber paquetes con el mismo nombre de NameBlock ni en el mismo ni |
| | 46 | en distinto repositorio. |
| | 47 | * No está permitido el requerimiento cíclico directo ni indirecto entre |
| | 48 | paquetes, es decir, si A requiere a B directa o indirectamente B no puede |
| | 49 | requerir a A ni directa ni indirectamente. El sistema gestor de repositorios |
| | 50 | caería en un ciclo infinito y no hay forma de detectarlo luego es |
| | 51 | responsabilidad de los desarrollodares del repositorio el evitarlo. |
| | 52 | * Cada paquete debe estar dotado de documentación autocontenida de manera |
| | 53 | que cualquier usuario pueda aprender a usarlo por sí mismo. Queda por ver si |
| | 54 | esa documentación ha de ser WIKI, HTML, PDF, ASCII, o si puede ser opcional |
| | 55 | el formato. La documentación estará ubicada en cualquier caso dentro de |
| | 56 | un directorio doc colgando directamente de la raíz del paquete. |
| | 57 | * También debe tener una batería de tests estándar en un directorio test |
| | 58 | colgando directamente de la raíz del paquete. |
| | 59 | * El repositorio es un directorio plano con unos archivos obligatorios: |
| | 60 | * index.tol: Contiene características generales del repositorio como el |
| | 61 | nombre, el tipo ("Private" ó "Public") y la descripción de los objetivos. |
| | 62 | * index.csv: Listado de los paquetes y su información asociada: fecha, |
| | 63 | versión, dependencias, etc. |
| | 64 | * Debe haber un comité o alguien responsable de probar todos los paquetes de |
| | 65 | un repositorio antes de publicar las actualizaciones de los paquetes para |
| | 66 | asegurar la compatibilidad conjunta de todos ellos. |
