From 79a3afe9dd2a236d580f228a3ee1ca2103d93e93 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Oct 06 2013 04:18:20 +0000 Subject: Update tcar_setModuleEnvironment.sh.asciidoc file. - Remove most information about modules from this file. This information was already moved from it to Understanding Modules. --- diff --git a/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc b/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc index c19af0a..cc0ebef 100644 --- a/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc +++ b/Automation/Manuals/tcar_setModuleEnvironment.sh.asciidoc @@ -14,129 +14,6 @@ Synopsis Description ----------- -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 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] -====================================================================== -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. -====================================================================== - -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 -------