diff --git a/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc b/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc index 51eb5c2..c19af0a 100644 --- a/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc +++ b/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc @@ -9,109 +9,188 @@ tcar_setModuleEnvironment.sh - Initiate module environments. Synopsis -------- -tcar_setModuleEnvironment -m "MODULE_NAME" -t "MODULE_TYPE" "${@}" +*tcar_setModuleEnvironment [-m "MODULE_NAME"] [-t "MODULE_TYPE"] [-g MODULE_ARGUMENT] ...* Description ----------- -Inside the centos-art.sh script, from version 0.5 on, all -functionalities have been rewritten to fit a modular design. This -modular design is conceived with the idea of loading and -executing only the functions that are absolutely required for the -current task. - -Inside the centos-art.sh script there are two kinds of functions, +From version 0.5 of The CentOS Artwork Repository on, the +*centos-art.sh* script was redesigned to introduce the idea of modules +to its base design. Modules are a collection of functions written in +Bash that can call one another to create individual execution +environments. They may be nested efficiently to achieve high levels of +maintainability and extensibility. This make possible for modules +writers to divide complicated tasks into smaller tasks that can be +easier to debug, maintain and share with other modules efficiently +(e.g., instead of loading modules all at once, they are only loaded at +demand and unset once they conclude their execution). + +Inside the *centos-art.sh* script there are two kinds of functions, which are "global functions" and "module-specific functions." The -global functions are loaded in the very beginning of centos-art.sh -script and remain in memory for you to use whenever you need it, -using a regular function call syntax. The module-specific -functions, on the other hand, are only loaded when they are needed -and they are removed from memory once the task they were created -to perform is over. To load module-specific functions inside the -centos-art.sh script, you use the tcar_setModuleEnvironment -function as described in the USAGE section, above. - -Each time you execute the tcar_setModuleEnvironment function, you -are creating a new module environment. Module environments are -logical space where you can develop solutions for specific -problems. These spaces are made available by creating a module -directory structure inside the CentOS artwork repository, -specifically under the Automation/Modules/ location. Inside this -location, you can find the different types of modules we mentioned -earlier (top-module, sub-module, and sib-module), based on the -levels deep they are stored in the file system. - -The module directory structure, as interpreted by -tcar_setModuleEnvironment has the following form: - -.Module's directory structure. +global functions are loaded in the very beginning of *centos-art.sh* +script and remain in memory for you to use whenever you need it, using +a regular function call syntax. The module-specific functions, on the +other hand, are only loaded when they are needed and they are removed +from memory once the task they were created for is done. To load +module-specific functions inside the *centos-art.sh* script, you use +the *tcar_setModuleEnvironment* global function as described in the +synopsis section above. + +Module Execution Environment +---------------------------- + +Each time you execute the *tcar_setModuleEnvironment* function, it +creates a new ``Module Environment.'' A module environment is a +logical space where you can deploy solutions for specific problems. +The implementation of these solutions take place in the Modules +directory of *centos-art.sh* script, as described in +<>. + +Module environments all begin with a ``top-module.'' These modules are +stored at the first level of Modules directory inside the +*centos-art.sh* script tree. These modules are small and their goal +main goal it to define global variables for task-specific actions, +interpret module-specific options passed in the command-line and +execute the appropriate sub-module based on it. + +Sub-modules are module environments that nest one inside another +creating a chain of module environments. A chain of module +environments is very useful in situations where you want to divide one +large task into smaller tasks and also control which of those smaller +tasks are loaded based on specific conditions (e.g., you want to +render both images and documentation). In a chain of modules, module +environments at a lower level in the chain (those started last) have +access to higher module environments (those started first), but not +the opposite. When processing information this way, module +environments aren't destroyed until the last module environment loaded +is done. At that point, module environments are destroyed in the +reverse order they were loaded (e.g., if the chain of module was +executed as ``render->images->svg'', then, when ``svg'' module +environment is done, the chain of modules will be destroy ``images'' +and finally ``render''). + +Module environments can also share one common module environment on +top of them to create sibling processing (sib-module). Sibling +processing is very useful in situations where you start processing +information in a way and then need to jump to another kind of +processing (e.g., when you are rendering documentation you first start +rendering it as html and then jump into manpage). In this situation, +you open a module environment that contains information useful for two +or more different kind of information processing and jump from one +processing to another without destroying the common information. +However, when one of the specific way or processing information is +done, it is destroyed. This, before opening a new way of processing +(e.g., once html processing is done, the html module is destroyed and, +then, the manpage module is loaded). So, only the required modules are +active while processing information. + +[[module-implementation]] +Module Implementation +--------------------- + +The implementation of *tcar_setModuleEnvironment* function uses global +array variables to store information about the modules and (non-array) +local variables to handle the information stored about modules in each +call of the function. Each time you call the +*tcar_setModuleEnvironment* function, it increments the array +variables counter, stores module-specific information in the array +variables, reset (non-array) local variables using the current +module's information stored in the array variables and executes the +module's initialization script from (non-array) local variables. When +the module's environment finishes its execution, the array counter +decrements and the module's environment is unset, to free the memory +it was using. This process repeats continually, each time you call +the *tcar_setModuleEnvironment* function. + +[TIP] ====================================================================== ----------------------------------------------------------------------- -Automation/Modules/ -`-- $\{MODULE_NAME} -|-- Modules/ <-- module's sub-module files. -|-- Manuals/ <-- module's documentation files. -|-- Locales/ <-- module's localization files. -|-- Configs/ <-- module's configuration files. -`-- $\{MODULE_NAME}.sh <-- module's initialization file. ----------------------------------------------------------------------- +In case you want to see how modules are created and destroyed inside, +pass the *--debug* option to *centos-art.sh* script. It will activate +the script internal debugger for you to see the whole process. ====================================================================== -This structure, is common to all type of modules. You can nest -modules by creating directory structures like this, inside the -Modules/ directory of whatever module you want to extend its -functionality. - -The tcar_setModuleEnvironment function falls into the group of -global functions inside the centos-art.sh script. Its -implementation uses global array variables to store information -about the modules and local (non-array) variables to handle all -the information related to modules. Each time the -tcar_setModuleEnvironment function is called, it adds another -entry to MODULE_ array variables and uses local variables to set -the module's current information. - -In case you want to see debugging information for array variables -in tcar_setModuleEnvironment, you need to set the -TCAR_FLAG_DEBUGGING environment variable to "true". Generally, we -add the --debug option to modules, and set the variable there, so -you can control whether to see debug information or not from the -module's command-line. - - -In the very beginning of tcar_setModuleEnvironment function we -were using just local variables and it worked fine for top-module -and sub-module loading, however when it was needed to load a -sibling module, centos-art.sh failed. The failure was produced -because a wrong variable assignment when tried to set the path of -the next module to load. There was not a clean way to "remember" -what was the base directory of the parent directory so we ended up -using the last loaded module base directory which made impossible -to load a sibling module. Using array variables to store -information about loaded modules fixes the issue of remembering -information from previous modules loaded. - -At this time the tcar_setModuleEnvironment function seems to work -as expected without any issue. - +When we say that a module environment is destroyed it means that all +the related variables and functions which make that module environment +useful are removed from *centos-art.sh* script execution environment, +which make the module environment inoperable to all effects, indeed. +However, the global array variables used by +*tcar_setModuleEnvironment* function to store module-specific +information remain active until the last module environment is +destroyed. This make possible for *centos-art.sh* script to remember +information about the module environments required for a specific +tasks. It is also very useful when it is necessary to jump from one +module environment to another under the same parent module environment. + +Each module environment you want to execute needs a module directory +in the *centos-art.sh* script tree. In this directory you organize the +functions that make your module environment useful. The directory +structure of your module directory is important because +*tcar_setModuleEnvironment* makes use of it to know module-specific +information. + +To illustrate how modules need to be implemented inside +*centos-art.sh* script in order for *tcar_setModuleEnvironment* to +execute them, we are using an example module named ``greet''. The +purpose of greet module is instructive only. Because, greet has a +module directory structure for its own, its documentation is not in +this documentation page but in greet module own documentation page. To +read greet module's documentation page, run the following command: +*centos-art greet --help*. + +[[options]] Options ------- - * -m :: - The name of the module you want to load. The argument of this - option should be module's initialization file (without extension). - * -t:: - The type of module you want to load. The argument of this option - should be one of the following values (only): - * top-module:: - is used when you want to load first-level modules, such as - render, locale and tuneup. - * sub-module:: - is used when you want to load next-level modules. This is, - modules that are one inside another. - * sib-module:: - is used when you want to load siblings modules. This is, - modules that are located at the same level. +The *tcar_setModuleEnvironment* function accepts the following +options: + +-m :: + This option specifies the name of the module you want to load. +-t:: + This option specifies the type of the module you want to load. + Modules can be one of the following types: ++ +top-module;; + This modules are stored in the first level of Modules directory. + This type of modules initiate module environments for specific + tasks so it can be called from anywhere inside *centos-art.sh* + script. +sub-module;; + This modules are stored from the second-level of Modules directory + on. This type of modules can be executed from top-modules, + sub-modules, or sib-modules but never the *centos-art.sh* file + itself. +sib-module;; + This modules are stored from the second-level of Modules directory + on. This type of modules can be executed from sub-modules or + sib-modules, but never top-modules or the *centos-art.sh* file + itself. +-g:: + This option specifies the module-specific option you want to pass + for processing in the module environment you are about to execute. + Generally, module-specific options are passed through + *centos-art.sh* command-line but you may need to pass them + internally in some cases (e.g., you are executing a top-module + from a sub-module). If you need to pass more than one option, then + you need to put the -g option before each option you want to pass. + +Bugs +---- + +In the very beginning of *tcar_setModuleEnvironment* function, it used +just non-array variables and it worked fine for top-module and sub-module +processing, however when it was needed to do sibling processing, it +didn't work as expected. The failure was produced because a wrong +variable assignment when tried to set the path of the next module to +load. There was not a clean way to ``remember'' what was the base +directory of the parent directory, so it ended up using the last +loaded module base directory which made impossible to load a sibling +module. The *tcar_setModuleEnvironment* function as implemented in +version 0.5 of The CentOS Artwork Repository, fixes this issue +replacing non-array variables by array variables which can remember +module information. + +See also: https://centos.org.cu/bugs/[https://centos.org.cu/bugs/] Author ------ @@ -119,12 +198,12 @@ Author The *centos-art.sh* script has received contribution from the following people: - * Alain Reguera Delgado , 2009-2013 +* Alain Reguera Delgado , 2009-2013 Copyright --------- -Copyright (C) 2009-2013 The CentOS Project +Copyright (C) 2009-2013 The CentOS Artwork SIG This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by