Blame Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/environment.docbook

ec611f
<sect1 id="scripts-bash-environment">
a01c20
42321e
    <title>The Execution Environment</title>
f751d7
f751d7
    <para>
f751d7
        The execution environment of <command>centos-art.sh</command>
42321e
        script is organized in four levels.  The first level is the
42321e
        <quote>shell environment</quote>, the second level is the
42321e
        <quote>command environment</quote>, the third level is the
42321e
        <quote>common functions environment</quote> and, finally, the
42321e
        fourth level which contains the <quote>specific function
42321e
        environment</quote>, as described in 
42321e
        linkend="scripts-bash-environment-example1" />.  In this
42321e
        context, child environments inherit definitions (e.g.,
42321e
        variables and functions) from their parent environments making
42321e
        possible to logically organize the script in a way that needs
42321e
        can be isolated one another to follow the paradigm proposed by
42321e
        Unix developers at Bell Labs when felt that programs
42321e
        <quote>should do one thing well.</quote>
f751d7
    </para>
f751d7
42321e
    <example id="scripts-bash-environment-example1">
efb35b
    <title>The execution environment</title>
a01c20
    <screenshot>
efb35b
    <screeninfo>The execution environment</screeninfo>
a01c20
    <mediaobject>
a01c20
    <textobject>
a01c20
<programlisting>
41bd76
+-----------------------------------------------------+
41bd76
| Shell environment                                   |
41bd76
+---|-------------------|-----------------|-----------+
41bd76
.   |-- TCAR_WORKDIR    |-- TCAR_BRAND    |-- EDITOR  .
41bd76
.   |-- LANG            |-- HOME          |-- PATH    .
41bd76
.   `-- centos-art.sh   `-- TMPDIR        `-- ...     .
41bd76
.   +---|-----------------------------------------+   .
41bd76
.   | Command environment                         |   .
41bd76
.   +---|---------------|----------------|--------+   .
41bd76
.   .   |-- CLI_NAME    |-- CLI_VERSION  `-- ...  .   .
41bd76
.   .   |-- CLI_FUNCDIR `-- CLI_BASEDIR           .   .
41bd76
.   .   `-- cli()                                 .   .
41bd76
.   .   +---|-----------------------------------+ .   .
41bd76
.   .   | Common functions environment          | .   .
41bd76
.   .   +---|------------------------|----------+ .   .
41bd76
.   .   .   |-- cli_printMessage()   |-- ...    . .   .
41bd76
.   .   .   |-- cli_getFilesList()   |-- ...    . .   .
41bd76
.   .   .   `-- render()             `-- ...    . .   .
41bd76
.   .   .   +---|---------------------------+   . .   .
41bd76
.   .   .   | Specific function environment |   . .   .
41bd76
.   .   .   +-------------------------------+   . .   .
41bd76
.   .   ......................................... .   .
41bd76
.   ...............................................   .
41bd76
.......................................................
a01c20
</programlisting>
a01c20
    </textobject>
a01c20
    </mediaobject>
a01c20
    </screenshot>
a01c20
    </example>
a01c20
42321e
    <sect2>
42321e
    <title>The Shell Environment</title>
efb35b
f751d7
    <para>
efb35b
        The <command>centos-art.sh</command> script uses the following
42321e
        shell environment variables:
efb35b
    </para>
efb35b
efb35b
    <variablelist>
efb35b
    <varlistentry>
efb35b
    <term><envar>PATH</envar></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>PATH</envar> environment variable is specific to
efb35b
        the operating system and provides search paths for command
42321e
        execution.  By default, the <command>centos-art.sh</command>
42321e
        script links executable scripts from the 
efb35b
        class="directory">~/bin</filename> directory which is one of
efb35b
        the locations used as search path in this variable. This is
efb35b
        how we create the <command>centos-art</command> command from
42321e
        the <command>centos-art.sh</command> script inside your
