Changes between Version 24 and Version 25 of TolPackageRulesAndComments

Timestamp:

Oct 18, 2010, 5:28:59 PM (14 years ago)

Author:

Víctor de Buen Remiro

Comment:

--

TolPackageRulesAndComments

@@ -33 +33 @@
 de los problemas que pueden resolver.
 
-== Arquitectura ==
-
-Un paquete es un tipo de NameBlock especial que se carga con la orden 
+== Uso básico de paquetes ==
+
+Un paquete es un caso de NameBlock especial que se carga con la orden 
 {{{
   #Require nombre_de_paquete;
@@ -42 +42 @@
 directorio local predeterminado por el sistema al que llamaremos almacén
 del cliente y que es común para todas las instalaciones de TOL que haya
-en una misma máquina.
+en una misma máquina y ubicado en {{{Text TolPackage::Client::_.localRoot}}}.
+
+La orden de requerimiento {{{#Require}}} es muy diferente a las órdenes 
+de inclusión {{{Include}}} e incrustación {{{Embed}}} por estos motivos
+fundamentales:
+
+ * No hay que dar el camino del archivo TOL sino el nombre del paquete
+ * No hay que poner el nombre entre comillas
+ * El NameBlock cargado es siempre global se llame desde donde se llame
+ * No es posible deshacer un requerimiento: el paquete permanecerá 
+   disponible durante toda la sesión
 
 Un repositorio es un sitio web o un directorio local al que llamaremos
 también almacén servidor, donde se encuentra disponible una colección de 
 paquetes ya preparados para que los usuarios puedan descargarlos a su 
-almacén de cliente.
+almacén de cliente. Los paquetes se encuentran comprimidos en el 
+repositorio remoto mientras que en el almacén del cliente se encuentran
+los directorios descomprimidos para no perder tiempo en descomprimirlos 
+cada vez.
+
+=== El gestor de paquetes ===
+
+El gestor de paquetes TOL es el {{{NameBlock TolPakage}}}
 
 Los paquetes disponibles en repositorios remotos o locales se instalan,
@@ -56 +73 @@
 {{{StdLib::TolPackage::Server}}}
 
-== Creación y uso de paquetes ==
+=== Uso on-line de paquetes ===
+
+La propia orden {{{#Require}}} se encargará de descargar e instalar los 
+paquetes que no se encuentren disponibles localmente revisando la lista 
+de directorios apuntada por 
+{{{
+#!cpp
+  Set TolConfigManager::Config::Upgrading::TolPackage::Repositories
+}}}
+
+Por defecto, esta lista sólo contiene el [wiki:OfficialTolArchiveNetwork 
+repositorio oficial de bayes] pero es posible añadir otros mediante
+{{{
+  Real TolPackage::Client::AddRepository(Text url)
+}}}
+
+=== Uso off-line de paquetes ===
+
+Para el uso off-line de los paquetes en una máquina sin acceso remoto es
+necesario instalar manualmente los paquetes. Para ello lo más sencillo es
+instalarlos en una máquina que sí tenga acceso y luego copiar el directorio
+{{{Text TolPackage::Client::_.localRoot}}} a la máquina aislada mediante 
+algún tipo de disco o unidad flash.
+
+Para evitar que el sistema pierda tiempo intentando conectarse es 
+recomendable cambiar la configuración local de TOL
+{{{
+#!cpp
+  Real TolConfigManager::Config::Upgrading::TolVersion::CheckAllowed:= False;
+  Real TolConfigManager::Config::Upgrading::TolPackage::LocalOnly := False;
+  Real TolConfigManager::SaveConfig(TolConfigManager::Config);
+}}}
+
+
+== Creación de paquetes ==
  
 Un paquete se crea como un NameBlock pero con una serie de restricciones de 
@@ -70 +121 @@
  * Los miembros obligatorios del NameBlock de un paquete son: [[BR]]
    {{{
+#!cpp
   Text _.autodoc.name = "NombreDelPaquete";
   Text _.autodoc.brief = "Descripción cortísima en una línea";
@@ -82 +134 @@
    }}}
  * Cuando un paquete requiera para su ejecución de recursos ajenos a TOL será 
-   necesario añadir un nuevo miembro que será un conjunto de conjuntos de 
-   caminos a los directorios raíces de cada uno de los recursos. Los que sean 
-   independientes de la plataforma se pueden poner en un elemento 
-   {{{crossPlatform}}} y los que sí dependan en uno con el nombre de la 
-   plataforma. Los nombres de los recursos han de ser únicos dentro de cada
-   plataforma específica y serán lógicamente los mismos en todas ellas, pues 
-   los recursos deberían estar disponibles en cualquiera de ellas, aunque podría 
-   haber excepciones si no se encuentra la forma de implementarlo en alguna.
-   Los recursos multi-plataforma deben tener nombres únicos distintos de los de
-   las específicas pues en el almacén de cliente convivirán con ellos en un 
-   mismo directorio. [[BR]]
+   necesario añadir un nuevo miembro que será un conjunto de textos con los  
+   caminos, obligatoriamente relativos e internos al paquete, de los directorios 
+   raíces de cada uno de los recursos. Los que sean dependientes de la plataforma 
+   deben tener una entrada distinta para cada una de forma que luego sea posible 
+   cargar lo necesario. Todos los recursos así definidos pasarán a formar parte 
+   del directorio del paquete [[BR]]
    {{{
+#!cpp
   Set _.autodoc.nonTolResources = { [[
-    Set crossPlatform = { [[ 
-       Text resource_cross_1="./....", 
-       Text resource_cross_2="./....", 
-       ... ]] },
-    Set win32_x86 =  { [[ 
-       Text resource_1="./....", 
-       Text resource_2="./....", 
-       ... ]] },
-    Set linux_x86 =  { [[ 
-       Text resource_1="./....", 
-       Text resource_2="./....", 
-       ... ]] },
+    Text "./resource_1", 
+    Text "./resource_2", 
+    Text "./resource_3/Linux_x86_32", 
+    Text "./resource_3/Windows_x86_32", 
     ...
   ]] };
    }}}
+
+=== Construcción del archivo comprimido ===
+
+Si sólo se quiere construir el archivo .zip correspondiente a un paquete basta con llamar a
+{{{
+#!cpp
+//////////////////////////////////////////////////////////////////////////////
+Text TolPackage::Server::BuildPackage(
+  Text name,         //Nombre del paquete (sin versión)
+  Text sourceRoot,   //Directorio raíz del código fuente
+  Text destination,  //Directorio de destino del paquete
+  Real removeDir)    //Si es cierto se borra el directorio descomprimido
+"Construye el archivo comprimido correspondiente a un paquete TOL a partir "
+"del código situado en el directorio fuente:\n"
+"  \"<sourceRoot>/<name>\"\n"
+"\n"
+"El resultado se almacena en el directorio de destino con el nombre de "
+"la versión específica que conste en el NameBlock del paquete:"
+"\n"
+"  \"<destination>/<name>.<high>.<low>.zip\"\n"
+"\n";
+//////////////////////////////////////////////////////////////////////////////
+}}}
+
+Para hacer una instalación manual directa basta con pasarle
+{{{
+#!cpp
+Text destination = TolPackage::Client::_.localRoot,
+Real removeDir   = False
+}}}
+
+Si no se quiere interferir con la instalación local es mejor pasarle
+{{{
+#!cpp
+Text destination = TolPackage::Server::_.localRoot,
+Real removeDir   = True
+}}}
+
+=== Publicación de paquetes ===
+
+Para subir un paquete ya comprimido previamente con {{{TolPackage::Server::BuildPackage}}} se usará
+{{{
+#!cpp
+//////////////////////////////////////////////////////////////////////////////
+Real TolPackage::Server::UploadPackage(NameBlock dbConnect, Text pkg.path.zip)
+"Sube al repositorio remoto un paquete desde el archivo local comprimido "
+"creado con TolPackage::Server::BuildPackage y dado por el argumento:\n"
+"  Text pkg.path.zip = \"<directory>/<name>.<high>.<low>.zip\"\n";
+//////////////////////////////////////////////////////////////////////////////
+}}}
+
+=== Construcción y publicación de paquetes en un solo paso ===
+La manera más sencilla de subir un paquete es mediante la función 
+{{{
+#!cpp
+//////////////////////////////////////////////////////////////////////////////
+Real BuildAndUploadPackage(
+  Text name,                //Nombre del paquete (sin versión)
+  Text sourceRoot,          //Directorio raíz del código fuente
+  Text repository.url,      //URL del repositorio
+  NameBlock repository.db,  //Conexión a la base de datos
+  Text checkInstallMode)    //Modo de chequeo de la instalación
+"Construye el archivo comprimido correspondiente a un paquete TOL a partir "
+"del código situado en el directorio fuente:\n"
+"  \"<sourceRoot>/<name>\"\n"
+"\n"
+"y luego lo sube al repositorio remoto.\n"
+"La copia temporal del archivo comprimido del paquete se queda en el "
+"directorio del servidor a efectos de depuración si surgen problemas "
+"pero se puede borrar si se desea.\n"
+"Por último se chequeará la instalación según lo indicado:"
+" Si checkInstallMode = \"local\" se usa la copia local comprimida.\n"
+" Si checkInstallMode = \"remote\" se instala desde el repositorio.\n"
+" En otro caso no se instala nada.";
+//////////////////////////////////////////////////////////////////////////////
+}}}
+que internamente llama a {{{TolPackage::Server::BuildPackage}}} y 
+{{{TolPackage::Server::UploadPackage}}} y luego chequea opcionalmente si 
+funciona la instalación.
+
 
 === Control de versiones ===