Environment Tool (Library) Guideline

This tutorial`s aim is to describe the usage of the environment tool and support the explanation with examples.

Before actually starting I would like to make clear, that there are few possible ways how to use this application:

• An tool runned with script
• A library to your script
• An interactive python session

This tutorial will mostly cover the first usage listed above.

The XML Source File

The most important part you are going to need is the XML file. This is the file that contains the setting you want to use to whatever you are going to do. Your environment is described by variables you want to create and/or modify. To help yourself with maintaining your variables you have the option to use variable as a "local" to define the same for multiple variables and in each individual variable just point to this local. You can use a pointer to another variable if it is not local as well.

You can use two differrent types of variables. List and scalar. List contains sequence of values divided by separator (colon on unix). Scalars are single string variables.

NOTE: You can use Eclipse to work with the XML file by giving the XML schema as a schema for a new XML page. Eclipse then offers visual environment and offers choices and take care about the XML header.

The XML file consists of two parts. The first is the header and then declarations of variables and actions to be taken.

The XML header

The XML header looks as displayed bellow:

<?xml version="1.0" encoding="UTF-8"?>
<env:config xmlns:env="EnvSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="EnvSchema ./EnvSchema.xsd ">

The default namespace you should use is "EnvSchema". In case you would like to use another, you have to change parameters passed by script. You might want to change schema location to correspond to actual file.

Declarations

The second part contains your environment. In order to use a variable you should declera it first. To do that, put the following line to your XML.

<env:declare variable="name" type= TYPE local=BOOL] />

This line will create a variable of given name "name" of a type TYPE ={'list','scalar'} and it will be treated as a local in case local=true and not as a local in case local=false.

In case you will not declera a variable before usage, then it will be treated as an unlocal list variable.

In case variable is redeclared to be any other type than declared before, an error will occur.

NOTE: If you are declaring a variable, that is located in OS its value will be loaded from the system during declaration.

Types

As said before you can use two kinds of varible. Either list or scalar.

Local Variable and Pointers

When you use a variable as a local it does not change environment of OS in any way. It can be used only as an input to other variables.

You can use both types of variables as locals. If you want to use already defined variable as local you have to use the name of the variable you want to use to value with a $ sign in front. Let`s suppose we want to use our local "myLoc" we worked with before and assign it to "myVar".

<env:append variable="myVar">$myLoc:anotherValue</env:append>

Or you can refer to scalar anywhere in the string. Then use "(" and ")" or "{" and "}".

<env:append variable="myVar">value${myLoc}ToBeExtended</env:append>

List should be referenced only in list as a single value. If refereced in list in the middle of value, exception is raised. If referenced in a scalar, then concateneted version of list is inserted.

Pointers to scalars can appear anywhere.

Actions

After variable is declared you can use action to operate with it. Write the following line in the XML:

<env:ACTION variable="name">value</env:ACTION>

where ACTION is one of following:

and value is eighter a single string or a list of values separated by ":" for list type of variable.

To append a value "myValue" and "secondValue" to the variable "myVar" the command is:

<env:append variable="myVar">myValue:secondValue</env:variable>

The action parameter can be any of 5 previously listed options.

NOTE: To use drive letter for windows environment please use "[C]" (without quotes) for C: drive (do not put colon next to C - will be added)(like: "[C]\Program Files\")

XML File Operations - Overview

The following table is the overview of possible usage of envRun.py script. Usage of those options is consulted bellow.

To set new environment for the current session please use envSetup

To set new environment for newly opened session please use envTerm

To check the XML file use envCheck.py

To merge XML files use envMerge.py

Using the scipt(s) - XML File Operations

Checking the XML file

You can use the tool to validate your XML file. It check for different kinds of conflicts. For example you will receive varining for set or unseting varibable that containes values.

To check your XML file use --check (-c) option:

./envCheck.py YOUR_XML_FILE --check [options]

Merging the XML file

In case you would like to use more than one XML file, you have to merge them first. The result is one XML files made from all files you provided in the order you provided. It can ends with an error if there are inconsistent declarations.

To merge files use --merge (-m) option as following:

./envMerge.py XML_FILES --merge OUTPUT_FILE [options]

Search in the XML file(s)

This functionality allows you to scan XML file(s) for apperance of variable of certain name. It will display a list of apperances sorted in order of aperance in each file and grouped by individual files. Thus you can debug operations, which are taken on individual variable.

./envRun.py YOUR_XML_FILES --search VARIABLE_NAME [options]

By default you will receive a list of all referenced variables, which are mentioned in the search variable, together with searched one. To turn this off, use --ref switch.

There is a limit of maximum depth of nesting variables and locals (default 5). To modify this limit use --maxdepth INT.

Using the scipt(s) - Environment Operations

Setting the environment of the current shell

To set new environment for the current session please use envSetup.

Under LINUX you have to source runscript. First navigate to the folder of this script (make also sure that you have envSetup.py script in your PYTHONPATH) and then use following syntax (with proper modification of "source" (on win none)(replace ".ext" with one according to your OS/shell version))

source ./envSetup.ext YOUR_XML_FILE

Running a command with a specific environment

To run command (or script) use envRun.py python script. Command is parsed the way shell input is parsed and the first part is the command and everything else are parameters for this command.

./envRun.py YOUR_XML_FILE --run COMMAND

Envoking a new terminal window

To envoke a new terminal (command prompt) window please use envTerm. Syntax is following (replace .ext with one according to your OS/shell version):

./envTerm.ext YOUR_XML_FILE

NOTE: This functionality will be supported only if you have gnome-terminal command available.

Using the interactive session

Following chapter is going through the basics of usage of Control class of Env Application

Creating new instance of Environment

From package Control import Environment (if not imported already).

Create new instance (consult script for more options of constructor):

env = Environment([loadFromSystem = True, useAsWriter=False, reportLevel = 1])

Now you can use your environment similary to list. To create new variable "PATH" with value "myPath" use (note that in this case value of PATH will be first loaded from system and your value will be appended - to prevent this pass loadFromSystem=False to constructor):

env['PATH'] = 'myPath'

By this way of creation you will get a variable, which is list and not local. To get another type, use declare function first passing on from type={'list','scalar'} and boolean to local.

env.declare(varName, type, local)

You can then use append, print and other list operations.

If you set useAsWriter=True, every action that changes variables will be recorded to XML instead of execution and then you can produce the XML file by calling env.finishXMLinput(OUTPUT_FILE). To start new recording again use env.startXMLInput().

Writing the current state of environment to file

You can write your environment to two different types of files. The first option is to produce shell script, which is able to set the environment to your shell when sourced. To do that use (giving the SCRIPT_TYPE one of "sh", "csh", "bat" parameters):

env.writeToFile(FILE_NAME, SCRIPT_TYPE)

The second option is to produce a XML file with your settings (Please note that there is no track of actions taken to this point, so every variable will be recorder with set action only. To record all operations taken you have to use useAsWriter option (see above). To use this functionality do:

env.writeToXMLFile(FILE_NAME)

NOTE: You might want to use the following functions before writing to files:

env.loadAllSystemVariables(),

which load every variable from the system you are running on.

-- MartinPlajner - 26-Aug-2011