Blame Automation/centos-art.asciidoc

Alain Reguera Delgado 0de111
centos-art.sh(1)
Alain Reguera Delgado 0de111
================
Alain Reguera Delgado 0de111
Alain Reguera Delgado 954d94
Name
Alain Reguera Delgado 0de111
----
Alain Reguera Delgado 0de111
centos-art.sh - The CentOS artwork repository automation tool
Alain Reguera Delgado 0de111
Alain Reguera Delgado 954d94
Synopsis
Alain Reguera Delgado 0de111
--------
Alain Reguera Delgado 954d94
*centos-art.sh* [*--help*|*--version*]::
Alain Reguera Delgado 954d94
    This command provides information about the script itself.
Alain Reguera Delgado 0de111
Alain Reguera Delgado 954d94
*centos-art.sh* *MODULE* [*--help|--version*]::
Alain Reguera Delgado 954d94
    This command provides information about the specified module. See
Alain Reguera Delgado 954d94
    the xref:Modules[] section below to see which modules are
Alain Reguera Delgado 954d94
    available.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*centos-art.sh* *MODULE* [*OPTIONS*]::
Alain Reguera Delgado 954d94
    This command executes the specified module. Options here are
Alain Reguera Delgado 954d94
    module-specific. See the xref:Modules[] section below to see which
Alain Reguera Delgado 954d94
    modules are available.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Description
Alain Reguera Delgado 0de111
-----------
Alain Reguera Delgado 954d94
*centos-art.sh* exists to standardize frequent tasks inside the CentOS
Alain Reguera Delgado 954d94
repository.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
When you execute the *centos-art.sh* script in a terminal, it will
Alain Reguera Delgado 954d94
request the absolute path where you stored your working copy of CentOS
Alain Reguera Delgado 954d94
artwork repository.  To avoid the absolute path request every time you
Alain Reguera Delgado 5824c8
execute the script, you can edit the +~/.bash_profile+ file and
Alain Reguera Delgado 5824c8
declare the absolute path to your working copy there, as value to
Alain Reguera Delgado 954d94
TCAR_BASEDIR variable.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 5824c8
Once *centos-art.sh* script knows what the absolute path to your
Alain Reguera Delgado 5824c8
working copy is, it executes the file *centos-art.conf* to load
Alain Reguera Delgado 5824c8
default values to configuration variables into its execution
Alain Reguera Delgado 5824c8
environment.  After configuration variables have been loaded in the
Alain Reguera Delgado 5824c8
execution environment, the script looks for supported options in the
Alain Reguera Delgado 5824c8
first argument. If the options passed are recognized the script
Alain Reguera Delgado 5824c8
process them. If the options aren't recognized or no option is passed
Alain Reguera Delgado 5824c8
at all, the *centos-art.sh* script exports common functions and
Alain Reguera Delgado 5824c8
executes the module specified as first argument, assuming the first
Alain Reguera Delgado 5824c8
argument is a valid module name of course.  Finally, the
Alain Reguera Delgado 5824c8
*centos-art.sh* script waits for the module script to conclude its job
Alain Reguera Delgado 5824c8
and exits the as described in the xref:exit[] section.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
anchor:exit[Exit Status]
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Exit Status
Alain Reguera Delgado 954d94
-----------
Alain Reguera Delgado 954d94
 * 0 -- Exit successfully without errors.
Alain Reguera Delgado 954d94
 * 1 -- Exit with errors.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
anchor:Modules[Modules]
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Modules
Alain Reguera Delgado 954d94
-------
Alain Reguera Delgado 954d94
From version 0.5 on, *centos-art.sh* script introduces the idea of
Alain Reguera Delgado 954d94
modules to its base design.  Modules are individual execution
Alain Reguera Delgado 954d94
environments that may nest themselves one inside another to achieve
Alain Reguera Delgado 5824c8
high levels maintainability.  Modules make it possible to divide a big
Alain Reguera Delgado 5824c8
task into smaller tasks that can be easier to debug, maintain and
Alain Reguera Delgado 5824c8
share with other modules.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
The following modules are available for *centos-art.sh* script:
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*prepare*::
Alain Reguera Delgado 954d94
    This module standardizes configuration tasks needed by your
Alain Reguera Delgado 49bab3
    working copy (e.g., verify whether required packages are installed
Alain Reguera Delgado 49bab3
    or not in your workstation). This is the first task you should run
Alain Reguera Delgado 49bab3
    in your workstation, just after downloading a fresh working copy
Alain Reguera Delgado 49bab3
    of CentOS artwork repository.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*render*::
Alain Reguera Delgado 954d94
    This module standardizes the way content is produced inside the
Alain Reguera Delgado 49bab3
    repository. This function relies on configuration files to do its
Alain Reguera Delgado 49bab3
    work. Whenever you need to produce images, documentation or
Alain Reguera Delgado 954d94
    localized content this is the module you'll need to use.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*locale*::
Alain Reguera Delgado 954d94
    This module standardizes the way translatable strings are
