JBE Howard Ship Primix 2000 2001 Primix As envisioned but most tool makers, the life of a Java developer is a solitary one. Parked at his or her desk, with only his trusty tools, IDEs and the command line, the developer creates the wonderful applets, applications and frameworks possible using Java. The developer has and requires great freedom; each tool in his or her arsenal may have come from a different company; each tool may have been installed into a directory of his or her liking. This is not a problem because the developer is only accountable to him- or her-self, and these selections of tools and locations will only aftect one person. Alas, in the real world, developers work on teams and share code using source code repositories. They may be physically located across the hallway, or across the planet. As they work, they may make conflicting changes to code. What's needed is a system that can adjust for local differences in developer's environments and allow for "clean builds" of projects directly from source. That's what the Java Build Environment (JBE) is for. JBE is designed to start with basic Java source and utlimately produce a Java Archive (JAR) or Web Archive (WAR) ready for testing or deployment. This may involve many steps, including compiling Java code, creating RMI stubs and skeletons, using application-server specific tools (such as WebLogic ejbc), combining the results into a JAR file ... even creating Javadoc. Without JBE, there are three options for doing all this: The command line. Developers may simply execute the java and jar commands themselves. This leads to problems when steps are missed, or the commands are in some way dependent on a single developer's environment (for example, the setting of the CLASSPATH variable). Batch commands / shell scripts. Hard to develop and debug and non-portable between platforms. Often assembled in a hurry that leads to the same kind of environment problems as using the command line. IDE. Some IDEs can assemble JARs, or even interface to an application server to build and deploy EJBs and WARs; however, this will require that the user interactively use the IDE's tools. Also, these tools are idiosyncratic; getting them to package up the correct Java classes and resources is often challenging. JBE includes many hooks to allow custom directories, compiliation options or other configuration (such as JDK release and vendor) to be specified. Other hooks allow for additional processing, such as signing a JAR. JBE is designed to be portable, meaning the same source files and Makefiles will work across multiple developer's workstations ... even when using different operating systems (such as Windows, Linux and Solaris). Because the JBE is based on GNU Make it is extermely adaptable and extensible. JBE Makefiles can do more than simply compile Java files, they can also run tests, launch applications, prepare distributions virtually any operation that can be done using shell scripts or command macros, though Makefile syntax is cleaner, easier and platform independent. JBE is most useful with medium to large scale Java projects. It has no support for compiling anything but Java; projects which use native code are beyond its scope. JBE is distributed as a part of the Tapestry distribution, in the JBE directory. Under Windows, it is necessary to perform a separate installation to provide the necessary GNU tools, including GNU Make. JBE was developed under Windows (Windows NT 4.0 Workstation and Windows 2000 Professional), and makes use of the Cygwin tools library. The JBE is also operational under Solaris, and future plans are ports to various Linux distributions. Because my direct experience is to suffer the indignities of Windows development, the examples in this document use Windows pathnames. Developers using Linux or Solaris should be able to translate to their sensibly named file systems. On any operating system it is necessary to have a JDK installed. JBE was developed using Sun's JDK 1.2.2 and JDK 1.3. The JDK used by the JBE is configurable (details are below).

The JBE has been ported to work with Solaris 2.6 or above. This version of Solaris does not, by default, include the GNU tools. The JBE requires the presense of GNU tar and GNU zip, which are a separate install. GNU tar should be installed as /usr/local/bin/gtar.

Cygwin is a set of GNU s ported so as to run in the Windows NT or Windows 2000 environments (it may also work under Windows 95/98/ME). Cygwin is available at http://sources.redhat.com/cygwin/. Installing Cygwin is very easy; Cygwin starts by downloading a small installer called setup.exe. Running this program allows the user to install any of the many individual packages in Cygwin individually. You should download this program from the Cygnus web site to a safe directory (you use the same program later to update your installation with newer versions of the packages). The JBE is packaged with Tapestry; if you are reading this document, then you have probably already unpacked the Tapestry distribtution. The JBE is stored in the JBE subdirectory of the distribution. It is necessary to create an environment variable, SYS_MAKEFILE_DIR, that points to the directory. Use forward slashes as the path seperator, even under Windows. A typical value for this is C:/Tapestry-x.x.x/JBE (depending on which release of Tapestry you downloaded, and where you installed it). In addition, the variable PATH should be changed to add the CYGWIN/bin directory (typically, C:/cygwin/bin) to the search path. This is primarily to support the make command (all commands executed during a make use complete pathnames).

Configuration is accomplished by creating additional files used by GNU Make at runtime. Under the JBE directory will be a config directory. Create a new file, SiteConfig.mk, in the directory. This file is used to specify the platform for the local workstation. # Defines the local platform. SITE_PLATFORM := Cygwin An example file, SiteConfig.example.mk is provided in the config directory, you can simply copy or rename it to SiteConfig.mk. Platforms correspond to the Platform.name.mk file in the main JBE directory. This file may also be used to store addtional, site-wide options (typically, variables that start with the prefix SITE_). Such options will apply to all projects built on the local workstation. In a multiple-developer environment, all developers on the same platform will use identical copies of the SiteConfig.mk file. Because of the way GNU Make works, all of these declarations could be made by creating additional environment variables. However, it is far easier to edit these makefiles than it is to deal with editting environment variables. Instead, the JBE requires only a single environment variable, SYS_MAKEFILE_DIR, to be set. A second configuration file, config/LocalConfig.mk, is used to establish the directories into which related tools have been installed. For example: JDK_Sun_1.2.2_DIR := C:/jdk1.2.2 JDK_Sun_1.3_DIR := C:/jdk1.3 WEBLOGIC_DIR := C:/WebLogic An example file, LocalConfig.example.mk is provided in the config directory, you can simply copy or rename it to SiteConfig.mk. It sets the two JDK directories (as shown above), but not WEBLOGIC_DIR. The first two variables define the locations of two JDKs installed on the local workstation. The JBE considers a JDK to be a combination of a vendor and a release. You must create a variable JDK_vendor_release_DIR for each combination. Unless overriden in some way, the default JDK is Sun 1.3. LocalConfig.mk is also a useful place to specify other global variables. In the example, the variable WEBLOGIC_DIR is specified, to identify where the WebLogic application server was installed ... this is only needed you will be creating EJB deployments for Weblogic.

