Subversion Repositories DevTools

#-------------------------------------------------------------------------------
#   Documentation
#

=pod

=for htmltoc    CORE::

=head1 NAME

JATS Environment Variables

=head1 SYNOPSIS

JATS makes use of a number of Environment Variables (EnvVars) to provide
configuration information.

There are two classes of EnvVars used by JATS. These are:

=over 4

=item 1 

JATS Configuration

These EnvVars have a GBE_ prefix. These are detailed in this document.

=item 2 

Toolset location

Some of the build tools used by JATS use EnvVars to specify the location
of the installed tool. 

Ideally tools should be installed in their default location and JATS should be
preconfigured to use this default location. Configuration allows for exceptions.

=back

=head2  Environment variables

Environment variables that specify a path may be set to '-', or 'none' in order
to force an undefined path.

=over 8

=item GBE_MACHTYPE

This specifies the machine that the script is running on. This is fixed within
the startup script.

=item GBE_HOSTMACH (internally set)

This is a copy of GBE_MACHTYPE.
Unlike GBE_MACHTYPE, this copy is not modified by makefiles.

=item GBE_HOSTNAME (internally)

This EnvVar is the name of the current host. It is available to be used within
scripts that need to stamp build files.

=item GBE_PERL

This specifies the full path the to B<ActiveState> perl binary.

=item GBE_CORE

This specifies the path the to B<JATS> installation.

=item GBE_CACHE_JATS

When set to a non zero value will force JATS to transfer a working copy to the
local dpkg_archive. This will speed up the build process because the utilities
will be run from a local drive; not a network drive.

This will only operate if JATS is run from dpkg_archive.

=item GBE_DPKG_STORE (optional)

This is the global read-only archive store. It will only be used to source
packages after all other archive stores have been examined. The GBE_DPKG_STORE
is intended to provide a read-only or remote repository within a global
environment.

=item GBE_DPKG

This is the official archive. Some tools will publish packages directly to this
archive.

This item is mandatory and must address a valid directory.

=item GBE_DPKG_REPLICA (optional)

This is the local package read-only archive replica. It will only be used to source
packages before other archive stores have been examined. The GBE_DPKG_REPLICA
is intended to provide a local read-only replica of the main repository within a global
environment.

=item GBE_DPKG_CACHE (optional)

This the path to a local package archive cache. This is used to speed access to
main repository. The cache should be on the users local machine and not a network
drive.

=item GBE_DPKG_LOCAL (optional)

This the path to a group wide local package archive. This may be used to store
non-official packages that are under test or development.

Not recommended. Use is being deprecated.

=item GBE_DPKG_SBOX (internal)

This the path to a sandbox specific package archive. This will be used to store
non-official packages that are under test or development within the current sandbox.

The archive is located by searching from the current directory to the root of
the file system for a directory called 'sandbox_dpkg_archive'.

It is intended that a group of packages that are being developed in the same
sandbox will share the same sandbox_dpkg_archive.

Jats will ignore the version number when dealing with packages in GBE_DPKG_SBOX.
This is done to simplify the publishing and consuming of packages in the sandbox.

This should not be set by a user. It will be calculated by JATS and passed to
JATS tools and utilities.

=item GBE_SANDBOX (internal)

This the path to a sandbox base directory. It is intended that a group of
packages that are being developed in the same sandbox will share the same
sandbox_dpkg_archive.

This should not be set by a user. It will be calculated by JATS and passed to
JATS tools and utilities.

=item GBE_DPLY (optional)

This the path to the deployment archive.
This archive will be used when publishing special deployment package. This is
not the norm.

This variable may be set on a per-project basis.

=item GBE_PLATFORM (deprecated)

This specifies the names of platforms that will be built and made. This should
be empty. Use B<GBE_BUILDFILTER> to provide better control.

=item GBE_BUILDFILTER (desirable)

This is a filter string that specifies which platforms to create makefiles
for. This variable is used to prevent JATS from creating Solaris and Linux
targets on a Windows machine and visa-versa.