Alain Reguera Delgado 954d94
    retrieved from source files and put into portable objects for you
Alain Reguera Delgado 954d94
    to edit.  Portable objects produced by this module are used by
Alain Reguera Delgado 954d94
    *render* module to produce localized content.  Whenever you need
Alain Reguera Delgado 954d94
    to produce the intermediate files holding the translatable strings
Alain Reguera Delgado 954d94
    required to produce localized content, use this module.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*help*::
Alain Reguera Delgado 954d94
    This module standardizes the way documentation is produced inside
Alain Reguera Delgado 954d94
    the repository. Whenever you need to manage documentation source
Alain Reguera Delgado 954d94
    files inside the repository, use this module.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*tuneup*::
Alain Reguera Delgado 954d94
    This module standardizes maintenance tasks frequently run inside
Alain Reguera Delgado 954d94
    the repository.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*vcs*::
Alain Reguera Delgado 954d94
    This module standardizes the way version control tasks are
Alain Reguera Delgado 954d94
    performed inside the repository. This module is used internally
Alain Reguera Delgado 954d94
    and you probably don't need to use it from the command line. This
Alain Reguera Delgado 954d94
    module is the interface that let us support different version
Alain Reguera Delgado 954d94
    control systems inside *centos-art.sh* script.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*pack*::
Alain Reguera Delgado 954d94
    This module standardizes the way RPM packages are produced from
Alain Reguera Delgado 954d94
    content available in the repository. When ever you need to produce
Alain Reguera Delgado 954d94
    RPM packages with information available in the repository, use
Alain Reguera Delgado 954d94
    this module.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Directory Structure
