Development Environment Setup Guide

Title:

Audience: Version / Status:

Development Environment Setup Guide Developers Draft

Location: Updated:

10/18/2008 21:10 a10/p10

Printed:

1/26/2005 16:56 a1/p1

1. Introduction This guide is for developers who want to set up their development environment for developing a Java J2EE project at Telephia. It involves the following steps •

Installation of the developer tools

•

Installation of the 3rd party Java components

•

Configuration of Eclipse

•

Building the project in Eclipse

•

Building the project with the Autobuild

•

Running and testing the project

Although it might be an interesting exercise to do everything described here, for practical purposes it should seldom be required, because most of the time the environment can be preconfigured and copied to a new machine, as new developers join the development team.

2. Resources There is a central repository for developer tools and libraries. First, Developer tools such as Eclipse and JBoss, Perforce, etc., are found here: \\corp.telephia.com\dev\archive_01\Dev-tools Next, 3rd party developer tools such as Struts, Hibernate, JUnit, etc. are found here: \\corp.telephia.com\dev\archive_01\Java-tools The repository is maintained to contain the latest version (or versions), and up-to-to-date information about installation, configuration and customization for our environment. All developers are encouraged to maintain the tool repository. If, for example, one project needs to upgrade to a newer version of a particular tool or library, they should download the newer version into the repository, revise the readme.txt file with updated information, communicate the new information to members of other projects who might also be interested in the upgrade, and when an older version is no longer required, delete it from the repository.

1

The author of this document, John Pianezze ([email protected]) can provide assistance with problem resolution, related to the development environment.

3. Best Practices for the Environment Before beginning to describe the various tools and processes for the environment, it would be wise to mention a few general practices to abide by:

3.1.Distributed Documentation Documentation for everything is distributed throughout the environment. Rather than trying to keep this document up-to-date, we refer to documents that are kept in the same place as the Tool or Component itself. Each Dev Tools has a link to the official documentation for that tool, which is found in the same place as the Dev Tool itself. It also has a “readme.txt” document which details any special instructions that apply to our environment.

3.2.Separation of Tools and Work In general we want to have a clear separation between “Developer tools” and “work”. The idea is that we should be able to install/reinstall/upgrade Developer Tools without affecting our Work artifacts. Whereas all Work should be either stored in Perforce or backed up, Developer Tools are not customized, and don’t need to be backed up, because they cam simply be reinstalled at any time. On the developer’s hard drive, Tools are kept physically separate from Work. The following convention applies: Developer Tools all installed in c:\Develop Work artifacts kept in c:\Work The drive device might be c:\ or d:\ In the event a developer’s hard drive fails, rebuilding the environment is easy: 1. unzip/install the Developer tools into c:\Develop 2. Synchronize with Perforce

3.3.Everything is scripted Any customization to any tool in the environment should be scripted. The tool of choice for this is ANT. The idea is that all customizations are easily repeatable, and they don’t require some “expert” to help with the configuration. We want to avoid the situation where all the expertise in configuring the environment is tied-up in someone’s brain. Rather, it should be scripted and clearly readable, so anyone can learn about what customizations should be done. The following customizations already exist: •

The JDK needs to have some “endorsed” libraries, and to have some special SSL certificates imported into the JDK’ keystore. It’s scripted in Core/env/jdk/build.xml

•

JBoss needs to have its server configured with certain customized security settings, to enable the optional Web Services, and other customizations. This is scripted in Core/env/jboss

•

The ability to install/uninstall/run JBoss as a service is scripted in .cmd batch files and stored in Perforce, and provided in Core/env/wrapper 2

•

The Autobuild is installed as a windows service and deployed to the Build Server, which is all scripted in Core/env/cruisecontrol

•

The customizations to the Eclipse workspace are exported to XML files, and stored in Core/env/eclipse

•

The source code for an Opensource library “pager-taglib” has been customized. The scripts to do a custom build of this 3rd party library is found in Core/env/pagertaglib

•

When we submit changelists to Perforce, they have a standard format. The template for the Perforce changelist is found in Core/env/perforce

Whenever a developer does any customizations to Tools or the Environment, they should be scripted, and put in the “env” folder in the Core project, or in a specific Product’s project folder.

3.4.Top-level project We define the “top-level” of the project as the folder that contains the entire project directory beneath it. For monolithic projects, it usually contains build.xml, but it might contains a set of subprojects, each of which contains separate build.xmls. Regardless, we need to be clear about where the “top-level” is, and the structure of our project, beneath it. Here is the suggested project structure, with some explanations: •

“Top-level” – contains build.xml and ant.properties to build the entire project o src – any source required to build the project, stored in Perforce  java - source files  conf – configuration files, such as XML required for the build  web – files used to build a “web application”, such as jsp, gif, html, etc. o gen – any code that is “generated” as part of the build. Same as “src” but not stored in Perforce o custom – any files that are used to customize the build during packaging  build – overwrites any files created at build time. Same structure as “build”  conf – overwrites any files in src/conf. Same structure as “src/conf” o lib – any third-party libraries required to build the project, stored in Perforce o build – any build artifacts generated as part of the build. Can be deleted to perform a “clean build” o env – files pertaining to the environment, and not part of the build. All projects should have a similar structure, which makes it easy to understand different projects in Telephia

3.5.Development Pipeline Development progresses along the Pipeline as follows: • • • •

Development Alpha Release Beta Release Production