efb35b
        working copy.
efb35b
    </para>
efb35b
efb35b
    <para>
efb35b
        This variable is not initialized inside the
efb35b
        <command>centos-art.sh</command> script. Instead, the value
efb35b
        set in <filename>~/.bash_profile</filename> file is used. 
efb35b
    </para>
efb35b
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
efb35b
    <varlistentry>
efb35b
    <term><envar>EDITOR</envar></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>EDITOR</envar> environment variable is specific to
efb35b
        the operating system and provides the path to your default
efb35b
        text editor. The <command>centos-art.sh</command> script uses
efb35b
        the default text editor to edit subversion pre-commit
efb35b
        messages, translation files, documentation files, script
efb35b
        files, and similar text-based files.  
efb35b
    </para>
efb35b
    
efb35b
    <para>
efb35b
        Possible values for this variable are:
efb35b
    </para>
efb35b
efb35b
    <itemizedlist>
efb35b
        <listitem>
efb35b
        <para>
efb35b
            <filename class="directory">/usr/bin/vim</filename>
efb35b
        </para>
efb35b
        </listitem>
efb35b
efb35b
        <listitem>
efb35b
        <para>
efb35b
        <filename class="directory">/usr/bin/emacs</filename>
efb35b
        </para>
efb35b
        </listitem>
efb35b
efb35b
        <listitem>
efb35b
        <para>
efb35b
            <filename class="directory">/usr/bin/nano</filename>
efb35b
        </para>
efb35b
        </listitem>
efb35b
    </itemizedlist>
efb35b
efb35b
    <para>
efb35b
        In case none of these values is set for the
efb35b
        <envar>EDITOR</envar> environment variable inside
efb35b
        <filename>~/.bash_profile</filename>, the
efb35b
        <command>centos-art.sh</command> script uses 
efb35b
        class="directory">/usr/bin/vim</filename> as default text
42321e
        editor. This is the text editor installed by default in &TC;;. 
efb35b
    </para>
efb35b
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
    <varlistentry>
efb35b
    <term><varname>TEXTDOMAIN</varname></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>TEXTDOMAIN</envar> environment variable is specific
efb35b
        to the operating system and provides the domain name of that
efb35b
        application we are producing translation messages for. This
efb35b
        variable, in combination with <envar>TEXTDOMAINDIR</envar>, is
efb35b
        used by <application>gettext</application> to find out the
efb35b
        location of translation messages.  In the very specific case
efb35b
        of <command>centos-art.sh</command> script we use the
efb35b
        <literal>centos-art.sh</literal> name as domain name.
efb35b
    </para>
efb35b
    
efb35b
    <para>
efb35b
        This variable is initialized inside the
efb35b
        <command>centos-art.sh</command> script, so if you set it
efb35b
        outside it (e.g., in <filename>~/.bash_profile</filename>) the
efb35b
        value you set there will be overwritten by that one set inside
efb35b
        <command>centos-art.sh</command> script, once it is executed.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
efb35b
    <varlistentry>
efb35b
    <term><varname>TEXTDOMAINDIR</varname></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>TEXTDOMAINDIR</envar> environment variable is
efb35b
        specific to the operating system and provides the absolute
efb35b
        path to the directory containing the translation messages
efb35b
        related to that application specified by
efb35b
        <envar>TEXTDOMAIN</envar> environment variable.  In the very
efb35b
        specific case of <command>centos-art.sh</command> script we
efb35b
        use the 
47422e
        class="directory">Locales/Scripts/Bash</filename>
efb35b
        path as default value.
efb35b
    </para>
efb35b
    <para>
efb35b
        This variable is initialized inside the
efb35b
        <command>centos-art.sh</command> script, so if you set it
efb35b
        outside it (e.g., in <filename>~/.bash_profile</filename>) the
efb35b
        value you set there will be overwritten by that one set inside
efb35b
        <command>centos-art.sh</command> script, once it is executed.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
efb35b
    <varlistentry>
efb35b
    <term><envar>TMPDIR</envar></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>TMPDIR</envar> environment variable is specific to
efb35b
        the operating system and provides the absolute path to the
efb35b
        temporal directory the centos-art.sh script will use along its
efb35b
        execution. This variable is defined inside the
efb35b
        <command>centos-art.sh</command> script itself using the
efb35b
        <command>mktemp</command> command and will be unique on each
efb35b
        script execution. Thus, you should be able to run several
efb35b
        instances of <command>centos-art.sh</command> script
efb35b
        simultaneously without any problem. 
efb35b
    </para>
efb35b
    
efb35b
    <para>
42321e
        When you contribute code to <command>centos-art.sh</command>
42321e
        script and need to create temporal files, do it inside the
efb35b
        absolute path specified by this variable.
efb35b
    </para>
efb35b
efb35b
    <para>
42321e
        This variable is redefined inside the
efb35b
        <command>centos-art.sh</command> script, so if you set it
efb35b
        outside it (e.g., in <filename>~/.bash_profile</filename>) the
efb35b
        value you set there will be overwritten by that one set inside
efb35b
        <command>centos-art.sh</command> script, once it is executed.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
efb35b
    <varlistentry>
efb35b
    <term><envar>LANG</envar></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>LANG</envar> environment variable is specific to
efb35b
        the operating system and controls the default locale
efb35b
        information of it.  The <command>centos-art.sh</command>
efb35b
        script use the <envar>LANG</envar> environment variable to
efb35b
        determine what language to use for printing output messages
efb35b
        from the script itself, as well as the portable objects
efb35b
        locations that need to be updated or edited when you localize
efb35b
        directory structures inside the working copy of &TCAR;.
efb35b
    </para>
efb35b
        
efb35b
    <para>
efb35b
        The <envar>LANG</envar> environment variable is initially set
efb35b
        in the installation process of &TC;;, specifically in the
efb35b
        <emphasis>Language</emphasis> step.  Generally, there is no
efb35b
        need to customize this variable in your personal profile. If
efb35b
        you need to change the value of this environment variable do
efb35b
        it through the login screen of GNOME Desktop Environment or
efb35b
        the <command>system-config-language</command> command, or even
efb35b
        resetting the variable before executing the
efb35b
        <command>centos-art.sh</command> script.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
efb35b
    </variablelist>
efb35b
efb35b
    <para>
42321e
        In addition to shell environment variables described above,
efb35b
        the <command>centos-art.sh</command> script adds the following
efb35b
        variables inside the <filename>~/.bash_profile</filename> file
efb35b
        to control the script behaviour in a per-user level:
efb35b
    </para>
efb35b
efb35b
    <variablelist>
efb35b
    <varlistentry>
efb35b
    <term><varname>TCAR_WORKDIR</varname></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>TCAR_WORKDIR</envar> environment variable is
efb35b
        specific to <command>centos-art.sh</command> script and
42321e
        controls the working copy default location of &TCAR;.  This is
42321e
        the place in your workstation where &TCAR; file system is
42321e
        stored for you to work with it.
efb35b
    </para>
42321e
efb35b
    <para>
42321e
        By default, just after installing your workstation, this
42321e
        variable will not be found in it and the
42321e
        <command>centos-art.sh</command> script will finish its
42321e
        execution with an error message if you try to execute it
42321e
        without any argument. This behaviour is OK because the
42321e
        <command>centos-art.sh</command> script doesn't know where you
42321e
        stored the working copy of &TCAR; in your workstation. In
42321e
        order for this variable to exist in your workstation you need
42321e
        to configure your workstation first, as described in 
42321e
        linkend="repo-ws-config" />.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
efb35b
    <varlistentry>
efb35b
    <term><varname>TCAR_BRAND</varname></term>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <envar>TCAR_BRAND</envar> environment variable is specific
efb35b
        to <command>centos-art.sh</command> script and controls the
efb35b
        brand information that identifies the content produced inside
efb35b
        &TCAR;. The brand information is used to give name to some
efb35b
        files inside the repository (e.g., see files under 
47422e
        class="directory">Identity/Models/Brands</filename>
efb35b
        directory).
efb35b
    </para>
efb35b
    <para>
42321e
        By default, this variable takes <quote>centos</quote> as
efb35b
        value. In case you want to change it to something else, you
efb35b
        should consider the following implications:
efb35b
    </para>
efb35b
    <itemizedlist>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The <command>centos-art.sh</command> script will no longer be
efb35b
        referred as such. Instead, the
efb35b
        <filename>${TCAR_BRAND}-art.sh</filename> name will be used.
efb35b
        This implies that you no longer are using the
efb35b
        <command>centos-art.sh</command> file we provide as part of
efb35b
        &TCAR; and won't be able to commit changes to it. However, if
efb35b
        you retain the same logic from
efb35b
        <command>centos-art.sh</command> script in
efb35b
        <filename>${TCAR_WORKDIR}-art.sh</filename>, you can use
efb35b
        common and specific functionalities provided by
efb35b
        <command>centos-art.sh</command> script and commit changes to
efb35b
        them.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    <listitem>
efb35b
    <para>
efb35b
        The files stored under 
47422e
        class="directory">Identity/Models/Brands</filename>
efb35b
        should be named using the value of
42321e
        <literal>${TCAR_BRAND}</literal> as section. If you change
efb35b
        the value of this variable, you need to be sure the new value
efb35b
        set does coincide with the file names you use to store brand
efb35b
        information.
efb35b
    </para>
efb35b
    </listitem>
efb35b
    </itemizedlist>
efb35b
    </listitem>
efb35b
    </varlistentry>
efb35b
    </variablelist>
efb35b
ec611f
    </sect2>
efb35b
42321e
    <sect2>
42321e
    <title>The Command Environment</title>
efb35b
42321e
    <para>
42321e
        The first file the <command>centos-art.sh</command> script
42321e
        calls is the
42321e
        <filename>Scripts/Bash/Functions/Commons/cli.sh</filename>
42321e
        file. This file initializes all variables and functions you
42321e
        will be able to use along the script execution environment
42321e
        lifetime.  Such environment variables are for internal use
42321e
        inside the <command>centos-art.sh</command> script only and
42321e
        users shouldn't modify them to customize the script in a
42321e
        per-user level.  Instead, to customize the script behaviour in
42321e
        a per-user level, you need to make use of your personal
42321e
        environment variables set in the
42321e
        <filename>~/.bash_profile</filename> file.
42321e
    </para>
efb35b
efb35b
    <para>
efb35b
        Once environment variables are initialized, the
efb35b
        <command>centos-art.sh</command> script initializes common and
42321e
        specific environment functions, in that order.
efb35b
    </para>
42321e
42321e
    <sect3>
42321e
    <title>Common Function Environment</title>
efb35b
    
efb35b
    <para>
42321e
        Common function environments are stored under 
47422e
        class="directory">Scripts/Bash/Functions/Commons</filename>
efb35b
        directory and will be available always, both for common
efb35b
        environment functions themselves and specific environment
efb35b
        functions.
efb35b
    </para>
efb35b
42321e
    </sect3>
42321e
42321e
    <sect3>
42321e
    <title>Specific Function Environments</title>
42321e
efb35b
    <para>
42321e
        Specific function environments, on the other hand, are stored
42321e
        in the 
47422e
        class="directory">Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/${CLI_FUNCNAME}.sh</filename>
41bd76
        file, where:
41bd76
    </para>
41bd76
41bd76
    <variablelist>
41bd76
    <varlistentry>
41bd76
    <term><varname>CLI_FUNCDIRNAME</varname></term>
