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_CACHE_CTL (optional)

Controls the automatic population of GBE_DPKG_CACHE, if it is defined. The provided value

is used as the initial value for the build argument of '-cache'.

The following values are supported:

=over 4

=item 0 - Do not cache package versions.

This is the default mode of operation. Caching can still be controlled from the

comamdn line of the 'build' command.

=item 1 - Cache package versions. 

If version is not present in the cache, then it will be transferred.

=item 2 - Force caching of package versions. 

Will transfer the package even if it already exists in the cache. Not recommended.

=back

=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_ESCROW (optional)

This the path to directory used in escrow builds to assemble the parts of the various

builds.

The presence of this value will alter the normal package search processing such that

most of the package archives are not searched. The only archives that will be searched are:

=over 4

* GBE_DPKG_SANDBOX

* GBE_DPKG_LOCAL

* GBE_DPKG_CACHE

* GBE_DPKG_ESCROW

=back

Used only in an escrow build. Care must be taken to ensure that all the package stores

are empty before the escrow build process is initiated.

=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_SANDBOX_BUILD (internal)

This EnvVar will contain a non-zero value when commands are executed by

'jats sandbox'. This allows some tools to operate correctly within a sandbox

environment.

The initial tool is 'gradle'. The command line build will prevent gradle from

building dependent packagses as they are built by the sandbox process.

=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_OPTS (optional)

A general mechanism to alter the operation of parts of JATS.

Used Values:

=over 4

=item LEGACY

Relax some sanity tests allowing older packages to be built. 

Forced within the build system. 

Should be set when performing an escrow build.

=back

=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.

Used values:

=over 4

=item NONE

Indicates that the current machine is not to be used to build software. It may be used to run various JATS utilities.

=back

=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://cds.vixtechnology.com:443>

=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 VIX 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_GIT_URL_<RepoStore> (Required for Git support)

Provides GIT configuration of known repositories. The EnvVar contains 

the unique name of a repository store within the VIX domain. ie: 

C<GBE_GIT_URL_AUPERAGIT01>

The value of the EnvVar specifies the URL of the GIT repository store to be

used by the GIT oriented JATS commands. The URL should contain the

protocol, the repository host and the path to the root of the repository store. 

ie: C<https://auawsagit001.vix.local/git>

=item GBE_GIT_PATH (optional)

If provided this will be used to locate the 'GIT' utility used by the Git

support functions. If not provided, then the utilities assume that 'GIT' is in the

users PATH. 

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

=item GBE_MAXMAKE (optional)

If defined this value will specify the default MaxTime used by the Jats Make utility.

Refer the '-MaxTime' option in the 'L<make|TOOLS::jmake>' utility for details.

=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_UTFNAME (internal)

This EnvVar is set when a unit test is being run. It is the name of the unit test.

=item GBE_UTFUID (internal)

This EnvVar is set when a unit test is being run. It is a short string that will 

uniquely identify the unit test within the build. It may be used to create a unique

log file for post processing.

=item GBE_UTFFILE (internal)

This EnvVar is set when a unit test is being run. It is an absolute path to a

recommended output file within the final package. 

It will be unique as it includes the GBE_UTFUID element. Unit Tests may 

create correctly formatted test results in this file.

=item GBE_UTFTEST (internal)

This EnvVar is set when a unit test is being run. It a part of a file name that may be used

to construct an output file for the tests.  

Some unit tests filters require files that start with this name and have a 

suitable extension. The file extension is not provided.

The name will be unique.

=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.