In addition, there are usually two “streams of development” with two such pipelines: • •

New Development Sustaining Work 3

The New Development pipeline is longer, and hosts major releases, with new features. Sustaining pipeline is shorter, and is for maintenance and fixes to an existing Production release. The streams should be totally independent. The source for each Pipeline in each Stream is kept separate by means of Branches in Perforce.

3.6.All builds are done by the Autobuild The Autobuild is provided by the Cruisecontrol tool, and the build results can be seen here: http://sfdevbuild01/cruisecontrol Each build publishes Build Artifacts which are available at each stage of the Development Pipeline. It usually has four builds: Development, Alpha, Beta and Production. The Autobuild: • • • •

does Development builds, the same as developers do on their own box, but it’s always a “clean build” and it will catch any problems due to a weirdness in the developer’s environment. does Alpha Builds, which are used by QA for Integration testing does Beta Builds, which are a “release candidate” for an upcoming release does Production Builds, which are requested when making a new release to Production.

All this is possible, because the particularizes of the builds, between dev/alpha/bata/prod, are scripted in build.xml, and parameterized in ant.properties.

4. Developer Tools

4.1.Overview Developer Tools are maintained and installed from this location: \\corp.telephia.com\dev\archive_01\Dev-tools Usually, tools are installed by simply unzipping them into the c:\Develop\ location. They are grouped together there, so that it’s easy to copy them to a different machine.

4.2.Installation Location The folder of the installed program usually contains the version number. This makes it easy to track which version of which tools you’re using. Here is an example of a set of dev tools installed into an environment: example: C:\Develop\eclipse-3.1 C:\Develop\cygwin C:\Develop\jboss-3.2.5 C:\Develop\MyEclipse C:\Develop\SSH Secure Shell C:\Develop\Perforce C:\Develop\j2sdk1.5.0 C:\Develop\j2sdk1.4.2_06 Some other tools, such as the SQLServer client tools might be installed in C:\program files\ because that is the location suggested by the installer program. This is ok, but all Java tools should be installed in c:\Develop, because having a “whitespace” in the path complicates things considerably.

4

4.3.Core Tools The following tools are almost always installed for all Java developers. See the Tool Respository \\corp.telephia.com\dev\archive_01\Dev-tools for more information, noting the readme.txt file in each install location. Name

Description

Eclipse

Required for all Java developers. Because of the many plugin options, configuring Eclipse can be time-consuming. Instead, unzip the pre-configured Eclipse environment, with all the required plugins installed, ready for Telephia development.

Java JDK

It’s usually wise to install both JDK 1.4 and JDK 1.5 together. Right now, we use 1.4, but in the future, we will upgrade.

ANT

Most popular tool for doing builds, and general-purpose scripting.

Perforce

Client Software

Database Client

SQLServer or Teradata database client software (usually installed by IT)

JBoss

The Core tool for all J2EE development

Winzip

Windows XP has built-in support for Zip archives, but many developers find it to be clumsy.

Yahoo Messenger

An essential tool for team communication. http://messenger.yahoo.com. Each project publishes a list of IDs for the people on the team.

4.4.Other Tools The following tools are often installed Name

Description

Text Editor

A Text Editor such as Textpad or UltraEdit is usually helpful. A keystroke macro is handy to automate repetitive editing tasks. \\corp.telephia.com\dev\archive_01\Dev-tools\Editors

Diff Tool

A color-coded side-by-side diff tool, such as Examdiff is often useful.

Cygwin

Because we use ANT, and we write scripts for everything, a command line interface is important. A Unix shell like Cygwin is more friendly and powerful than a regular DOS box.

Decompiler When no source code is available, it’s handy to be able to see the source, while debugging. Install JAD, along with the Eclipse plugin, which allows you to see decompiled source when opening a class file in the Eclipse workbench SSH Client

For accessing the command-line of a Unix box, try this SSH client: \\corp.telephia.com\dev\archive_01\Dev-tools\SSH

Toad

A popular SQL tool, works with any database: \\corp.telephia.com\dev\archive_01\Dev-tools\Toad

Mozilla

For web testing, it’s not enough to just use Internet Explorer. Install Mozilla Firefox here: www.mozilla.org

Log4j Chainsaw

Tool for viewing log files in a friendly, Color-coded format.

5

WinCVS

Most Opensource projects use CVS, so it pays to have a CVS client installed, so you can participate, contribute, build alpha releases, etc.

5. Third Party Java Libraries

5.1.Overview A typical Developer installation has over 50 Third Party Java Tools. They can be found here: \\corp.telephia.com\dev\archive_01\Java-tools Usually, tools are installed by simply unzipping them into the c:\Develop\ location. They are grouped together there, so that it’s easy to copy them to a different machine. As with Developer Tools, they should be installed in the following common location: C:\Develop\

5.2.Core Java Tools Name

Description

6. Working with Eclipse

6.1.Things we’ve learned Project locations The Eclipse workspace is in a different location to the Java project. For example, your dev workspace is found in c:\work\eclipse\dev... The Perforce client points to c:\work\perforce\ The files for the dev project are checked out to c:\work\perforce\dev All the files for a project should be contained under the “top-level” project, which is checked-out from Perforce

7. The Auto-build

7.1.Cruise-control The automatic build is done by a tool called Cruise Control. It runs on the server “sfdevbuild01” You can see the status of all the automatic builds here: http://sfdevbuild01/cruisecontrol

6