=item GBE_JATS_VERSION (optional)

Specifies the version of JATS that the user will use. This is the same as
specifying the -version=xx.xx.xx option on the command line, but because it is
in the environment the required version will be used by all invocations of JATS.

=item GBE_ABT (optional)

Used by the Auto Build Tool to indicate that the build is being performed by the
ABT. When set the build environment will be modified to suite the ABT. Some
operations may be relaxed.

Currently set to 1 to set it.

=item ANT_HOME (desirable)

Used by the Auto Build Tool and any JATS builds that make use of ANT. This 
EnvVar should specify the location of the root of the ANT (1.6.5) Installation. 
Jats will expect to locate 'bin/ant' below ANT_HOME.

=item GBE_VIEWBASE (optional)

Used by the 'release' utilities to provide a user configurable base directory for
the creation of static views. The default location is:

=over 8

=item *

WINDOWS - c:\clearcase

=item * 

Unix - ${HOME}/jats_cbuilder

=back

=item GBE_VCS (optional)

Used by the JATS wrapper script when processing the 'release', 'extract' and 'label'
commands to determine the command to invoke.

If not specified, then 'cc' is assumed.

Valid values are:

=over 4

=item *

cc for ClearCase

=item *

svn for Subversion

=back

=item GBE_RM_LOCATION (optional)

Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.
Specifies the location of the Release Manager Database. This is a database url
of the form jdbc:subprotocol:subname as used by java.sql.DriverManager.getConnection()

C<Example: jdbc:oracle:thin:@auperaprm01:1521:RELEASEM>

=item GBE_RM_USERNAME (optional)

Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.
Specifies a USERNAME with access to the Release Manager Database.

=item GBE_RM_PASSWORD (optional)

Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.
Specifies a PASSWORD to be used in conjunction with GBE_RM_USERNAME to access
the Release Manager Database.

=item GBE_RM_URL (optional)

Used by tools that interface to Release Manager: primarily the (ABT) Auto Build Tools.
Specifies the base URL of RElease Manager

=item GBE_DM_LOCATION (optional)

Similar to GBE_RM_LOCATION, but is used to access the Deployment Manager Database.
If GBE_DM_LOCATION is not provided, then GBE_RM_LOCATION will be used.

=item GBE_DM_USERNAME (optional)

Similar to GBE_RM_USERNAME, but is used to access the Deployment Manager Database.

=item GBE_DM_PASSWORD (optional)

Similar to GBE_RM_PASSWORD, but is used to access the Deployment Manager Database.

=item GBE_DM_URL (optional)

Similar to GBE_DM_URL, but is used to access the Deployment Manager Database.

=item GBE_CQ_LOCATION (optional)

Used by tools that interface to ClearQuest: primarily the (ABT) Auto Build Tools.
Specifies the location of the ClearQuest Database. This is a database url
of the form jdbc:subprotocol:subname as used by java.sql.DriverManager.getConnection()

C<Example: jdbc:jtds:sqlserver://AUPERASQL05:1433:master>

=item GBE_CQ_USERNAME (optional)

Used by tools that interface to ClearQuest: primarily the (ABT) Auto Build Tools.
Specifies a USERNAME with access to the ClearQuest Database.

=item GBE_CQ_PASSWORD (optional)

Used by tools that interface to ClearQuest: primarily the (ABT) Auto Build Tools.
Specifies a PASSWORD to be used in conjunction with GBE_RM_USERNAME to access
the ClearQuest Database.

=item GBE_JIRA_URL (optonal)

Used by tools that interface to the Jira Issues database via a REST API: primarily the
Auto Build Tools. The variable specifies the URL to the base of the REST API interface.

C<Example: http://cloudajir01.vix.local:8080>

=item GBE_JIRA_USERNAME (optional)

Using in conjunction with GBE_JIRA_URL to access the Jira Issues database.

=item GBE_JIRA_PASSWORD (optional)

