Viewtier Devenv Documentation
Contents
Setting common development environment
devenv.xml
Validating existence of a directory
Validating existence of a file
Using property parameter
Setting build.properties
Adding file to CLASSPATH
Adding directory to PATH
Setting shell variables
Appendix. Installation
Appendix. Altering setenv script
Appendix. Registration and updating license
Appendix. System requirements
Common development environment is a set of directories, files, and
shell variables that each member of an engineering team must have
access to. Having established a common development environment
allows reproducible builds, which are key to the successful delivery
of a software project.
Viewtier Devenv uses a single entry point for the development environment
definition. This is the devenv.xml file. you followed
instructions for default installation, you know that this file is
located in the "env" subdirectory of your project home. Use the
editor of your choice to modify devenv.xml
Use the dir element to validate existence of a directory.
For example, if your valid project tree has "bin", "lib", and
"src" directories in the project home after the check-out from the
version control system, devenv.xml will look like the
following:
<?xml version="1.0"?>
<environment>
<validate>
<dir location="bin" required="yes"/>
<dir location="lib" required="yes"/>
<dir location="src" required="yes"/>
</validate>
<environment>
Parameter required="yes" tells Viewtier Devenv that the directory is mandatory.
If the directory is missing, Devenv will report an explicit error.
Use the file element to validate the existence of a file.
For example, if your valid project tree has a lib directory, ANT
builder version 1.4.1 lib directory, and an ant.jar file in the
given directory after the check-out from version control system,
devenv.xml file will look like this:
<?xml version="1.0"?>
<environment>
<validate>
<dir property="lib" location="lib" required="yes"/>
<dir property="ant.lib" location="${lib}/ant141/lib" required="yes"/>
<file property="ant.jar" location="${ant.lib}/ant.jar" required="yes"/>
</validate>
</environment>
Parameter required="yes" tells Devenv that the file is mandatory.
If the file is missing, Devenv will report an explicit error.
In the previous example, we showed you how to make use of the
parameter property. This parameter associates a name
with a directory or a file. This name allows you to re-use values
supplied by the location parameter and thus make the
definition of the environment easier to read and modify. For
instance, a long definition as in
<validate>
<file location="lib/3rdparty/xml/jdom.jar" required="yes"/>
<file location="lib/3rdparty/xml/xalan.jar" required="yes"/>
<file location="lib/3rdparty/xml/xerses.jar" required="yes"/>
<file location="lib/3rdparty/xml/saxon.jar" required="yes"/>
<file location="lib/3rdparty/xml/xsql.jar" required="yes"/>
<file location="lib/3rdparty/xml/schema.jar" required="yes"/>
</validate>
can be simplified by introducing directory lib/3rdparty/xml and naming it "xml.lib":
<validate>
<dir property="xml.lib" location="lib/3rdparty/xml" required="yes"/>
<file location="${xml.lib}/jdom.jar" required="yes"/>
<file location="${xml.lib}/xalan.jar" required="yes"/>
<file location="${xml.lib}/xerses.jar" required="yes"/>
<file location="${xml.lib}/saxon.jar" required="yes"/>
<file location="${xml.lib}/xsql.jar" required="yes"/>
<file location="${xml.lib}/schema.jar" required="yes"/>
</validate>
Viewtier Devenv allows easy and automatic creation of
build.properties file that contains the path and the
names to directories and files you want to be available for your
build scripts. For example, this file can be used by an ANT build
script to access the common development environment properties.
If you want your directory or file be in the build.properties
file, simply add a property parameter and build="yes"
or build="true" to a definition of a directory or a file in
devenv.xml. Please note that in this case the property
parameter is mandatory.
For instance, you are going to use xalan.jar library in a
compilation classpath in an ANT script, but you don't want your ANT
script to be tied to the particular location of xalan.jar. With
Viewtier Devenv, it is no longer a hassle:
<?xml version="1.0"?>
<environment>
<validate>
<dir property="xml.lib" location="lib/3rdparty/xml" required="yes"/>
<file property="xalan.jar" location="${xml.lib}/xalan.jar" required="yes"
build="yes"/>
</validate>
</environment>
This will generate a build.properties file that may look like the
following (supposed your project home is C:\my\project):
# Created at 11:24 on 25/02/2001
xalan.jar=C:\\my\\project\\lib\\3rdparty\\xml\\xalan.jar
build.properties will later be used by your ANT build script as in
the fragment below:
<project name="myproject" default="usage" basedir=".">
<!-- load properties from a file generated by Devenv -->
<property file="build.properties"/>
<!-- Use ${xalan.jar} defined by Devenv environment
definition to compose a compile classpath -->
<path id="compile.classpath">
<pathelement path="${xalan.jar}"/>
</path>
</project>
If your project uses Java, it's likely that you'll find it necessary
to add some of the project libraries or directories to the shell
CLASSPATH variable. It can easily be done by supplying
classpath="yes" parameter to the definition of the
location. For example, this fragment of the environment definition:
<?xml version="1.0"?>
<environment>
<validate>
<file property="junit.jar" location="lib/3rdparty/junit37/junit.jar"
required="yes"
classpath="yes"/>
</validate>
</environment>
will add full path to junit.jar to the CLASSPATH
shell variable. If your project home is C:\my\project,
value of CLASSPATH variable will
be C:\my\project\lib\3rdparty\junit37\junit.jar. Adding
classpath="yes" to a directory definition will
have the same effect.
Viewtier Devenv allows to add directories to the PATH shell
variable that defines a directory order shell uses to search for
executable files. Add path="yes" parameter to the
definition of the directory and it will be added at the front of
PATH. In this example, we add path to ANT builder and
path to Jikes compiler to PATH:
<?xml version="1.0"?>
<environment>
<validate>
<dir location="3rdparty/ant141/bin" required="yes"
path="yes"/>
<dir location="3rdparty/jikes115/bin" required="yes"
path="yes"/>
</validate>
</environment>
If your project home is C:\my\project, and the value
of PATH variable was C:\WINNT;C:\WINNT\System32;,
after setting the development environment it will be
C:\my\project\3rdparty\ant141\bin;C:\my\project\3rdparty\jikes115\bin;C:\WINNT;C:\WINNT\System32;.
Through Devenv you can set shell variables; the element
output allows it:
<validate>
<dir property="gcc.home" location="/opt/gcc3.0" required="yes"/>
<dir property="ant.home" location="/opt/ant151" required="yes"/>
</validate>
<output>
<shell variable="GCC_HOME" path="${gcc.home}"/>
<shell variable="ANT_HOME" path="${ant.home}"/>
<shell variable="ANT_OPTIONS" value="-debug"/>
</output>
Viewtier Devenv is distributed as a single zip file. During the installation
process, simply unzip the distribution file to a temporary
directory. After that you may copy the result to your project source
tree and put Devenv under the control of source control system.
Suppose you unzipped it into your /temp directory; then, the
directory structure of Devenv will look the following:
./env
./env/devenv.jar
./env/devenv.html
./env/devenv.xml
./setenv.bat
./setenv.sh
env directory contains Devenv jar file and Devenv
documentation in HTML format. File devenv.xml out of
the box contains development environment definition that validates
presence of Devenv itself. Root directory contains two shell scripts
(or command files in Windows terms) - setenv.sh and
setenv.bat
It is recommended that you preserve this directory structure once
Devenv is copied to your project source tree. In this case, the
environment setter will be ready for use, and you will not need to
make any additional changes. For instance, if the root of your
project tree looks like the following:
./bin
./lib
./doc
./src
./test
./build.xml
./build-prod.xml
./build-test.xml
then after you copy Devenv, it would be as follows (Devenv
files marked bold):
./bin
./env
./doc
./lib
./src
./test
./build.xml
./build-prod.xml
./build-test.xml
./setenv.bat
./setenv.sh
Devenv is ready for use at this point, and you may begin
modifying development environment definition to fit your own needs.
If you don't like the name "env" as the name of the directory
containing Devenv, you will need to take an additional simple step
to change the name of the directory. It is described in the appendix
"Altering devenv script".
Please note that
setenv.sh and/or
setenv.bat shell scripts should always be located in
the root of the project tree
.
The major reason for this
requirement is that all relative paths used while setting and
validating development environment are relative to the project
tree root, or, simply project home. As the result, you get an
important advantage of being independent from the physical
location of the project home. You will always be able to validate
and set your development environment whether it's located on local
drive, like
D:\my\project or on a Unix partition like
/home/autobuild/my/project.
You may want to alter Devenv wrapping shell script to better serve
your needs. Wrapper shell script (or command file in Windows)
provides minimal validation of the environment and makes sure that
Devenv is able to run. There are two scripts in the Devenv
installation - setenv.sh and setenv.bat,
for Unix, Cygwin and Windows, respectively.
If you want to change the default location of Devenev home, which
is the "env" directory in the root of your project source tree,
change DEVENV_SETTER_HOME script variable to reflect this location.
It should always point to the directory relative to the project
root. For example, if you decide to put Devenv in bin/devenv
directory, this variable will look like this:
Unix:
DEVENV_SETTER_HOME=bin/devenv
Windows:
DEVENV_SETTER_HOME=bin\devenv
In this case, the related part of the project source tree should
look like the following:
./bin/devenv/devenv.jar
./bin/devenv/devenv.html
./bin/devenv/devenv.xml
./setenv.bat
./setenv.sh
Please note that the path to Devenv home must be
relative. Devenv will not start if this path is
absolute.
If the path to Devenv is changed to a custom location, variable
DEVENV_DEFINITION_HOME should be changed accordingly. It is defined
in the script right after DEVENV_SETTER_HOME
For your convenience, the wrapper script contains extensive
comments that will help you to carry out the required modifications.
After Viewtier Devenv registration you will receive a license file
devenv.lic. This file should replace the evaluation
license file contained in the devenv.jar jar archive.
The updating process is simple - copy devenv.lic to the
same directory that contains devenv.jar and run
updatelicense.sh or updatelicense.bat,
depending on OS you use. Possible sequence of commands for *nix is
the following:
mv devenv.lic ./env/
cd ./env
. updatelicense.sh
When the license is updated, devenv.jar needs to be
checked in so that it is available for other members of your team.
-
Devenv requires Java Runtime Environment
version 1.3.1 and higher.
-
Devenv is a pure Java program and will run
on any operating system with JRE 1.3.1 installed.
-
Devenv supports Windows command shell, Unix
and Cygwin bash.
|