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

ec611f
<sect1 id="scripts-bash-environment">
a01c20
38c6be
    <title>Script Execution Environment</title>
f751d7
f751d7
    <para>
f751d7
        The execution environment of <command>centos-art.sh</command>
f751d7
        script can be defined as the virtual boundery of memory in
f751d7
        which the script does what it was conceived to do once
f751d7
        executed by a command-line interpreter (e.g., Bash). When you
f751d7
        execute the <command>centos-art.sh</command> script in your
f751d7
        terminal, the interpreter behind it creates a new execution
f751d7
        environment for it which inherits all the variables and
f751d7
        functions set in the shell execution environment and those
f751d7
        exported to it through the
f751d7
        <filename>~/.bash_profile</filename> file, as well.
f751d7
    </para>
f751d7
f751d7
    <para>
f751d7
        The <command>centos-art.sh</command> script uses the
f751d7
        <filename>~/.bash_profile</filename> file to implement
f751d7
        per-user customizations.  For example, you can use this file
f751d7
        to set the location of your working copy through the
f751d7
        <envar>TCAR_WORKDIR</envar> enviroment variable. By default
f751d7
        this variable is set to 
f751d7
        class="directory">${HOME}/artwork</filename>, but you can
f751d7
        reset to something different to fit your needs. See 
f751d7
        linkend="repo-ws-config-ChangeWorkingCopy" />.
f751d7
    </para>
f751d7
f751d7
    <para>
f751d7
        Once the <command>centos-art.sh</command> script has been
f751d7
        executed, it creates different levels of execution
f751d7
        environments inside the one created by the script itself on
efb35b
        the shell.  These different environment levels can be seen as
efb35b
        a tree of execution environments which inherit one another, as
efb35b
        illustrated in 
efb35b
        linkend="scripts-bash-environments-example1" />.  These
efb35b
        different levels of execution evironments are where the
f751d7
        <command>centos-art.sh</command> script is developed in.
f751d7
    </para>
f751d7
efb35b
    <example id="scripts-bash-environments-example1">
efb35b
    <title>The execution environment</title>
a01c20
    <screenshot>
efb35b
    <screeninfo>The execution environment</screeninfo>
a01c20
    <mediaobject>
a01c20
    <textobject>
a01c20
<programlisting>
f751d7
---------------------------------------------------------------
f751d7
Shell execution environment
a94822
----|-------------------|-----------------|--------------------
a94822
.   |-- TCAR_WORKDIR    |-- TCAR_BRAND    |-- EDITOR          .
a94822
.   |-- LANG            |-- HOME          |-- PATH            .
a94822
.   `-- centos-art.sh   `-- ...           `-- ...             .
f751d7
.       ----|------------------------------------------------ .
f751d7
.       centos-art.sh script execution environment            .
f751d7
.       ----|--------------------|--------------------------- .
f751d7
.       .   |-- CLI_NAME         `-- cli()                  . .
f751d7
.       .   |-- CLI_VERSION          |-- render()           . .
f751d7
.       .   |-- CLI_BASEDIR          |   |-- svg()          . .
f751d7
.       .   |-- CLI_FUNCDIR          |   `-- docbook()      . .
f751d7
.       .   |-- TMPDIR               |-- help()             . .
f751d7
.       .   `-- ...                  |   |-- docbook()      . .
f751d7
.       .                            |   `-- texinfo()      . .
f751d7
.       .                            |-- locale()           . .
f751d7
.       .                            |-- cli_printMessage() . .
f751d7
.       .                            |-- cli_getFilesList() . .
f751d7
.       .                            `-- ...                . .
f751d7
.       ..................................................... .
f751d7
...............................................................
a01c20
</programlisting>
a01c20
    </textobject>
a01c20
    </mediaobject>
a01c20
    </screenshot>
a01c20
    </example>
a01c20
a01c20
    <para>
efb35b
        The first file the <command>centos-art.sh</command> script
efb35b
        calls is the
f751d7
        <filename>trunk/Scripts/Bash/Functions/Common/cli.sh</filename>
efb35b
        file. This file initializes variables and functions can be
