Blame tcar-scripts-docs/Understanding_Modules/understanding_modules.asciidoc

Alain Reguera Delgado cdbf5c
Understanding Modules
Alain Reguera Delgado cdbf5c
=====================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado <al@centos.org.cu>
Alain Reguera Delgado cdbf5c
v0.1, Oct 2013
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Overview
Alain Reguera Delgado cdbf5c
--------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
From version 0.5, *centos-art.sh* script implements the idea of
Alain Reguera Delgado cdbf5c
modules to its base design. Modules are a collection of functions
Alain Reguera Delgado cdbf5c
written in Bash that can call themselves one another to create
Alain Reguera Delgado cdbf5c
individual execution environments. They may be nested to achieve high
Alain Reguera Delgado cdbf5c
levels of maintainability and extensibility. This make possible for
Alain Reguera Delgado cdbf5c
modules writers to divide complicated tasks into smaller tasks that
Alain Reguera Delgado cdbf5c
can be easier to debug, maintain and share with other modules
Alain Reguera Delgado cdbf5c
efficiently (e.g., instead of loading modules all at once, they are
Alain Reguera Delgado cdbf5c
only loaded at demand and unset once they conclude their execution).
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This article describes the modular design of *centos-art.sh* script.
Alain Reguera Delgado cdbf5c
It is a good place for you to start if you are planning to contribute
Alain Reguera Delgado cdbf5c
new module environments to *centos-art.sh* script or want to know more
Alain Reguera Delgado cdbf5c
about how they work. The next section delves into what a module
Alain Reguera Delgado cdbf5c
environment is, the three module types you can find in it and the
Alain Reguera Delgado cdbf5c
correct way of execute each one of them.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-environment]]
Alain Reguera Delgado cdbf5c
Module Environment
Alain Reguera Delgado cdbf5c
------------------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
When you execute the *centos-art.sh* script you create an execution
Alain Reguera Delgado cdbf5c
environment in which variables and functions are defined. This
Alain Reguera Delgado cdbf5c
execution environment is the higher environment inside *centos-art.sh*
Alain Reguera Delgado cdbf5c
script. It is considered to have a ``global'' scope, so variables and
Alain Reguera Delgado cdbf5c
functions defined inside it are always available for any function
Alain Reguera Delgado cdbf5c
execution made from it. You can control the execution environment of
Alain Reguera Delgado cdbf5c
*centos-art.sh* script through +centos-art.sh+ and
Alain Reguera Delgado cdbf5c
+centos-art.conf.sh+ files. These files don't provide too much
Alain Reguera Delgado cdbf5c
functionality so specific module environments are executed from
Alain Reguera Delgado cdbf5c
+centos-art.sh+ at demand, to extend its functionality.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Module environments are made of small functions that perform small
Alain Reguera Delgado cdbf5c
tasks and can be further executed in a specific order to produce a
Alain Reguera Delgado cdbf5c
desired result.  Module environments are executed and destroyed at
Alain Reguera Delgado cdbf5c
demand.  Inside *centos-art.sh*, module environments can be either
Alain Reguera Delgado cdbf5c
``parent modules,'' ``child modules,'' or ``sibling modules.''
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[parent-modules-environment]]
Alain Reguera Delgado cdbf5c
Parent Modules
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Parent modules are initiated by executing the
Alain Reguera Delgado cdbf5c
*tcar_setModuleEnvironment* function with the *-t parent* option set
Alain Reguera Delgado cdbf5c
on it. Parent modules are very simple in design and you can use them
Alain Reguera Delgado cdbf5c
to implement simple solutions quickly. Normally, when you execute a
Alain Reguera Delgado cdbf5c
parent module, you initiate the highest module environment possible
Alain Reguera Delgado cdbf5c
inside *centos-art.sh* script.  Because of such high scope, parent
Alain Reguera Delgado cdbf5c
modules are frequently used to define module's global variables,
Alain Reguera Delgado cdbf5c
interpret module-specific options passed through the command-line and
Alain Reguera Delgado cdbf5c
execute the appropriate actions based on them.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
In <<debug-parent-modules>>, we have executed the *hello* module with
Alain Reguera Delgado cdbf5c
the *--greeting=hi* and *--debug* options through the command-line. In
Alain Reguera Delgado cdbf5c
this example, *centos-art.sh* script executes a parent module named
Alain Reguera Delgado cdbf5c
*hello*, processes the module-specific options passed through the
Alain Reguera Delgado cdbf5c
command-line, prints a greeting message to standard output and exits
Alain Reguera Delgado cdbf5c
successfully.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[debug-parent-modules]]
Alain Reguera Delgado cdbf5c
.Debugging execution of parent modules
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT =========================>      [0] | main
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_NAME                [0]=hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_TYPE                parent
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_ARGUMENT            --greeting=hi  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TEXTDOMAIN                      hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT export -f                       hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT export -f                       hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT ------------------------->      hello --greeting=hi  
Alain Reguera Delgado cdbf5c
hi             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT <-------------------------      hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT unset -f                        hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT unset -f                        hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:53:28 PM CDT <=========================      [0] | main
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<<debug-parent-modules>> describes an entire module environment in
Alain Reguera Delgado cdbf5c
action. With this information you can create your own module
Alain Reguera Delgado cdbf5c
environment, already. However, when your module is getting too much
Alain Reguera Delgado cdbf5c
complicated you probably want to divide it in smaller pieces that you
Alain Reguera Delgado cdbf5c
can execute accordingly, based on the purpose you defined for it. Such
Alain Reguera Delgado cdbf5c
kind of division can be implemented as described in
Alain Reguera Delgado cdbf5c
<<module-optimization>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Summary
Alain Reguera Delgado cdbf5c
~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This section has covered basic concepts related to module environment
Alain Reguera Delgado cdbf5c
inside *centos-art.sh* script. The next section takes these concepts
Alain Reguera Delgado cdbf5c
and focuses on the implementation of them. Once you finish it, you
Alain Reguera Delgado cdbf5c
should be able of writing your own module environments from scratch
Alain Reguera Delgado cdbf5c
inside *centos-art.sh* script.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-implementation]]
Alain Reguera Delgado cdbf5c
Module Implementation
Alain Reguera Delgado cdbf5c
---------------------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The *centos-art.sh* script implements module environments inside the
Alain Reguera Delgado cdbf5c
``+Modules+'' directory, as described in <<module-structure>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-implementation-parent]]
Alain Reguera Delgado cdbf5c
Parent Modules
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
For example, consider the creation of a module named *hello*. The
Alain Reguera Delgado cdbf5c
purpose of this module is to print a greeting message to standard
Alain Reguera Delgado cdbf5c
output and then exit successfully. To create such a module, we need to
Alain Reguera Delgado cdbf5c
create a directory named ``Hello'' inside the ``Modules'' directory
Alain Reguera Delgado cdbf5c
and put an initialization file named ``hello.sh'' inside it.  Because
Alain Reguera Delgado cdbf5c
we want to execute the *hello* module from *centos-art.sh* script
Alain Reguera Delgado cdbf5c
command-line, we put it in the first level of directories of +Modules+
Alain Reguera Delgado cdbf5c
directory. See <<parent-module-layout>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[parent-module-layout]]
Alain Reguera Delgado cdbf5c
.Directory layout used by parent modules
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
.
Alain Reguera Delgado cdbf5c
|-- COPYING                     <1>
Alain Reguera Delgado cdbf5c
|-- Locales/                    <2>
Alain Reguera Delgado cdbf5c
|-- Manuals/                    <3>
Alain Reguera Delgado cdbf5c
|-- Modules/                    <4>
Alain Reguera Delgado cdbf5c
|   `-- Hello/                  <5>
Alain Reguera Delgado cdbf5c
|       |-- hello.sh            <6>
Alain Reguera Delgado cdbf5c
|       `-- hello_getOptions.sh <7>
Alain Reguera Delgado cdbf5c
|-- Scripts/                    <8>
Alain Reguera Delgado cdbf5c
|-- centos-art.conf.sh          <9>
Alain Reguera Delgado cdbf5c
`-- centos-art.sh               <10>
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<1> Script's copying conditions.
Alain Reguera Delgado cdbf5c
<2> Script's localization files.
Alain Reguera Delgado cdbf5c
<3> Script's documentation files.
Alain Reguera Delgado cdbf5c
<4> Script's modules. Here is where you store parent modules.
Alain Reguera Delgado cdbf5c
<5> Parent directory of module named hello.
Alain Reguera Delgado cdbf5c
<6> Initialization file of module named hello.
Alain Reguera Delgado cdbf5c
<7> Function related to module named hello.
Alain Reguera Delgado cdbf5c
<8> Script's global functions.
Alain Reguera Delgado cdbf5c
<9> Script's configuration file.
Alain Reguera Delgado cdbf5c
<10> Script's initialization file.
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<<parent-module-layout>> presents a complete module layout you can use
Alain Reguera Delgado cdbf5c
as reference to create your own module implementations. However, it is
Alain Reguera Delgado cdbf5c
not complete yet.  At this point, when you execute *centos-art.sh*, it
Alain Reguera Delgado cdbf5c
is able to find out *hello* module's initialization file and execute
Alain Reguera Delgado cdbf5c
it but that prints an error message because the initialization file
Alain Reguera Delgado cdbf5c
doesn't have a function definition inside. It is completely empty.  In
Alain Reguera Delgado cdbf5c
order for *centos-art.sh* script to do something useful, you need to
Alain Reguera Delgado cdbf5c
write a function definition inside the initialization file, as
Alain Reguera Delgado cdbf5c
described in <<module-init-file>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-init-file]]
Alain Reguera Delgado cdbf5c
The Initialization File
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The module's initialization file contains the module's main function
Alain Reguera Delgado cdbf5c
definition and a comment describing what it does on top of it.  This
Alain Reguera Delgado cdbf5c
comment includes a small description about what the function does, a
Alain Reguera Delgado cdbf5c
written by section, the copyright note and the legal status of the
Alain Reguera Delgado cdbf5c
file. The function definition is set later and must be written using
Alain Reguera Delgado cdbf5c
the long definition format (i.e., it must begin with the word
Alain Reguera Delgado cdbf5c
``+function+,'' then the function name, and finally the ``+{+''
Alain Reguera Delgado cdbf5c
character).  The name of the function is exactly the same of the
Alain Reguera Delgado cdbf5c
initialization file but without the +.sh+ extension. These conditions
Alain Reguera Delgado cdbf5c
are required in order for *centos-art.sh* script to execute the
Alain Reguera Delgado cdbf5c
function definition and destroy it when it is no longer used.  See
Alain Reguera Delgado cdbf5c
<<initialization-file>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The function definition is where you write all the commands you want
Alain Reguera Delgado cdbf5c
the module runs, once executed.  The function definition can be as
Alain Reguera Delgado cdbf5c
simple as just one single line of code or as complex as you can
Alain Reguera Delgado cdbf5c
imagine. It is the place where you express your solutions. However,
Alain Reguera Delgado cdbf5c
when writing initialization files, it is considered a good practice to
Alain Reguera Delgado cdbf5c
avoid any sort of complexity.  Instead, try to write small and simple
Alain Reguera Delgado cdbf5c
initialization files.  In case you notice the initialization file is
Alain Reguera Delgado cdbf5c
growing up inevitably, you can reduce its code by refactoring it.  To
Alain Reguera Delgado cdbf5c
do this, you can use resources like module related functions and child
Alain Reguera Delgado cdbf5c
modules. These resources are described in <<module-optimization>>, and
Alain Reguera Delgado cdbf5c
they help you to keep the initialization file in a clean state, easy
Alain Reguera Delgado cdbf5c
to understand, maintain and debug.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[initialization-file]]
Alain Reguera Delgado cdbf5c
.Initialization file used by hello module
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
#!/bin/bash
Alain Reguera Delgado cdbf5c
######################################################################
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
#   hello.sh -- Print out greetings to standard output and exit
Alain Reguera Delgado cdbf5c
#   successfully.
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
#   Written by:
Alain Reguera Delgado cdbf5c
#   * Alain Reguera Delgado <al@centos.org.cu>, 2013
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
# Copyright (C) 2009-2013 The CentOS Artwork SIG
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
# This program is free software; you can redistribute it and/or modify
Alain Reguera Delgado cdbf5c
# it under the terms of the GNU General Public License as published by
Alain Reguera Delgado cdbf5c
# the Free Software Foundation; either version 2 of the License, or (at
Alain Reguera Delgado cdbf5c
# your option) any later version.
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
# This program is distributed in the hope that it will be useful, but
Alain Reguera Delgado cdbf5c
# WITHOUT ANY WARRANTY; without even the implied warranty of
Alain Reguera Delgado cdbf5c
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Alain Reguera Delgado cdbf5c
# General Public License for more details.
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
# You should have received a copy of the GNU General Public License
Alain Reguera Delgado cdbf5c
# along with this program; if not, write to the Free Software
Alain Reguera Delgado cdbf5c
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Alain Reguera Delgado cdbf5c
#
Alain Reguera Delgado cdbf5c
######################################################################
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
function hello {
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    tcar_printMessage "`gettext "Hello, World!"`" --as-stdout-line
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
}
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The function definition described in <<initialization-file>> uses the
Alain Reguera Delgado cdbf5c
*tcar_printMessage* global function to print localized versions of the
Alain Reguera Delgado cdbf5c
string ``Hello, World!'' to standard output. Because there isn't no
Alain Reguera Delgado cdbf5c
other command in the function definition, when the greeting message is
Alain Reguera Delgado cdbf5c
printed out, *centos-art.sh* destroys the *hello* module and exit
Alain Reguera Delgado cdbf5c
successfully. This process is more visible when also pass the
Alain Reguera Delgado cdbf5c
*--debug* option. See <<debug-parent-modules>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Summary
Alain Reguera Delgado cdbf5c
~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Congratulations! You've implemented a module environment inside
Alain Reguera Delgado cdbf5c
*centos-art.sh* script. With the information you have so far, you are
Alain Reguera Delgado cdbf5c
able to create your own module environment implementations. The next
Alain Reguera Delgado cdbf5c
section delves into available resources you can use to simplify module
Alain Reguera Delgado cdbf5c
environments when the initialization file starts growing inevitably
Alain Reguera Delgado cdbf5c
and complexity daemons begin hammering your head.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-optimization]]
Alain Reguera Delgado cdbf5c
Module Optimization
Alain Reguera Delgado cdbf5c
-------------------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The *centos-art.sh* script provides four resources you can use to
Alain Reguera Delgado cdbf5c
optimize your module implementations. These resources are ``related
Alain Reguera Delgado cdbf5c
functions,'' ``child modules,'' ``sibling modules'' and ``recursive
Alain Reguera Delgado cdbf5c
modules''.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[related-functions]]
Alain Reguera Delgado cdbf5c
Related Functions
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Related functions are very useful when you need to simplify the
Alain Reguera Delgado cdbf5c
function definition of one initialization file. For example, consider
Alain Reguera Delgado cdbf5c
extending the *hello* module so it is able to interpret arguments
Alain Reguera Delgado cdbf5c
passed through the command-line.  Now, inside the initialization file,
Alain Reguera Delgado cdbf5c
we have some variable definitions, one function call to a module
Alain Reguera Delgado cdbf5c
related function named *hello_getOptions*, and a decision on how the
Alain Reguera Delgado cdbf5c
greeting message must be printed out based on the collected actions.
Alain Reguera Delgado cdbf5c
See <<initialization-file-extended>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[initialization-file-extended]]
Alain Reguera Delgado cdbf5c
.Initialization file used by hello module (extended)
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
function hello {
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Define default greeting message.
Alain Reguera Delgado cdbf5c
    local HELLO_WORLD="`gettext "Hello, World!"`"
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Define actions variable. Here is where actions related to
Alain Reguera Delgado cdbf5c
    # module-specific options are stored in for further processing.
Alain Reguera Delgado cdbf5c
    local ACTIONS=''
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Interpret module-specific options and store related actions.
Alain Reguera Delgado cdbf5c
    hello_getOptions
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Print greeting message
Alain Reguera Delgado cdbf5c
    if [[ -z ${ACTIONS} ]];then
Alain Reguera Delgado cdbf5c
        # Using parent module.
Alain Reguera Delgado cdbf5c
        tcar_printMessage "${HELLO_WORLD}" --as-stdout-line
Alain Reguera Delgado cdbf5c
    else
Alain Reguera Delgado cdbf5c
        # Using child module.
Alain Reguera Delgado cdbf5c
        tcar_setModuleEnvironment -m 'output' -t 'child'
Alain Reguera Delgado cdbf5c
    fi
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
}
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
When you execute the command *centos-art.sh hello* with the
Alain Reguera Delgado cdbf5c
*--greeting=hi* argument, *centos-art.sh* stores module-specific
Alain Reguera Delgado cdbf5c
arguments inside the +TCAR_MODULE_ARGUMENT+ variable, creates a list
Alain Reguera Delgado cdbf5c
of all function definitions inside the module directory and exports
Alain Reguera Delgado cdbf5c
them.  This includes the function definition of the initialization
Alain Reguera Delgado cdbf5c
file itself.  Then *centos-art.sh* executes the function definition
Alain Reguera Delgado cdbf5c
set inside the initialization file and leaves all other function
Alain Reguera Delgado cdbf5c
definitions, already in memory, waiting for further execution. At this
Alain Reguera Delgado cdbf5c
point, the *hello* initialization function sets some default values
Alain Reguera Delgado cdbf5c
and execute the *hello_getOptions* function to parse all the arguments
Alain Reguera Delgado cdbf5c
passed through the command-line and redefines the +ACTIONS+ variable
Alain Reguera Delgado cdbf5c
based on them. Using the +ACTIONS+ variables it decides whether to
Alain Reguera Delgado cdbf5c
print the greeting message immediately or execute the child modules
Alain Reguera Delgado cdbf5c
named *output* so it decides what to do with the information collected
Alain Reguera Delgado cdbf5c
so far.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<<hello_getOptions-definition>> defines the options you can pass to
Alain Reguera Delgado cdbf5c
*hello* module and the associated actions they must perform for each
Alain Reguera Delgado cdbf5c
of them. Actions aren't immediately executed here. Instead, they are
Alain Reguera Delgado cdbf5c
stored in the +ACTIONS+ variable for further processing (e.g., we
Alain Reguera Delgado cdbf5c
store the names of the modules we want to execute later). The
Alain Reguera Delgado cdbf5c
+ACTIONS+ variable was defined in the initialization file so it has a
Alain Reguera Delgado cdbf5c
global scope inside the module environment and is reachable from any
Alain Reguera Delgado cdbf5c
related function executed inside it.  Storing the actions this way
Alain Reguera Delgado cdbf5c
lets the *hello* module to collect information about different actions
Alain Reguera Delgado cdbf5c
and execute them all in just one command.  When all options have been
Alain Reguera Delgado cdbf5c
parsed, only non-option arguments remain in the +TCAR_MODULE_ARGUMENT+
Alain Reguera Delgado cdbf5c
variable.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[hello_getOptions-definition]]
Alain Reguera Delgado cdbf5c
.Related function definition (hello_getOptions)
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
function hello_getOptions {
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Define short options we want to support.
Alain Reguera Delgado cdbf5c
    local ARGSS="h::,v,g:,l,u,c,r"
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Define long options we want to support.
Alain Reguera Delgado cdbf5c
    local ARGSL="help::,version,greeting:,lower,upper,camel,random"
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Redefine arguments using getopt(1) command parser.
Alain Reguera Delgado cdbf5c
    tcar_setModuleArguments
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Reset positional parameters on this function, using output
Alain Reguera Delgado cdbf5c
    # produced from (getopt) arguments parser.
Alain Reguera Delgado cdbf5c
    eval set -- "${TCAR_MODULE_ARGUMENT}"
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Look for options passed through command-line.
Alain Reguera Delgado cdbf5c
    while true; do
Alain Reguera Delgado cdbf5c
        case "${1}" in
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -h | --help )
Alain Reguera Delgado cdbf5c
                tcar_printHelp "${2}"
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -v | --version )
Alain Reguera Delgado cdbf5c
                tcar_printVersion "${TCAR_MODULE_NAME}"
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -g | --greeting )
Alain Reguera Delgado cdbf5c
                HELLO_WORLD="${2:-${HELLO_WORLD}}"
Alain Reguera Delgado cdbf5c
                shift 2
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -l | --lower )
Alain Reguera Delgado cdbf5c
                ACTIONS="lower ${ACTIONS}"
Alain Reguera Delgado cdbf5c
                shift 1
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -u | --upper )
Alain Reguera Delgado cdbf5c
                ACTIONS="upper ${ACTIONS}"
Alain Reguera Delgado cdbf5c
                shift 1
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -c | --camel )
Alain Reguera Delgado cdbf5c
                ACTIONS="camel ${ACTIONS}"
Alain Reguera Delgado cdbf5c
                shift 1
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -r | --random )
Alain Reguera Delgado cdbf5c
                ACTIONS="random ${ACTIONS}"
Alain Reguera Delgado cdbf5c
                shift 1
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
            -- )
Alain Reguera Delgado cdbf5c
                shift 1
Alain Reguera Delgado cdbf5c
                break
Alain Reguera Delgado cdbf5c
                ;;
Alain Reguera Delgado cdbf5c
        esac
Alain Reguera Delgado cdbf5c
    done
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
    # Redefine arguments using current positional parameters. Only
Alain Reguera Delgado cdbf5c
    # paths should remain as arguments, at this point.
Alain Reguera Delgado cdbf5c
    TCAR_MODULE_ARGUMENT="${@}"
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
}
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[IMPORTANT]
Alain Reguera Delgado cdbf5c
<<hello_getOptions-definition>> presents the standard construction we
Alain Reguera Delgado cdbf5c
use inside *centos-art.sh* script for parsing arguments passed through
Alain Reguera Delgado cdbf5c
the command-line in a per-module basis.  As convention, all the parent
Alain Reguera Delgado cdbf5c
modules you write must be able to interpret the *--help* and
Alain Reguera Delgado cdbf5c
*--version* options using the construction described here.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Related functions are very useful when you are refactoring the
Alain Reguera Delgado cdbf5c
initialization file of a module. However, they aren't so efficient
Alain Reguera Delgado cdbf5c
when you need to execute them at demand (e.g., based on specific
Alain Reguera Delgado cdbf5c
conditions). When a module is executed, related functions are exported
Alain Reguera Delgado cdbf5c
to *centos-art.sh* script execution environment. They remain there,
Alain Reguera Delgado cdbf5c
consuming memory, until the module they belong to is destroyed. If you
Alain Reguera Delgado cdbf5c
create a related function and never execute it, it will consume
Alain Reguera Delgado cdbf5c
memory, as well. So, use related functions when you are absolutely
Alain Reguera Delgado cdbf5c
sure they will be executed at some point, in one single iteration of
Alain Reguera Delgado cdbf5c
*centos-art.sh* script.  If you need to execute functions at demand,
Alain Reguera Delgado cdbf5c
use child modules, instead.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[child-modules]]
Alain Reguera Delgado cdbf5c
Child Modules
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Child modules are initiated by executing the
Alain Reguera Delgado cdbf5c
*tcar_setModuleEnvironment* function with the *-t child* option set on
Alain Reguera Delgado cdbf5c
it.  Child modules have the characteristic of being nested modules.
Alain Reguera Delgado cdbf5c
They cannot be executed from the command-line. Normally, child modules
Alain Reguera Delgado cdbf5c
are executed from parent modules but they can be executed from other
Alain Reguera Delgado cdbf5c
child modules, too.  When several child modules are executed in one
Alain Reguera Delgado cdbf5c
single iteration of *centos-art.sh*, they create a chain of modules.
Alain Reguera Delgado cdbf5c
A chain of modules is very useful in situations where you want to
Alain Reguera Delgado cdbf5c
divide one large task into smaller tasks and also control which of
Alain Reguera Delgado cdbf5c
these smaller tasks is executed based on specific conditions (e.g.,
Alain Reguera Delgado cdbf5c
you may want to render images or documentation, but not both, in one
Alain Reguera Delgado cdbf5c
single iteration of *centos-art.sh* script).  In a chain of modules,
Alain Reguera Delgado cdbf5c
lower modules in the chain (those started last) have access to
Alain Reguera Delgado cdbf5c
information set by modules higher in the chain (those started first),
Alain Reguera Delgado cdbf5c
but not the opposite. When processing information this way, modules
Alain Reguera Delgado cdbf5c
aren't destroyed until the last module executed in the chain has
Alain Reguera Delgado cdbf5c
finished its work (e.g., all the commands inside it have been
Alain Reguera Delgado cdbf5c
executed). At that point, child modules are destroyed in the reverse
Alain Reguera Delgado cdbf5c
order they were executed.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
For example, when you execute the *hello* module with both *--debug*
Alain Reguera Delgado cdbf5c
and *--upper* option, *centos-art.sh* script creates a chain of three
Alain Reguera Delgado cdbf5c
modules to produce the greeting message.  Firstly, it begins by
Alain Reguera Delgado cdbf5c
executing the parent module named *hello*, then it continues with the
Alain Reguera Delgado cdbf5c
child module named *output* which in turn executes the child module
Alain Reguera Delgado cdbf5c
name *lower* to finally print the expected greeting message.  In this
Alain Reguera Delgado cdbf5c
example, the module named *lower* is the last module in the chain of
Alain Reguera Delgado cdbf5c
executed modules. It has access to all information defined by earlier
Alain Reguera Delgado cdbf5c
modules (e.g., in *hello* and *output* modules) and none of its earlier
Alain Reguera Delgado cdbf5c
modules will be destroyed until it has finished its work. This process
Alain Reguera Delgado cdbf5c
becomes more visible when you take a look at <<debug-child-modules>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[debug-child-modules]]
Alain Reguera Delgado cdbf5c
.Debugging execution of child modules
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT =========================>      [0] | main
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_NAME                [0]=hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_TYPE                parent
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_ARGUMENT            --upper --greeting=hi  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAIN                      hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT export -f                       hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT export -f                       hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT ------------------------->      hello --upper --greeting=hi  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT =========================>      [1] | hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_NAME                [1]=output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_TYPE                child
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_LIST                output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/output.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAIN                      output.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT export -f                       output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT ------------------------->      output  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT =========================>      [2] | output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_NAME                [2]=upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_TYPE                child
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:41 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Upper/upper.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT TEXTDOMAIN                      upper.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT export -f                       upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT ------------------------->      upper  
Alain Reguera Delgado cdbf5c
HI             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT <-------------------------      upper  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT <=========================      [2] | output 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT <-------------------------      output  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT <=========================      [1] | hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT <-------------------------      hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT unset -f                        hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:52:42 PM CDT <=========================      [0] | main 
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The module environment described in <<debug-child-modules>> shows the
Alain Reguera Delgado cdbf5c
child modules' ability of reducing scope as they get deeper in the
Alain Reguera Delgado cdbf5c
chain of executed modules. However, child modules lack the possibility
Alain Reguera Delgado cdbf5c
of nest modules that share the same scope. For example, in the *hello*
Alain Reguera Delgado cdbf5c
module described above, you cannot execute the modules *lower*  or
Alain Reguera Delgado cdbf5c
*upper* from *camel* module, as if they were child modules of it.
Alain Reguera Delgado cdbf5c
That is not possible because they all have the same scope, which is,
Alain Reguera Delgado cdbf5c
to print the greeting message to standard output. Child modules are
Alain Reguera Delgado cdbf5c
conceived to reduce the module scope as new child modules are
Alain Reguera Delgado cdbf5c
executed. When you need to execute new module environments and, also,
Alain Reguera Delgado cdbf5c
retain the last scope from which the new module is executed, you need
Alain Reguera Delgado cdbf5c
to use ``_sibling modules_,'' instead.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[sibling-modules]]
Alain Reguera Delgado cdbf5c
Sibling Modules
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Sibling modules are initiated by executing the
Alain Reguera Delgado cdbf5c
*tcar_setModuleEnvironment* function with the *-t sibling* option set
Alain Reguera Delgado cdbf5c
on it.  Sibling modules are another type of nested modules but, in
Alain Reguera Delgado cdbf5c
contrast with child modules, sibling modules cannot be executed from
Alain Reguera Delgado cdbf5c
parent modules. Normally, sibling modules are executed from other
Alain Reguera Delgado cdbf5c
sibling modules but, considering the context, they can be executed
Alain Reguera Delgado cdbf5c
from child module too, to initiate sibling processing. When several
Alain Reguera Delgado cdbf5c
siblings modules are executed, they also build a chain of modules. In
Alain Reguera Delgado cdbf5c
contrast with the chain of child modules, the chain of sibling modules
Alain Reguera Delgado cdbf5c
destroys the last sibling module executed before executing the next
Alain Reguera Delgado cdbf5c
sibling module. This make the chain to stop its growing at sibling
Alain Reguera Delgado cdbf5c
module processing, unless you call a child module from a sibling
Alain Reguera Delgado cdbf5c
module. In this case, the chain expansion would continue as long as
Alain Reguera Delgado cdbf5c
the number of child modules you execute. This process becomes more
Alain Reguera Delgado cdbf5c
visible when you take a look at <<debug-sibling-modules>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
In <<debug-sibling-modules>>, we've executed the *hello* module with
Alain Reguera Delgado cdbf5c
the *--greeting=hi*, *--camel*, and *--debug* options. In this
Alain Reguera Delgado cdbf5c
example, *centos-art.sh* script executes the *hello* module then the
Alain Reguera Delgado cdbf5c
*output* module which in turn executes the *camel* module. At this
Alain Reguera Delgado cdbf5c
point, can appreciate how the chain of modules stop growing. Observe
Alain Reguera Delgado cdbf5c
that *camel* module has gained the position 2 in the chain of modules
Alain Reguera Delgado cdbf5c
and executes the *upper* module which takes the position 3, as
Alain Reguera Delgado cdbf5c
expected. Now, when *upper* module finishes its work it is destroyed
Alain Reguera Delgado cdbf5c
and the module's counter is reset to its previous value which is 2
Alain Reguera Delgado cdbf5c
(the one set by *camel* module). Then, *camel* executes the *lower*
Alain Reguera Delgado cdbf5c
module which take position 3 at the chain of modules until it
Alain Reguera Delgado cdbf5c
finishes. When it finishes, the *camel* module finishes its work and
Alain Reguera Delgado cdbf5c
is destroyed, then *output*, then *hello*.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[debug-sibling-modules]]
Alain Reguera Delgado cdbf5c
.Debugging execution of sibling modules
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT =========================>      [0] | main
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_NAME                [0]=hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_TYPE                parent
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_ARGUMENT            --camel --greeting=hi  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TEXTDOMAIN                      hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:42 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT export -f                       hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT export -f                       hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      hello --camel --greeting=hi  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [1] | hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [1]=output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                child
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/output.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAIN                      output.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT export -f                       output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      output  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [2] | output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [2]=camel
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                child
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Camel
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Camel/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Camel/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Camel/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Camel/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Camel/camel.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAIN                      camel.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Camel/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT export -f                       camel
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      camel  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [3] | camel
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [3]=upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                sibling
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Upper/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Upper/upper.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAIN                      upper.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Upper/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT export -f                       upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT ------------------------->      upper  
Alain Reguera Delgado cdbf5c
H              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT <-------------------------      upper  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT unset -f                        upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT <=========================      [3] | camel 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT =========================>      [3] | camel
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_NAME                [3]=lower
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_TYPE                sibling
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Lower
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:43 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Lower/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Lower/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Lower/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Lower/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Lower/lower.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT TEXTDOMAIN                      lower.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Lower/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT export -f                       lower
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT ------------------------->      lower  
Alain Reguera Delgado cdbf5c
i              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      lower  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        lower
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [3] | camel 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      camel  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        camel
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [2] | output 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      output  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [1] | hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <-------------------------      hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT unset -f                        hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:51:44 PM CDT <=========================      [0] | main
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<<debug-sibling-modules>> shows a single iteration of *centos-art.sh*
Alain Reguera Delgado cdbf5c
script executing different types of modules. Normally, one module is
Alain Reguera Delgado cdbf5c
executed at some point and destroyed at the same point when it has
Alain Reguera Delgado cdbf5c
finished its work, however, what if the next immediate module you are
Alain Reguera Delgado cdbf5c
about to execute is the same module you are about to destroyed? This
Alain Reguera Delgado cdbf5c
is, you need to execute the last module in the chain of executed
Alain Reguera Delgado cdbf5c
modules again, but, this time, from itself.  In cases like this, the
Alain Reguera Delgado cdbf5c
*centos-art.sh* script doesn't destroy the last module.  It cannot,
Alain Reguera Delgado cdbf5c
because you are certainly executing a new module from itself, so it
Alain Reguera Delgado cdbf5c
has to wait for this new call to finish in order to be destroyed. This
Alain Reguera Delgado cdbf5c
kind of processing is known as _processing modules recursively._
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[recursive-modules]]
Alain Reguera Delgado cdbf5c
Recursive Modules
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
When one module environment executes itself we are in presence of a
Alain Reguera Delgado cdbf5c
recursive module execution. The execution of modules recursively
Alain Reguera Delgado cdbf5c
doesn't destroy the last module in the chain of executed modules and
Alain Reguera Delgado cdbf5c
doesn't increment or decrement the module counter either. The module
Alain Reguera Delgado cdbf5c
counter is somehow frozen until a different module environment is
Alain Reguera Delgado cdbf5c
executed. In these cases, the last module environment remains in
Alain Reguera Delgado cdbf5c
memory for the new module execution to make use of. This process
Alain Reguera Delgado cdbf5c
becomes more visible when you take a look at
Alain Reguera Delgado cdbf5c
<<debug-recursive-modules>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[CAUTION]
Alain Reguera Delgado cdbf5c
When you execute modules recursively, you should be very careful not
Alain Reguera Delgado cdbf5c
to get trapped into an endless loop.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
In <<debug-recursive-modules>>, we've executed the *hello* module with
Alain Reguera Delgado cdbf5c
the *--greeting=hello*, *--random*, and *--debug* options. In this
Alain Reguera Delgado cdbf5c
example, *centos-art.sh* script executes a parent module named *hello*
Alain Reguera Delgado cdbf5c
which in turn executes a child module named *output* which in turn
Alain Reguera Delgado cdbf5c
executes a child module named *random*. At this point, the *random*
Alain Reguera Delgado cdbf5c
modules executes itself five times (the number of characters passed as
Alain Reguera Delgado cdbf5c
value to greeting option) to print out random letters from the
Alain Reguera Delgado cdbf5c
greeting message. The output may have no much sense on itself but the
Alain Reguera Delgado cdbf5c
related debugging information helps to understand the execution of
Alain Reguera Delgado cdbf5c
modules recursively.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[debug-recursive-modules]]
Alain Reguera Delgado cdbf5c
.Processing execution of modules recursively
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT =========================>      [0] | main
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_NAME                [0]=hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_TYPE                parent
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_ARGUMENT            --random --greeting=Hello  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_LIST                hello|help|locale|prepare|render|tuneup|vcs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:03 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAIN                      hello.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT export -f                       hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT export -f                       hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ------------------------->      hello --random --greeting=Hello  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT =========================>      [1] | hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_NAME                [1]=output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_TYPE                child
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_LIST                output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/output.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAIN                      output.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT export -f                       output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ------------------------->      output  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT =========================>      [2] | output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_BASEDIR             Automation/Modules/Hello/Modules/Output/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_NAME                [2]=random
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_TYPE                child
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_ARGUMENT             
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_LIST                camel|lower|random|upper
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR                 Automation/Modules/Hello/Modules/Output/Modules/Random
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MODULES         Automation/Modules/Hello/Modules/Output/Modules/Random/Modules
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_MANUALS         Automation/Modules/Hello/Modules/Output/Modules/Random/Manuals
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_LOCALES         Automation/Modules/Hello/Modules/Output/Modules/Random/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_DIR_CONFIGS         Automation/Modules/Hello/Modules/Output/Modules/Random/Configs
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TCAR_MODULE_INIT_FILE           Automation/Modules/Hello/Modules/Output/Modules/Random/random.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAIN                      random.sh
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT TEXTDOMAINDIR                   Automation/Modules/Hello/Modules/Output/Modules/Random/Locales
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT export -f                       random
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ------------------------->      random  
Alain Reguera Delgado cdbf5c
H              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  
Alain Reguera Delgado cdbf5c
H              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  
Alain Reguera Delgado cdbf5c
l              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  
Alain Reguera Delgado cdbf5c
l              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT ~~~~~~~~~~~~~~~~~~~~~~~~~>      random  
Alain Reguera Delgado cdbf5c
H              
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT <-------------------------      random  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT unset -f                        random
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT <=========================      [2] | output 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:04 PM CDT <-------------------------      output  
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:05 PM CDT unset -f                        output
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:05 PM CDT <=========================      [1] | hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:05 PM CDT <-------------------------      hello 
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:05 PM CDT unset -f                        hello
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:05 PM CDT unset -f                        hello_getOptions
Alain Reguera Delgado cdbf5c
Thu 10 Oct 2013 11:50:05 PM CDT <=========================      [0] | main 
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Recursive execution of modules occurs only when the module you are
Alain Reguera Delgado cdbf5c
executing is considered sibling of the last module executed in the
Alain Reguera Delgado cdbf5c
chain of executed modules and they both have the same name. The fact
Alain Reguera Delgado cdbf5c
that no variable name is printed out in <<debug-recursive-modules>>
Alain Reguera Delgado cdbf5c
means that they were not created. The arrows change from +->+ to +~>+,
Alain Reguera Delgado cdbf5c
means that module's related functions weren't exported for the new
Alain Reguera Delgado cdbf5c
module execution either. It also means that the initialization script
Alain Reguera Delgado cdbf5c
is reusing both related functions and variables from the last module
Alain Reguera Delgado cdbf5c
environment in the chain of executed modules. In this case the
Alain Reguera Delgado cdbf5c
*random* module.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Summary
Alain Reguera Delgado cdbf5c
~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This section covered the resources you can use to optimize module
Alain Reguera Delgado cdbf5c
environments inside *centos-art.sh* script. The next section
Alain Reguera Delgado cdbf5c
summarizes the base files and directories you might find inside one
Alain Reguera Delgado cdbf5c
module environment.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-structure]]
Alain Reguera Delgado cdbf5c
Module Structure
Alain Reguera Delgado cdbf5c
----------------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The module structure takes place at the root location of
Alain Reguera Delgado cdbf5c
*centos-art.sh* script, specifically, in a directory named +Modules+.
Alain Reguera Delgado cdbf5c
The +Modules+ directory at *centos-art.sh* root location is the
Alain Reguera Delgado cdbf5c
highest level which you can store modules in.  Modules stored in this
Alain Reguera Delgado cdbf5c
location are known as parent modules. Parent modules can optimize
Alain Reguera Delgado cdbf5c
their structure by using related functions, child modules, sibling
Alain Reguera Delgado cdbf5c
modules and recursive modules. Basically, all these types of modules
Alain Reguera Delgado cdbf5c
share the same structure.  They all have function files and,
Alain Reguera Delgado cdbf5c
optionally, module related stuff like locales, documentation,
Alain Reguera Delgado cdbf5c
configuration and dependent modules. See <<module-directory-layout>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[IMPORTANT]
Alain Reguera Delgado cdbf5c
From version 0.7 on, child modules no longer have +Locales+, +Manuals+
Alain Reguera Delgado cdbf5c
and +Configs+ directories inside. Only initialization files, related
Alain Reguera Delgado cdbf5c
functions and +Modules+ directory are supported inside child modules.
Alain Reguera Delgado cdbf5c
See https://centos.org.cu/bugs/view.php?id=114[Bug 114].
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-directory-layout]]
Alain Reguera Delgado cdbf5c
.The directory structure of hello module
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
.
Alain Reguera Delgado cdbf5c
|-- COPYING
Alain Reguera Delgado cdbf5c
|-- Locales/
Alain Reguera Delgado cdbf5c
|-- Manuals/
Alain Reguera Delgado cdbf5c
|-- Modules/
Alain Reguera Delgado cdbf5c
|   `-- Hello/                          <1>
Alain Reguera Delgado cdbf5c
|       |-- Locales
Alain Reguera Delgado cdbf5c
|       |   |-- es_ES
Alain Reguera Delgado cdbf5c
|       |   |   |-- LC_MESSAGES
Alain Reguera Delgado cdbf5c
|       |   |   |   `-- hello.sh.mo     <2>
Alain Reguera Delgado cdbf5c
|       |   |   `-- hello.sh.po
Alain Reguera Delgado cdbf5c
|       |   `-- hello.sh.pot
Alain Reguera Delgado cdbf5c
|       |-- Manuals
Alain Reguera Delgado cdbf5c
|       |   |-- hello.asciidoc
Alain Reguera Delgado cdbf5c
|       |   |-- man1
Alain Reguera Delgado cdbf5c
|       |   |   `-- hello.1             <3>
Alain Reguera Delgado cdbf5c
|       |   `-- render.conf             <4>
Alain Reguera Delgado cdbf5c
|       |-- Modules
Alain Reguera Delgado cdbf5c
|       |   `-- Output                  <5>
Alain Reguera Delgado cdbf5c
|       |       |-- Modules
Alain Reguera Delgado cdbf5c
|       |       |   |-- Camel
Alain Reguera Delgado cdbf5c
|       |       |   |   `-- camel.sh
Alain Reguera Delgado cdbf5c
|       |       |   |-- Lower           <6>
Alain Reguera Delgado cdbf5c
|       |       |   |   `-- lower.sh    <7>
Alain Reguera Delgado cdbf5c
|       |       |   |-- Random
Alain Reguera Delgado cdbf5c
|       |       |   |   `-- random.sh
Alain Reguera Delgado cdbf5c
|       |       |   `-- Upper
Alain Reguera Delgado cdbf5c
|       |       |       `-- upper.sh
Alain Reguera Delgado cdbf5c
|       |       `-- output.sh           <8>
Alain Reguera Delgado cdbf5c
|       |-- hello.sh                    <9>
Alain Reguera Delgado cdbf5c
|       `-- hello_getOptions.sh         <10>
Alain Reguera Delgado cdbf5c
|-- Scripts/
Alain Reguera Delgado cdbf5c
|-- centos-art.conf.sh
Alain Reguera Delgado cdbf5c
`-- centos-art.sh
Alain Reguera Delgado cdbf5c
----------------------------------------------------------------------
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<1> Child module of *centos-art.sh* script and parent module of
Alain Reguera Delgado cdbf5c
*output* module.
Alain Reguera Delgado cdbf5c
<2> Spanish translated strings of *hello* module.
Alain Reguera Delgado cdbf5c
<3> Manpage shown when you request help of *hello* module.
Alain Reguera Delgado cdbf5c
<4> Configuration file used to produce the manpage of *hello* module.
Alain Reguera Delgado cdbf5c
<5> Child module of *hello* module and parent module of *camel,*
Alain Reguera Delgado cdbf5c
*lower,* *random* and *upper* modules.
Alain Reguera Delgado cdbf5c
<6> Child module of *output* module and sibling module of *camel,*
Alain Reguera Delgado cdbf5c
*random* and *upper* module.
Alain Reguera Delgado cdbf5c
<7> Initialization file of *lower* module.
Alain Reguera Delgado cdbf5c
<8> Initialization file of *output* module.
Alain Reguera Delgado cdbf5c
<9> Initialization file of *hello* module.
Alain Reguera Delgado cdbf5c
<10> Function file related to *hello* module.
Alain Reguera Delgado cdbf5c
======================================================================
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
<<module-directory-layout>> presents a complete structure for module
Alain Reguera Delgado cdbf5c
environments you can use as reference for writing your own modules. It
Alain Reguera Delgado cdbf5c
begins with a parent module directory named ``Hello'' which contains
Alain Reguera Delgado cdbf5c
an initialization file (``hello.sh'') and one related function file
Alain Reguera Delgado cdbf5c
(``hello_getOptions.sh''). These files work together with a child
Alain Reguera Delgado cdbf5c
module named *output* which in turn has four child modules inside
Alain Reguera Delgado cdbf5c
named *camel,* *lower,* *random,* and *upper.* The +Locales+ directory
Alain Reguera Delgado cdbf5c
contains the required information to print *hello* messages in
Alain Reguera Delgado cdbf5c
different languages (e.g., it only supports Spanish language in our
Alain Reguera Delgado cdbf5c
example, but it can be extended to other languages as needed).  The
Alain Reguera Delgado cdbf5c
+Manuals+ directory contains all the files required to produce
Alain Reguera Delgado cdbf5c
documentation for the *hello* module (e.g., the information you read
Alain Reguera Delgado cdbf5c
when provide the *--help* option in the command-line).
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The Function Files
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
The function files are used to create the initialization file of a
Alain Reguera Delgado cdbf5c
module and the related functions of it.  As convention, both
Alain Reguera Delgado cdbf5c
initialization file and related function files are stored in the
Alain Reguera Delgado cdbf5c
module's directory, see <<module-directory-layout>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
At execution time, the definition of related function are exported to
Alain Reguera Delgado cdbf5c
*centos-art.sh* execution environment before executing the function
Alain Reguera Delgado cdbf5c
definition set inside the initialization file, so related functions
Alain Reguera Delgado cdbf5c
are always available for you to use in the initialization file file
Alain Reguera Delgado cdbf5c
and other related functions as well. This is rather useful when you
Alain Reguera Delgado cdbf5c
are refactoring your initialization scripts and probably related
Alain Reguera Delgado cdbf5c
functions as well.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
As naming convention, related function files are written using the
Alain Reguera Delgado cdbf5c
module's name, then an underscore (``_''), then a descriptive name
Alain Reguera Delgado cdbf5c
and, finally, the ``+.sh+'' extension. The function definition inside
Alain Reguera Delgado cdbf5c
the function file also follows this convention but excludes the
Alain Reguera Delgado cdbf5c
``+.sh+'' extension from name (e.g., the function file
Alain Reguera Delgado cdbf5c
``+hello_getOptions.sh+'' has a function definition named
Alain Reguera Delgado cdbf5c
``+hello_getOptions+'' inside). The *centos-art.sh* script relays in
Alain Reguera Delgado cdbf5c
these conventions to export and destroy related functions when new
Alain Reguera Delgado cdbf5c
module environments are created and destroyed.  If you create related
Alain Reguera Delgado cdbf5c
function files with a pattern different from that described here, they
Alain Reguera Delgado cdbf5c
will not be executed nor available inside the initialization file of
Alain Reguera Delgado cdbf5c
the module environment being currently executed.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
See also: <<module-init-file>> and <<related-functions>>.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-directory-modules]]
Alain Reguera Delgado cdbf5c
The +Modules+ Directory
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This directory contains nested modules (e.g., child modules) and is
Alain Reguera Delgado cdbf5c
used for extending the current module functionality in a modular way.
Alain Reguera Delgado cdbf5c
There isn't a visible limitation in the number of +Modules+ directory
Alain Reguera Delgado cdbf5c
you can nest inside one module to achieve certain functionality so,
Alain Reguera Delgado cdbf5c
you can create as many levels of +Modules+ directories as you need.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-directory-locales]]
Alain Reguera Delgado cdbf5c
The +Locales+ Directory
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This directory contains module-specific localization files. The
Alain Reguera Delgado cdbf5c
content of this directory is automatically generated by *locale*
Alain Reguera Delgado cdbf5c
module of *centos-art.sh* script, when you execute it using the
Alain Reguera Delgado cdbf5c
initialization file as source and the *--update --sibling* options.
Alain Reguera Delgado cdbf5c
Once the localization files have been created, you need to edit PO
Alain Reguera Delgado cdbf5c
files to translate the strings from English to your preferred
Alain Reguera Delgado cdbf5c
language.  If the translatable strings inside the module's source
Alain Reguera Delgado cdbf5c
files change, you need to run the *locale* module again to update the
Alain Reguera Delgado cdbf5c
PO files and repeat the localization process all over again.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-directory-manuals]]
Alain Reguera Delgado cdbf5c
The +Manuals+ Directory
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This directory contains module-specific documentation. Documentation
Alain Reguera Delgado cdbf5c
in this directory is written in asciidoc format and produced through
Alain Reguera Delgado cdbf5c
the *render* module of *centos-art.sh* script to different formats,
Alain Reguera Delgado cdbf5c
including man pages and html.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
[[module-directory-configs]]
Alain Reguera Delgado cdbf5c
The +Configs+ Directory
Alain Reguera Delgado cdbf5c
~~~~~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This directory contains module-specific configuration. Some modules
Alain Reguera Delgado cdbf5c
(e.g., ``tuneup'') need to store auxiliary files required to achieve
Alain Reguera Delgado cdbf5c
its main goal (e.g., the ``tuneup'' module uses sed files to transform
Alain Reguera Delgado cdbf5c
the top-comment of scripts each time it is executed, the sed file
Alain Reguera Delgado cdbf5c
itself is stored in this directory). Whenever you need to make
Alain Reguera Delgado cdbf5c
reference to a file inside this directory, use the
Alain Reguera Delgado cdbf5c
``TCAR_MODULE_DIR_CONFIGS'' variable. This variable provides the
Alain Reguera Delgado cdbf5c
absolute path of module-related configuration file.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
Summary
Alain Reguera Delgado cdbf5c
~~~~~~~
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
This section has covered the directories and files a module is made of
Alain Reguera Delgado cdbf5c
inside the *centos-art.sh* script.
Alain Reguera Delgado cdbf5c
Alain Reguera Delgado cdbf5c
// vim: set syntax=asciidoc: