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