Using in conjunction with GBE_JIRA_URL to access the Jira Issues database.

=item GBE_SVN_URL_<Repo> (Required for Subversion support)

Provides subversion configuration of known repositories. The EnvVar contains 
the unique name of the repository within the ERG domain. ie: 
C<GBE_SVN_URL_AUPERASVN01>

The value of the EnvVar specifies the URL of the Subversion repository to be
used by the Subversion oriented JATS commands. The URL should contain the
protocol, the repository host and the path to the root of the repository and
possibly name of the repository. ie: C<https://auawsasvn001.vix.local/svn>

=item GBE_SVN_URL (Required for Subversion support)

Specifies the default URL of the Subversion repository to be used by the
Subversion oriented JATS commands. The URL should contain the protocol, the
repository host and the path to the root of the repository, but not the name of
the repository. ie: C<https://auawsasvn001.vix.local/svn>

This EnvVar is similar to B<GBE_SVN_URL_<Repo>>, except that it will only be
used as a last resort. It may be used to provide a site wide repository URL, but
it would not be suitable for repositories that are external to the site. 

For correct operation of utilities that calculate a global Subversion tag,
B<GBE_SVN_URL> should resolve to one of B<GBE_SVN_URL_<Repo>> values.

=item GBE_SVN_PATH (optional)

If provided this will be used to locate the 'svn' utility used by the SubVersion
support functions. If not provided, then the utilities assume that 'svn' is in the
users PATH. 

Providing the path will prevent JATS from searching for the utility.

=item GBE_SVN_USERNAME (optional)

Subversion repository credentials. If provided it will be used, otherwise the
native svn credential mechanism will be used.

=item GBE_SVN_PASSWORD (optional)

Subversion repository credentials. If provided it will be used, otherwise the
native svn credential mechanism will be used.

=item GBE_MAKE_TYPE (internal)

This EnvVar is set when a Makefile is being processed by 'make'. The value
indicates the type of the build. It will be either P(Production), D(debug)
or C(Common).

=item GBE_MAKE_TARGET (internal)

This EnvVar is set when a Makefile is being processed by 'make'. The value
is set current target platform name.

=item GBE_MAKE_CFG (internal)

This EnvVar is set when a Makefile is being processed by 'make'. The value
is set to the path of the parsed makefile.pl data gathered when the makefile
was created.

=item GBE_MAKE_CMD (internal)

This EnvVar is set when a Makefile is being processed by 'make'. The value
is set current make command being processed.

=item GBE_SCRIPT (internal)

This EnvVar contains the path and command line argument to the current JATS
command.

Its primary purpose is to determine the location of the jats startup script:
jats.bat or jats.sh.

=item GBE_UNIX (internal)

This EnvVar will be set to 1 on Unix systems and 0 on Windows Systems. The value
is calculated by JATS and cannot be set externally.

=item USER (set if undefined)

This EnvVar will be set to the current JATS user. It may be set externally,
but normally this is not required as JATS will determine the user in a
platform specific manner.

=back

=head2 Location of EnvVar definitions

The location of the EnvVars used by JATS is dependent on the target machine
type.

=head3 Windows 

Under Windows, the best place to specify the JATS EnvVars is in the JATS.BAT
file itself. The location of the JATS.BAT file being used is provided by the '
jats vars' utility.

=head3 Solaris

Under Solaris, the JATS EnvVars are set in /etc/profile. These can be
overridden by users in there own profile, but this is not encouraged as the
JATS configuration is normally machine-wide.

The jats.sh script, used to start jats may provide default definitions. The
location of this script is provided by the 'jats vars' utility.

=head3 Linux

Under Linux, the JATS EnvVars are set in  /etc/profile.d/jats.sh. These can be
overridden by users in there own profile, but this is not encouraged as the
JATS configuration is normally machine-wide.

The jats.sh script, used to start jats may provide default definitions. The
location of this script is provided by the 'jats vars' utility.