The JBE performs builds on projects. For the JBE, a project is a directory which contains a number of Java packages. The source code in all the packages will be compiled and eventually combined into a single JAR file. The JBE requires a project makefile in the project directory, whose job is to set global options for the entire project, and to identify the list of Java packages. Each package may also have its own Makefile, which is used to identify the Java source files, resource files and RMI classes for that package. The project makefile also identifies the type of JBE module the project uses. The module determines whether a Jar, a War or something else is produced by the project.

This section describes each of the different types of JBE modules that are used by projects.

The most basic type of JBE module is the Jar module, which builds a JAR file that can be used as a framework or standalone application. The JAR file is created in the project directory (though it can be removed by make clean). The project Makefile for a Jar module should define the following variables: INSTALL_DIR The directory to which the final JAR should be copied after it is built. JAVAC_OPT Module specific java compiler options. JAVADOC_DIR The directory to which Javadoc should be written. JAVADOC_OPT Javadoc options. JDK_RELEASE Optional: The release of the JDK to use when compiling. JDK_VENDOR Optional: The JDK vendor to use when compiling. META_RESOURCES The names of any resources that should be copied from the module directory into the JAR's META-INF directory. This is optional. PACKAGES The names of all packages in the module. PROJ_CLASSPATH A space seperated list of the classpath entries (typically, other JAR files) used when compiling. Absolute or relative pathnames may be used. Use the forward slash as the path seperator (even on Windows). PROJECT_NAME The name used when building the JAR. RMIC_OPT RMI compiler options. SOURCE_DIR Optional: An alternate directory to serve as the root directory for Java source and Java class resources. If not specified the module directory is treated as the source directory. A Jar module has a number of standard make targets: catalog Rebuild the catalog of Java files, resource files and RMI classes. Used after adding or removing such files from a package. clean Remove JAR and the .build directory. compile Compile changed Java source files, then compile any changed RMI classes. default Alias for compile. force Compile all, not just dirty, then compile all RMI classes. install Build JAR, then copy it to INSTALL_DIR. javadoc Generate Javadoc for the contents of the JAR

CONTEXT_RESOURCES The names of individual files or directories that should be copied from the module directory into the root of the WAR. Relative pathnames will be maintained when copied. Directories are copied recusively (but directories named 'CVS' are pruned). INSTALL_DIR The directory to which the WAR should be copied after it is built. INSTALL_LIBRARIES A space seperated list of libraries that should be installed into the WEB-INF/lib directory. The entries here should be a subset of PROJ_CLASSPATH. JAVADOC_DIR The directory to which Javadoc should be written. JDK_RELEASE Optional: The release of the JDK to use when compiling. JDK_VENDOR Optional: The JDK vendor to use when compiling. META_RESOURCES The names of any resources that should be copied from the module directory into the WAR's META-INF directory. This is optional. PACKAGES The names of all packages in the module. PROJ_CLASSPATH A space seperated list of the classpath entries (typically, other JAR files) used when compiling. Absolute or relative pathnames may be used. Use the forward slash as the path seperator (even on Windows). PROJECT_NAME The name used when building the WAR. SOURCE_DIR Optional: An alternate directory to serve as the root directory for Java source and Java class resources. If not specified the module directory is treated as the source directory. WEB_INF_RESOURCES The names of files that should be copied into the WEB-INF directory. This should include the application-server specific deployment descriptor. The J2EE deployment descriptor, web.xml, is required and automatically copied. catalog Rebuild the catalog of Java files, resource files and RMI classes. Used after adding or removing such files from a package. clean Remove WAR and the .build directory. compile Compile changed Java source files, then compile any changed RMI classes. default Alias for compile. force Compile all, not just dirty, then compile all RMI classes. install Build WAR, then copy it to INSTALL_DIR. javadoc Generate Javadoc for the contents of the JAR war Build the WAR, recompiling files and copying resources as necessary.

deploy Build the JAR, then copy it to the JBOSS_DIR/deploy directory to be hot deployed into the running jBoss server. run Deploys the JAR, then starts the jBoss server. run-ejx Runs the jBoss EJX tool (a GUI used to edit deployment descriptors).

The DocBook module is the standout of the available modules, because it doesn't compile any Java code at all. The DocBook module is used to create documentation and manuals, using the DocBook SGML format. DocBook is a standard SGML format for online and print media. It is widely used by publishers, including O'Reilly. More information on DocBook is available at http://www.oasis-open.org/docbook/. The current implementation of the DocBook module allows documentation to be produced as HTML. PDF output is being developed as well.

clean Wipes out all derived and temporary files. default Builds each of the targets specified by FORMATS. html Builds HTML output, placing the results into the html subdirectory. install Installs each of the targets specified by FORMATS. install-html Builds the html target, then copies the results to the install directory.

In addition to variables defined in individual module Makefiles, additional variables can be defined in LocalConfig.mk. These variables will affect all modules.