Alain Reguera Delgado 954d94
~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado 954d94
Inside the repository, modules related to *centos-art.sh* script are
Alain Reguera Delgado 954d94
stored in the directory +Automation/Modules+.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*Modules/*::
Alain Reguera Delgado 954d94
    This directory contains module's modules.
Alain Reguera Delgado 954d94
*Manuals/*::
Alain Reguera Delgado e08529
    This directory contains module's documentation produced by *help*
Alain Reguera Delgado e08529
    module.  The structure of this directory looks as follow:
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
Manuals/
Alain Reguera Delgado 954d94
|-- ${LANG}/
Alain Reguera Delgado 954d94
|   |-- man${SECTION_NUMBER}
Alain Reguera Delgado 954d94
|   `-- ${MODULE_NAME}.${SECTION_NUMBER}
Alain Reguera Delgado 954d94
`-- man${SECTION_NUMBER}
Alain Reguera Delgado 954d94
    `-- ${MODULE_NAME}.${SECTION_NUMBER}
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*Locales/*::
Alain Reguera Delgado e08529
    This directory contains module's translations produced by *locale*
Alain Reguera Delgado e08529
    module. The structure of this directory looks as follow:
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
Locales/
Alain Reguera Delgado 954d94
`-- ${LANG}/
Alain Reguera Delgado 954d94
    |-- LC_MESSAGES
Alain Reguera Delgado 5824c8
    |   |-- ${MODULE_NAME}.sh.mo
Alain Reguera Delgado 5824c8
    |   `-- ${MODULE_NAME}.docbook.mo
Alain Reguera Delgado 954d94
    |-- ${MODULE_NAME}.sh.po
Alain Reguera Delgado 954d94
    |-- ${MODULE_NAME}.sh.pot
Alain Reguera Delgado 5824c8
    |-- ${MODULE_NAME}.docbook.po
Alain Reguera Delgado 5824c8
    `-- ${MODULE_NAME}.docbook.pot
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*Scripts/*::
Alain Reguera Delgado e08529
    This directory contains function scripts written by module's
Alain Reguera Delgado 5824c8
    writers. Here is where all the tasks the module is useful for are
Alain Reguera Delgado 5824c8
    written and stored in.  As convention the following structure is
Alain Reguera Delgado e08529
    used:
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
Scripts/
Alain Reguera Delgado 954d94
`-- ${MODULE_NAME}_${FUNCTION_NAME}.sh
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 954d94
{asccidoc-br}
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 954d94
Inside each function script, there is a top comment where you should
Alain Reguera Delgado 954d94
put the name of the function script, a brief description about what it
Alain Reguera Delgado 954d94
does, as well as author and copying information. After the top comment
Alain Reguera Delgado 954d94
and separated by one white line, you should define the function
Alain Reguera Delgado 954d94
sentence using the long format.
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
#!/bin/bash
Alain Reguera Delgado 5824c8
######################################################################
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 954d94
#   ${MODULE_NAME}_${FUNCTION_NAME}.sh -- ${FUNCTION_DESCRIPTION}
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 954d94
#   Written by:
Alain Reguera Delgado 954d94
#   * ${AUTHOR_NAME} <${AUTHOR_EMAIL}>, ${YEARS}
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 954d94
# Copyright (C) ${YEAR} The CentOS Project
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 954d94
# This program is free software; you can redistribute it and/or modify
Alain Reguera Delgado 954d94
# it under the terms of the GNU General Public License as published by
Alain Reguera Delgado 5824c8
# the Free Software Foundation; either version 2 of the License, or
Alain Reguera Delgado 5824c8
# (at your option) any later version.
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 954d94
# This program is distributed in the hope that it will be useful, but
Alain Reguera Delgado 954d94
# WITHOUT ANY WARRANTY; without even the implied warranty of
Alain Reguera Delgado 954d94
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Alain Reguera Delgado 954d94
# General Public License for more details.
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 954d94
# You should have received a copy of the GNU General Public License
Alain Reguera Delgado 954d94
# along with this program; if not, write to the Free Software
Alain Reguera Delgado 954d94
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Alain Reguera Delgado 954d94
#
Alain Reguera Delgado 5824c8
######################################################################
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
function ${MODULE_NAME}_${FUNCTION_NAME} {
Alain Reguera Delgado 954d94
    ...
Alain Reguera Delgado 954d94
}
Alain Reguera Delgado 5824c8
----------------------------------------------------------------------
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 954d94
[NOTE]
Alain Reguera Delgado 954d94
If your are planning to contribute a new module to *centos-art.sh*
Alain Reguera Delgado 954d94
script, please, consider using the layout described above for all your
Alain Reguera Delgado 954d94
function scripts, consistently.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*$\{MODULE_NAME}.asciidoc*::
Alain Reguera Delgado 954d94
    This file contains the module's documentation source. From this
Alain Reguera Delgado 954d94
    file it is possible to produce the same documentation in other
Alain Reguera Delgado 954d94
    formats including manpage, html and pdf. Whenever you need to
Alain Reguera Delgado 954d94
    improve the module's documentation, edit this file.
Alain Reguera Delgado 954d94
*$\{MODULE_NAME}.conf*::
Alain Reguera Delgado 954d94
    This file contains the module's configuration variables. These
Alain Reguera Delgado 954d94
    variables are exported to the environment and remain there as long
Alain Reguera Delgado 954d94
    as the script execution environment is alive. Some variables are
Alain Reguera Delgado 954d94
    read-only others not.
Alain Reguera Delgado 954d94
+
Alain Reguera Delgado 954d94
The configuration file provides explanation about each environment
Alain Reguera Delgado 954d94
variable it exports. If you want to know more about what these
Alain Reguera Delgado 954d94
variables are, open this file and read the comments near each
Alain Reguera Delgado 954d94
variable.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*$\{MODULE_NAME}.sh*::
Alain Reguera Delgado 954d94
    This is the module's initialization script. The first file
Alain Reguera Delgado 954d94
    executed when the module called from the command-line. This file
Alain Reguera Delgado 954d94
    provides access to argument parsing and controls how
Alain Reguera Delgado 954d94
    module-specific function scripts are called. This is the starting
Alain Reguera Delgado 954d94
    point for writing modules. You can write a complete module using
Alain Reguera Delgado 954d94
    this file only but, frequently, it is convenient as the module
Alain Reguera Delgado 954d94
    complexity grows to divide it in smaller pieces (function scripts)
Alain Reguera Delgado 954d94
    to improve maintainability and error findings.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Options
Alain Reguera Delgado 954d94
-------
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*--help*::
Alain Reguera Delgado 954d94
    Display program's help (this page).
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
*--version*::
Alain Reguera Delgado 954d94
    Display program's name and version.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 5824c8
Bugs
Alain Reguera Delgado 5824c8
----
Alain Reguera Delgado 5824c8
The module *pack* isn't implemented yet.
Alain Reguera Delgado 5824c8
Alain Reguera Delgado 954d94
Reporting Bugs
Alain Reguera Delgado 954d94
--------------
Alain Reguera Delgado 5824c8
Report bugs inside the *automation* category of *centos-artwork*
Alain Reguera Delgado 5824c8
project, at the https://centos.org.cu/bugs/[The CentOS Bugs] website.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Author
Alain Reguera Delgado 954d94
------
Alain Reguera Delgado 954d94
Written by mailto:al@centos.org.cu[Alain Reguera Delgado]
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
Copyright
Alain Reguera Delgado 954d94
---------
Alain Reguera Delgado 954d94
Copyright (C) 2013 The CentOS Project
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
This program is free software; you can redistribute it and/or modify
Alain Reguera Delgado 954d94
it under the terms of the GNU General Public License as published by
Alain Reguera Delgado 954d94
the Free Software Foundation; either version 2 of the License, or (at
Alain Reguera Delgado 954d94
your option) any later version.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
This program is distributed in the hope that it will be useful, but
Alain Reguera Delgado 954d94
WITHOUT ANY WARRANTY; without even the implied warranty of
Alain Reguera Delgado 954d94
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Alain Reguera Delgado 954d94
General Public License for more details.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
You should have received a copy of the GNU General Public License
Alain Reguera Delgado 954d94
along with this program; if not, write to the Free Software
Alain Reguera Delgado 954d94
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Alain Reguera Delgado 954d94
Alain Reguera Delgado 954d94
// vim: set syntax=asciidoc: