Reglas de construcción y comentarios acerca de paquetes y repositorios

• Un paquete es un tipo de NameBlock especial que se carga con la orden #Require nombre_de_paquete y que se lee directamente de un archivo .oza almacenado previamente en un directorio local predeterminado por el sistema.
• Los paquetes están disponibles en repositorios remotos o locales desde los cuales es posible instalarlos y manejarlos mediante las utilidades de StdLib::TolPackage::Client
• Las correspondientes funciones de creación y mantenirmiento de los respositorios están disponibles en StdLib::TolPackage::Server
• Los nombres de los paquetes deben seguir el estilo CamelCase
• Un paquete se crea como un NameBlock en un fichero principal del mismo nombre con extensión .tol y dentro de un directorio raíz llamado igual. El fichero principal puede cargar con #Embed los archivos auxiliares que necesite con nombre libre pero ubicación paralela o en subdirectorios del raíz.
• Cuando un paquete requiere de otros se debe incluir las correspondientes sentencias #Require antes de la declaración del primer miembro.
• Los miembros obligatorios del NameBlock de un paquete son:
  • Text _.autodoc.brief = "Descripción cortísima en una línea".
  • Text _.autodoc.description = "Descripción detallada";
  • Text _.autodoc.url = "​http://.../";
  • Set _.autodoc.keys = "Palabras","Clave", ...?;
  • Set _.autodoc.authors = "fulanito@mail.tal", "menganito@mail.cual"?;
  • Text _.autodoc.minTolVersion = TolPackage::_.currentTolVersion;
  • Real _.autodoc.version.high = 1;
  • Real _.autodoc.version.low = 1;
  • Set _.autodoc.dependencies = "paquete1","paquete2", ...?;
• Puesto que un paquete se almacena como un módulo OZA, está terminantemente prohibido que un NameBlock ejecute acciones de ningún tipo durante su creación. Si se hace algo así el sistema no avisará pero simplemente no se realizarán las acciones previstas. Es decir, las declaraciones de los miembros no pueden tener efectos secundarios como
  • Modificar variables con :=, PutValue, Append, ... .
  • Llamar al sistema operativo para crear, borrar ni modificar nada.
  • Abrir conexiones a la base de datos o a cualquier otro mecanismo de consulta.
• Si un paquete necesita ejecutar alguna acción antes de ser utilizado deberá tener un método
  Real StartActions(Real void) { ... };
  el cual será llamado justo después de ser cargado por el #Require por vez primera.
• El nombre del archivo de una versión concreta de un paquete se obtiene como la concatenación del nombre del paquete seguido de un punto, el número _.autodoc.version.high, otro punto y el número _.autodoc.version.low
• Si no se especifica números de versión el #Require cargará la versión más actual que corresponderá siempre al archivo con el nombre del paquete nada más. En este caso los paquetes que requiera directa o indirectamente serán también las últimas versiones y no hace falta hacer nada previamente.
• Si se especifica una versión concreta entonces se debe cargar previamente cada uno de los paquetes requeridos directa o indirectamente mediante el método StdLib::TolPackage::Client::ForceExactRequirements, antes de que se llame al #Require de ninguno de ellos.
• La definición del paquete siempre debe usar #Require sin especificar una versión concreta.
• Obsérvese que los paquetes requeridos se deben especificar por duplicado: primero en los #Require sin comillas y luego en Set _.autodoc.dependencies entre comillas pues esta información la necesita el gestor de repositorios.
• No puede haber paquetes con el mismo nombre de NameBlock ni en el mismo ni en distinto repositorio.
• No está permitido el requerimiento cíclico directo ni indirecto entre paquetes, es decir, si A requiere a B directa o indirectamente B no puede requerir a A ni directa ni indirectamente. El sistema gestor de repositorios caería en un ciclo infinito y no hay forma de detectarlo luego es responsabilidad de los desarrollodares del repositorio el evitarlo.
• Cada paquete debe estar dotado de documentación autocontenida de manera que cualquier usuario pueda aprender a usarlo por sí mismo. Queda por ver si esa documentación ha de ser WIKI, HTML, PDF, ASCII, o si puede ser opcional el formato. La documentación estará ubicada en cualquier caso dentro de un directorio doc colgando directamente de la raíz del paquete.
• También debe tener una batería de tests estándar en un directorio test colgando directamente de la raíz del paquete.
• El repositorio es un directorio plano con unos archivos obligatorios:
  • index.tol: Contiene características generales del repositorio como el nombre, el tipo ("Private" ó "Public") y la descripción de los objetivos.
  • index.csv: Listado de los paquetes y su información asociada: fecha, versión, dependencias, etc.
• Debe haber un comité o alguien responsable de probar todos los paquetes de un repositorio antes de publicar las actualizaciones de los paquetes para asegurar la compatibilidad conjunta de todos ellos.