41bd76
    <listitem>
41bd76
    <para>
41bd76
        Is the first argument passed to
41bd76
        <command>centos-art.sh</command> script with the first letter
41bd76
        in uppercase but the rest in lowercase. For example,
41bd76
        <literal>Render</literal>, <literal>Locale</literal> and
41bd76
        <literal>Help</literal> are all possible values to this
41bd76
        variable.
41bd76
     </para>
41bd76
    </listitem>
41bd76
    </varlistentry>
41bd76
41bd76
    <varlistentry>
41bd76
    <term><varname>CLI_FUNCNAME</varname></term>
41bd76
    <listitem>
41bd76
    <para>
41bd76
        Is the first argument passed to
41bd76
        <command>centos-art.sh</command> script with all letters in
41bd76
        lowercase. For example, <literal>render</literal>,
41bd76
        <literal>locale</literal> and <literal>help</literal> are all
41bd76
        possible values to this variable. 
41bd76
    </para>
41bd76
    </listitem>
41bd76
    </varlistentry>
41bd76
    </variablelist>
41bd76
    
41bd76
    <para>
41bd76
        Specific functions environment can be written in just one file
41bd76
        or in several files inside the same directory. Using one file
41bd76
        to write specific functions environment is rarely seen inside
41bd76
        the <command>centos-art.sh</command> script but it could
41bd76
        happen in situations where the need you want to solve can be
41bd76
        written in a few lines inside just one file. On the other
41bd76
        hand, if you find yourself writing a too long file, it is
41bd76
        convenient to logically divide it into several files. This
41bd76
        logical division takes place using functions, which indeed
41bd76
        create other environments where you can create and express
41bd76
        your solutions.
41bd76
    </para>
41bd76
41bd76
    <para>
41bd76
        The order in which individual files are exported and executed
41bd76
        inside the specific functions environments depends in the way
41bd76
        each developer write the 
41bd76
        class="directory">Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/${CLI_FUNCNAME}.sh</filename>
41bd76
        file. This is the main file inside the specific function
41bd76
        environment and controls the kind of logical division you
41bd76
        implement to organize the solution you need. As file name
41bd76
        convention, the following structure for new specific functions
41bd76
        environment is proposed:
41bd76
    </para>
41bd76
41bd76
<programlisting>
41bd76
Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/
41bd76
|-- ${CLI_FUNCNAME}.sh
41bd76
`-- ${CLI_FUNCNAME}_verbSubject.sh
41bd76
</programlisting>
41bd76
41bd76
    <para>
41bd76
        Specific functions environment is exported after common
41bd76
        functions environment does, so it is not possible for specific
41bd76
        functions environment to be available inside the common
41bd76
        functions environment, nor inside other specific functions
41bd76
        environment, different to the one been passed as first
41bd76
        argument to the <command>centos-art.sh</command> script
41bd76
        command-line.<footnote>
41bd76
            <para>
41bd76
                Although, it is possible for you to call the
41bd76
                <command>centos-art.sh</command> script to itself
41bd76
                through the <function>cli_runFnEnvironment</function>
41bd76
                common function environment.
41bd76
            </para>
41bd76
        </footnote> In 
41bd76
        linkend="scripts-bash-environment-example1" />,
41bd76
        <function>render</function> is a specific function environment
41bd76
        while <function>cli_printMessage</function> and
41bd76
        <function>cli_getFilesList</function> are common function
41bd76
        environments.
a01c20
    </para>
f751d7
efb35b
    <para>
41bd76
        Both specific and common function environments exist to
efb35b
        standardize frequent tasks inside &TCAR;. The following
42321e
        sections will describe which these frequent tasks are and the
41bd76
        way they are standardized using specific and common function
41bd76
        environments.
efb35b
    </para>
42321e
    </sect3>
efb35b
ec611f
    </sect2>
efb35b
ec611f
</sect1>