Like nearly every software project, jEdit is built from its source code using what is called a "make" or "makefile" system. These terms come from the original "make" utility that was created for use on the UNIX operating system; there are now a variety of makefile utilities available for all operating systems. Besides the source code and related resources, a makefile system has two main elements. The first is a "makefile", a plain text file that specifies the steps necessary to build the application, such as the invocation of a compiler, an object code linker or an archiving program. The makefile also describes the dependencies among the final product, intermediate files and the underlying source code. This file will be written in a special format designed to satisfy the requirements of the second major element, the "make" utility.

The make utility is a program that interprets the makefile as a set of rules for building or rebuilding any component of the final software product that is out of date because of file modifications. For example, if a modification in a Java source file is made in a project, the make utility, with a properly prepared makefile, will determine that an existing class file corresponding to the source file is out of date. It will accordingly invoke the Java compiler specified in the makefile to recompile the source file. If the final product - for example, a compressed executable archive in JAR format - requires the new class file, the make utility will determine that the JAR file is out of date in relation to the new class file. It will then assemble a replacement archive containing all of the up to date elements.

You can see that a makefile is itself a kind of script program that passes instructions to the make utility. We will not be trying to show you how to write a makefile, but instead how to use the makefile system provided by the jEdit project to build or modify the application. This can give you a start on how to write makefiles for your own projects.

The jEdit project currently uses the Ant makefile program, a creation of the Jakarta Project sponsored by the Apache Foundation (the same people who bring you the leading web server application). Ant is written in Java, so it is particularly well suited for building Java programs. It is also platform and language independent, so it can be used to build software on any operating system that can support a Java runtime environment, and with any programming language.

One of Ant's most attractive features is that its makefiles specify build steps, dependencies and "targets" (or end results) using XML. Not only does this help programmers create and maintain makefiles (or "buildfiles", as they are also called), but it also makes them fairly easily to understand and modify.

If you have downloaded the jEdit application and some of its more popular plugins, you should already have most of what you need to build jEdit from its source code. You will need the Console and AntFarm plugins; downloading these plugins should automatically get you the ErrorList and EditBus plugins.

To illustrate the method for building jEdit, we will work with the current version of jEdit and its source code. To do this yourself, you should already have downloaded and installed your preferred version of a Java Development Kit (JDK). You should also download the source code archive from the jEdit project web site and unpack it into a new directory. Here we will call that directory jEditSource.

Next, make sure your command line parameters for running jEdit do not include the -jar option for the Java application loader (either java, java.exe or javaw.exe, depending on your operating system). The reason for this is that the -jar option masks the classpath normally used by the loader to find Java class files outside of jEdit, and you will need to preserve that classpath when running the Ant system. You should have a CLASSPATH environment variable available to your operating system's shell; the -classpath command line option for the Java application loader should append the full path to jEdit.jar to the existing class path value ($CLASSPATH in Linux, and %CLASSPATH% in Windows). Under either operating system, the target Java class of the loader should be org.gjt.sp.jedit.jEdit, followed by any command line parameters for the jEdit application.

If you are running jEdit under Windows and using jEditLauncher, there is a sample version of this command line provided in the "Set jEdit Parameters" dialog (available from a command line by running jedit /p). If you are running jEdit under Linux or other UNIX-like systems, check your jedit shell script for these values.

Once you have checked and modified as necessary your command line parameters, open jEdit and load the file build.xml from the jEditSource directory. The contents of the buildfile consists of a top-level "project" element:

<project name="jEdit" default="dist" basedir=".">

After this, there are a series of XML target blocks, each containing instructions on build steps and dependencies. We will begin by building the default "dist" target.

Open the AntFarm plugin. Like all plugins, it will appear either in a docking window as part of jEdit's top-level frame window, or in a separate, "floating" frame window of its own, depending on the options you have selected in the "Docking" section of the Global Options dialog. Click the plus sign icon to add an Ant build file. You should see a file browser dialog set to the jEditSource directory. Once you select build.xml and commit the selection, you will see a "tree root" entry in the AntFarm display window for "jEdit build file". Open the tree, select "dist [default]", and click the double arrow icon to "Run Current Target".

That's all you need to do. The Ant system will cause each of the source files in your jEditSource directory tree to be compiled, then assemble the class files with other resources to produce the file jedit.jar in the jEditSource directory. You have just built your own copy of jEdit.

If Ant complains about missing files or classes, it is possible that it cannot find the Java classes needed for compiling jEdit in your copy of the Java Development Kit. Check the value of your CLASSPATH environment variable. It should include the path to a file called tools.jar in the lib directory of your JDK installation. Add it to the CLASSPATH variable or to the value of the -classpath parameter used to launch jEdit. Either way, you will have to restart jEdit (and under some versions of Windows, reboot your machine) so the classpath change will be recognized.

You will notice if you run your new version of jEdit that it does not include help files, and an attempt to open the help documentation will cause an error message to be displayed. This is because the help documentation is compiled from XML source files in DocBook format to HTML files using separate targets in the jEdit build file. Go back to the build.xml file and find the series of four targets beginning with the prefix docs-. These are the build targets for building the HTML and PDF version of the help documentation.

There are two alternative targets for building HTML help documentation. We will use the "docs-html-xsltproc" target, which requires the xsltproc package. The Linux version of this Open Source package is available from xmlsoft.org; a set of binaries for Windows is also available. Install the appropriate binaries and make sure that they are in a directory on your shell's system path.

You will also need the XSL stylesheet files for transforming the XML source code into HTML. They are available from the DocBook Open Repository project. The help documentation will compile either with version 1.44 of the stylesheets or the latest version 1.45. If you are interested, the document `type` definition (DTD) for DocBook XML is available from its official home at OASIS, but it is not necessary to build jEdit's help files.

Finally, you will need to make one change to a file in jEdit's source code distribution to tell the XSL processor where you have put the DocBook XSL stylesheets. Open the file /doc/users-guide/jedithtml.xsl in your jEditSource source code directory and look at or around line 8 for a line that begins <xsl:import href=..... Substitute the full path for the named file, /html/chunk.xsl, with the full path of that file in your own installation. You are then ready to run the "docs-html-xsltproc" target in AntFarm. When you have successfully created the HTML help files, running the "dist [default]" AntFarm target again will yield a version of jEdit complete with help documentation.

You can follow these same steps to build jEdit from the upcoming development releases of jEdit 4.0, or from the source code stored in the project's CVS repository. If you want your version (or one of your versions) of jEdit to be on the "bleeding edge", we will outline in a future article how you can obtain files from the CVS repository, whether or not you are registered with SourceForge or a member of the jEdit development team. Finally, you can add a comment to this article if you encounter problems with these instructions, or if you just want to tell us it works! We hope this summary helps open jEdit's Open Source to more developers, tinkerers, and just plain curious folks.