Subversion Repositories DevTools

Rev

Rev 7447 | Blame | Compare with Previous | Last modification | View Log | RSS feed 

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