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 must exists and must be valid for every member of
engineering team developing a software product. Having common development
environment set allows reproducible builds, which is a key to successful
software project development done in a team environment.
Devenv uses single entry point for development environment definition.
This is a devenv.xml file. If you followed instructions for default
installation, this file is located in "env" subdirectory of your project home.
Use your editor of choice to modify devenv.xml
Use dir element to validate existence of a directory.
For example, if valid project tree after check out from version
control system must have "bin", "lib" and "src" directories in the
project home, 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 Devenv that a directory is mandatory.
If directory is missing, Devenv will report an explicit error.
file element allows to validate existence of a file.
For example,
if valid project tree after check out from version control system must have
the a lib directory, Ant builder version 1.4.1 lib directory and an ant.jar file in this
directory, the 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 a file is mandatory.
If the file is missing, Devenv will report an explicit error.
In the previous example, you see how we make use of parameter
property.
This parameter associates a name with a directory or a file. This name allows
to re-use values supplied by a
location parameter making definition
of the environment easier to read and modify. For instance, 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 giving it name "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>
Devenv allows easy and automatic creation of build.properties
file that contains names and path to directories and file you want
to be available for you build scripts. For example, this file can be used by
an Ant build script to access common development environment parameters.
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 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 is later used by your Ant build script like 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 you will want to add
some of the project libraries or directories to the shell
CLASSPATH variable. It can easely be done by supplying
classpath="yes" parameter to the definition of the location.
For example, this fragment of enironment 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.
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 to the front of PATH. This example will
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 developemnt environment it will be
C:\my\project\3rdparty\ant141\bin;C:\my\project\3rdparty\jikes115\bin;C:\WINNT;C:\WINNT\System32;.
Using Devenv you can set shell variables. 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>
Devenv is distributed as a single zip file. When installing, simply unzip
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.
When unzipped, directory structure of Devenv is the following,
supposed you unzipped it into the /temp directory:
./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 this directory structure preserved when 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
Than 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
At this point Devenv is ready for use and you may begin modifying
development environment definition to your own needs.
If you don't' like name "env" as a name of the directory containing
Devenv, you will need to take additional simple step to alter
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.
Major reason for this requirement
is that all relative paths used when setting and validating development environment
are relative project tree root, or, simply project home. As a result, you get
a valuable ability to be independent from physical location of the project home.
You will always be able to validate and set your development environment
it whether it's located on local drive, like D:\my\project or on
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 make sure that Devenv can run. There
are two scripts in the Devenv installation - setenv.sh and setenv.bat,
for Unix, Cygwin and Windows, accordingly.
If you want to change default location of Devenev home, which is "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 a
directory relative to the project root. For example, if you decide to put
Devenv in bin/devenv directory, this variable will look like:
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 path to Devenv changed to 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 doing required modifications.
After Devenv registration you will receive a license file devenv.lic.
This file should replace evaluation license file contained in the devenv.jar
jar archive. Update 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 sequience of
commands for *nix is the following:
mv devenv.lic ./env/
cd ./env
. updatelicense.sh
When 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.
|