efb35b
        used along the script execution environment lifetime.  Such
efb35b
        environment variables are for internal use inside the
efb35b
        <command>centos-art.sh</command> script only and users
efb35b
        shouldn't modify them to customize the script in a per-user
efb35b
        level.  Instead, to customize the script behaviour in a
efb35b
        per-user level, users need to make use of environment
efb35b
        variables set in <filename>~/.bash_profile</filename> file.
f751d7
    </para>
f751d7
ec611f
    <sect2 id="scripts-bash-environment-varref">
efb35b
efb35b
    <title>Environment Variables</title>
efb35b
f751d7
    <para>
efb35b
        The <command>centos-art.sh</command> script uses the following
efb35b
        system 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
efb35b
        execution.  By default, the centos-art.sh script links
efb35b
        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
efb35b
        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
efb35b
        editor. This is the default text editor installed by default
efb35b
        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 
efb35b
        class="directory">trunk/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>
efb35b
        Each time you need to store temporal files, do it inside the
efb35b
        absolute path specified by this variable.
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><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>
efb35b
        In addition to system 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
efb35b
        controls the working copy default location in the workstation.
efb35b
        This variable doesn't exist just after installing your
efb35b
        workstation. In order for this variable to be customizable you
efb35b
        need to configure your workstation first, as described in
efb35b
        <xref linkend="repo-ws-config" />.
efb35b
    </para>
efb35b
    <para>
efb35b
        By default, when this variable is not set, the
efb35b
        <command>centos-art.sh</command> script assumes the 
efb35b
        class="directory">${HOME}/artwork</filename> path as default
efb35b
        location for your working copy.
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 
efb35b
        class="directory">trunk/Identity/Models/Brands</filename>
efb35b
        directory).
efb35b
    </para>
efb35b
    <para>
efb35b
        By default, this variable takes <literal>centos</literal> 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 
efb35b
        class="directory">trunk/Identity/Models/Brands</filename>
efb35b
        should be named using the value of
ec611f
        <literal>${TCAR_BRAND}</literal> as sect2. 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
ec611f
    <sect2 id="scripts-bash-environment-func">
efb35b
efb35b
    <title>Environment Functions</title>
efb35b
efb35b
    <para>
efb35b
        Once environment variables are initialized, the
efb35b
        <command>centos-art.sh</command> script initializes common and
efb35b
        specific environment functions.
efb35b
    </para>
efb35b
    
efb35b
    <para>
efb35b
        Common environment functions are stored under 
efb35b
        class="directory">trunk/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
efb35b
    <para>
efb35b
        Specific environment functionalities, on the other hand, are
f751d7
        stored in the 
78a769
        class="directory">trunk/Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/${CLI_FUNCNAME}.sh</filename>
efb35b
        file, where <varname>CLI_FUNCDIRNAME</varname> is the first
efb35b
        argument passed to centos-art.sh script with the first letter
efb35b
        in uppercase but the rest in lowercase and
efb35b
        <varname>CLI_FUNCNAME</varname> is the first argument passed
efb35b
        to centos-art.sh script with all letters in lowercase.
efb35b
        Specific functionalities are exported after common
efb35b
        functionalities, so specific environment functionalities
efb35b
        aren't available inside common environment functionalities.
f751d7
    </para>
a01c20
a01c20
    <para>
efb35b
        In <xref linkend="scripts-bash-environments-example1" />,
a94822
        <function>render</function>, <function>help</function> and
efb35b
        <function>locale</function> are all specific environment
efb35b
        functions while <function>cli_printMessage</function> and
efb35b
        <function>cli_getFilesList</function> are common environment
efb35b
        functions.
a01c20
    </para>
f751d7
efb35b
    <para>
efb35b
        Both specific and common environment functions exist to
efb35b
        standardize frequent tasks inside &TCAR;. The following
ec611f
        sect2s will describe which these frequent tasks are and the
efb35b
        way they are standardized using specific and common
efb35b
        environment functions.
efb35b
    </para>
efb35b
ec611f
    </sect2>
efb35b
ec611f
</sect1>