tcar_setModuleEnvironment.sh(1)
===============================
Name
----
tcar_setModuleEnvironment.sh - Initiate module environments.
Synopsis
--------
*tcar_setModuleEnvironment [-m "MODULE_NAME"] [-t "MODULE_TYPE"] [-g MODULE_ARGUMENT] ...*
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-implementation>>.
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
-------
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
------
The *centos-art.sh* script has received contribution from the
following people:
* Alain Reguera Delgado <mailto:al@centos.org.cu[al@centos.org.cu]>, 2009-2013
Copyright
---------
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
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
// vim: set syntax=asciidoc: