Menu
▾
▴
[642ad0]: / docs / src / developer / gettingStarted.docbook Maximize Restore History
423 lines (303 with data), 35.9 kB
<!--
Instructions for new developers to get started. This is one chapter in
the DrJava Developer Documentation. All chapters are joined into a single
document in devdoc.docbook.
@version $Id: devdoc.docbook 3498 2006-01-17 22:36:31Z dlsmith $
-->
<chapter id="gettingStarted">
<title>Getting Started</title>
<para>This section provides a step-by-step tutorial for new DrJava developers on setting up a build environment and making modifications to the code base. It discusses much of the material only lightly, presenting just the essential information required to get everything working properly. Links are interspersed to more comprehensive treatment elsewhere.</para>
<section>
<title>Setting up Your Accounts</title>
<section>
<title>SourceForge</title>
<para>The DrJava project is hosted by SourceForge.net. We take advantage of SourceForge's source control, Web space, bug tracking, and mailing list features. Regardless of whether you will be committing code or not, we recommend registering for a SourceForge user account to provide a point of contact in the Tracker forums. If you will be a member of the DrJava development team, the project administrators will add your account to the project to allow you to commit code and respond to bugs and feature requests.</para>
<itemizedlist>
<listitem><para>If you don't already have a SourceForge user account, go to <ulink url="http://sourceforge.net">http://sourceforge.net</ulink> and click on "Create Account"; follow the directions until your account is set up and you can log in to the site.</para></listitem>
<listitem><para>Visit the <ulink url="http://sourceforge.net/projects/drjava">DrJava project page</ulink>. The "Tracker" and "Code" sections (you made need to click on "More" first) are particularly relevant. You should also follow the "Mailing Lists" link and consider subscribing to one of the mailing lists. <literal>drjava-hackers</literal> is a high-traffic list containing all initial bug and feature request posts; <literal>drjava-users</literal> is generally limited to messages announcing new development and stable application releases.</para></listitem>
<listitem><para>If you are a member of the Rice DrJava development team, ask a project administrator to add you as a project member.</para></listitem>
</itemizedlist>
</section>
<section>
<title>Java PLT Group at Rice</title>
<para>For Rice students wishing to work with the DrJava developer team, you should also do the following:
<itemizedlist>
<listitem><para>Get a Computer Science Department Unix account, if you don't already have one. This account is distinct from the Owlnet account given to all undergraduates, and will allow you to login and develop in the PLT computer lab. You can pick up an application from the department secretaries; have it signed by Corky Cartwright.</para></listitem>
<listitem><para>Subscribe to the <literal>drjava</literal> mailing list. You can do so here: <ulink url="https://mailman.rice.edu/mailman/listinfo/drjava-l">https://mailman.rice.edu/mailman/listinfo/drjava-l</ulink>. This list is the main electronic forum for communication among the team members (like a course discussion board). Feel free to post your ideas or ask for help here.</para></listitem>
</itemizedlist>
</para>
</section>
</section>
<section>
<title>Installing Essential Software</title>
<para>You will need to have three programs properly installed and set up on any system you intend to use for development. These are the Sun Java Development Kit (for compilation), a Subversion client (to access the source code repository), and Apache Ant (for scripted building).</para>
<section id="installJDK">
<title>Sun Java Development Kit</title>
<para>If it's not already installed on your system, you can download the JDK from <ulink url="http://java.sun.com">Sun's Web site</ulink>. You will need to have installed the JDK version 5 (note the distinction on the download pages between a Java <emphasis>Runtime Environment</emphasis>, which just contains the tools needed to <emphasis>run</emphasis> Java programs, and a Java <emphasis>Development Kit</emphasis>, which contains a compiler and other tools, in addition to the runtime application). You may also want to install JDK version 6. The DrJava sources depend on Java 5 (but not 6) language features and APIs. (Note: theoretically, any Java 5 compiler should be able to handle the DrJava sources. However, there are currently some dependencies on Sun's tools in the main DrJava code module, so you will need to have those tools available.)</para>
<para>You should set up your command-line environment so that you can access the <command>java</command> and <command>javac</command> commands. See <link linkend="environmentSettings">Command-Line Environment Settings</link> for details.</para>
<note>
<title>Rice Java PLT</title>
<para>On the Rice Computer Science department network, various versions of the JDK are installed at <filename>/home/javaplt/java</filename>, organized by platform (such as <filename>Linux-i686</filename>) and then by version.</para>
</note>
<note id="osx-java">
<title>Mac OS X</title>
<para>Java is built in to Mac OS X, which makes Apple, rather than Sun, the main source of core Java software for the platform. Java 5 is only supported since version 10.4 (Tiger) of the operating system, and Java 6 requires OS X 10.5 (Leopard) and a recent (64-bit Intel) machine. If you haven't done so already, you should install the Xcode Tools, distributed on CD or DVD with the OS, and also available from the <ulink url="http://developer.apple.com">Apple Developer Connection</ulink> (free membership may be required). This will contain <emphasis>at least</emphasis> the Java 1.4 tools. If you need to, you can then dowload the Java 5 or Java 6 tools from the ADC Web site. To see what is currently installed, go to <filename>/System/Library/Frameworks/JavaVM.framework/Versions</filename>.</para>
<para>To select which version of Java is used to launch applications and to run command-line tools, run <filename>/Applications/Utilities/Java/Java Preferences</filename>. There is no need to manually adjust the <literal>PATH</literal> variable or manipulate symbolic links.</para>
<para>For more information on Java in OS X, see <ulink url="http://developer.apple.com/java">Apple's Java development page</ulink> and, specifically, <ulink url="http://developer.apple.com/java/faq/">this FAQ</ulink>.</para>
</note>
</section>
<section id="installSubversion">
<title>Subversion Client</title>
<para>The DrJava source code is stored on a SourceForge server using Subversion. This allows changes to the sources to be tracked and permits a number of developers to work on different parts of the code at the same time. In order to access the source repository, you will need a Subversion client. See the <ulink url="http://subversion.tigris.org/">Subversion Web site</ulink> for links to a client for your platform.</para>
<para>Your command-line path will need to be set up so that the <command>svn</command> command is available. See <link linkend="environmentSettings">Command-Line Environment Settings</link> for details.</para>
<note>
<title>Rice Java PLT</title>
<para>On the Rice Computer Science department network, the Subversion client is located at <filename>/home/javaplt/packages/subversion-1.5.4/bin</filename>.</para>
</note>
<note>
<title>Mac OS X</title>
<para>Subversion is installed with recent versions of Xcode Tools. See the <link linkend="osx-java">previous note</link> for instructions on installing Xcode. After this installation, you can find out if you have Subversion by typing <literal>svn --version</literal> at the command line.</para>
</note>
</section>
<section id="installAnt">
<title>Apache Ant</title>
<para>Ant is a build script interpreter — loosely a Java- and XML-based alternative to the <command>make</command> command on Unix systems. It can be downloaded from <ulink url="http://ant.apache.org">Apache's Web site</ulink>. Decompress the package and copy the <filename>jakarta-ant-xxx</filename> folder to a convenient location (such as <filename>/usr/local</filename>, your home directory, or <filename>C:\Program Files</filename>).</para>
<para>Once installed, you should follow Apache's installation recommendations for setting up your environment. See <link linkend="environmentSettings">Command-Line Environment Settings</link> for details.</para>
<note>
<title>Rice Java PLT</title>
<para>On the Rice Computer Science department network, Ant is available in the <filename>/home/javaplt/packages/apache-ant-1.x.x</filename> directories.</para>
</note>
<note>
<title>Microsoft Windows (95, 98, & Me)</title>
<para>According to the Ant installation instructions, the <command>ant</command> executable script will not work correctly in older Windows systems if Ant is installed in a location with a long filename. They recommend creating a <filename>C:\ant</filename> directory. See the <ulink url="http://ant.apache.org/manual">Ant Manual</ulink> for details.</para>
</note>
<note>
<title>Mac OS X</title>
<para>Ant is installed with the Xcode Tools. See the <link linkend="osx-java">previous note</link> for details.</para>
</note>
</section>
<section id="environmentSettings">
<title>Command-Line Environment Settings</title>
<para>Once you've installed these programs on your system, you'll need to ensure that your command-line environment is set up properly. Because shells vary widely in the conventions they use, you may need to familiarize yourself with the idiosyncrasies of your particular platform.</para>
<note>
<title>Unix</title>
<para>On Unix systems, the environment variables can be set by modifying a login script file. Assuming you are running a <command>bash</command> shell, you can see how your environment is currently set up by typing <literal>env</literal>. You can also use <command>which</command> to test the <literal>PATH</literal> variable — for example, <literal>which ant</literal> will print a full path to the <command>ant</command> executable if Ant is correctly set up. It is important to check the current settings before making changes.</para>
<para>To make changes to the default environment settings, edit (or create) the <filename>.bashrc</filename> file in your home directory to contain the needed declarations. (On some systems, such as Mac OS X or the Rice Owlnet network, you should use the <filename>.profile</filename> file instead.) Under <command>bash</command>, an environment variable is set with a command like the following:
<informalexample><para><literal>export ANT_HOME=/usr/local/ant</literal></para></informalexample>
Note that path-like variables (such as <literal>PATH</literal> and <literal>CLASSPATH</literal>) should use a colon (<literal>:</literal>) to delimit filenames. You can use a variable's value at any time (both in a later declaration and at the command line) with syntax like <literal>$ANT_HOME</literal>.</para>
<para>After making changes, you will need to open a new terminal window before the settings will take effect.</para>
</note>
<note>
<title>Microsoft Windows</title>
<para>Each version of Windows has a slightly different method for setting environment variables. In most cases, you can select <guibutton>System</guibutton> in the Control Panel (or choose <guibutton>Properties</guibutton> after right-clicking on <guibutton>My Computer</guibutton>), and then find a button for <guibutton>Environment Variables</guibutton> (usually on the <guibutton>Advanced</guibutton> tab). You may need to log out and back in before your settings will take effect. Note that path-like variables (such as <literal>PATH</literal> and <literal>CLASSPATH</literal>) should use a semicolon (<literal>;</literal>) to delimit filenames. You can use a variable's value at any time (both in a later declaration and at the command line) with syntax like <literal>$ANT_HOME</literal> [TODO: is this true?].</para>
<para>If you're using Cygwin (a Unix-like environment for Windows), many of the Unix instructions above are relevant. You <emphasis>could</emphasis>, for example, define the environment variables in a <filename>.bashrc</filename> file. However, it's probably best to use the system-wide Windows facilities (such as the <guibutton>Environment Variables</guibutton> dialog box) whenever possible. One problem you will encounter when using Cygwin is that Windows filenames and paths are formatted differently from Cygwin filenames and paths. Generally, Java applications (including Ant, with some exceptions) will only be able to handle <emphasis>Windows</emphasis>-style paths. On the other hand, some Cygwin programs expect Cygwin's Unix-like paths. To deal with this problem, you may need to thoroughly familiarize yourself with the <command>cygpath</command> command, which converts between the two formats.</para>
</note>
<para>The following table summarizes the variables and corresponding values that should be set up on your system:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Variable</entry>
<entry>Value</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>JAVA5_HOME</literal></entry>
<entry>Location of the Java 5 installation. The specified directory should have a <filename>bin</filename> subdirectory containing <command>java</command>, <command>javac</command>, <command>javadoc</command>, etc.</entry>
<entry>Required in order to locate the correct standard libraries when compiling. Rice CS: <filename>/home/javaplt/java/Linux-i686/1.5</filename>.</entry>
</row>
<row>
<entry><literal>JAVA6_HOME</literal></entry>
<entry>Location of the Java 6 installation. The specified directory should have a <filename>bin</filename> subdirectory containing <command>java</command>, <command>javac</command>, <command>javadoc</command>, etc.</entry>
<entry>Optional; makes it possible to explicitly request that Java 6 be used by the Ant script when running or testing. Rice CS: <filename>/home/javaplt/java/Linux-i686/1.6</filename>.</entry>
</row>
<row>
<entry><literal>ANT_HOME</literal></entry>
<entry>Location of the Ant installation. The specified directory should contain the <filename>bin</filename> and <filename>lib</filename> subdirectories.</entry>
<entry>The Ant command generally needs this in order to work correctly (although on some platforms Ant will work fine without it). Rice CS: <filename>/home/javaplt/packages/ant</filename>.</entry>
</row>
<row>
<entry><literal>PATH</literal></entry>
<entry>For example, <literal>$PATH:$JAVA_HOME/bin:$ANT_HOME/bin</literal>.</entry>
<entry>You will want the <command>ant</command> command on your path, as it will be used often. The Ant script requires that <command>java</command>, <command>javac</command>, and <command>svn</command> be available from the command line. You may want to explore the current settings before you make any modifications. Note the use of previously-declared environment variables in this example. Also keep in mind that the <emphasis>first</emphasis> matching location for a command in the path will shadow all later matches.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>
</section>
<section id="basicTutorial">
<title>Accessing and Modifying the Source Code</title>
<para>Now that your development system is ready, you can get to work! These instructions will demonstrate some of the typical tasks you'll want to accomplish in browsing, building, and modifying the DrJava sources.</para>
<section>
<title>Downloading the Sources</title>
<para>You can use Subversion to get a copy of the DrJava source code. In Subversion terminology, downloading a fresh copy is (usually) synonymous with "checking out" the code. You can download the sources with the following command:
<informalexample><para><literal>svn co https://drjava.svn.sourceforge.net/svnroot/drjava/trunk/drjava</literal></para></informalexample>
A <filename>drjava</filename> directory will be created in your working directory, and Subversion will output the name of each file it downloads.</para>
<para>Note that the above command only checks out <emphasis>part</emphasis> of the DrJava sources. The sources are divided into independent modules, each a subdirectory of <filename>trunk</filename>. Each module can be built, tested, and modified without the others. You can check out a different directory by simply modifying the URL given to Subversion.
<warning>
<para>While it is possible to check out the entire <filename>https://drjava.svn.sourceforge.net/svnroot/drjava</filename> directory, you <emphasis>should not</emphasis> do so! This top-level directory contains dozens of copies of the sources, including snapshots at various stages of development. If you download this directory, it will take a lot of time and disk space.</para>
</warning>
The full list of <filename>trunk</filename>'s subdirectories includes:
<variablelist>
<varlistentry>
<term><literal>drjava</literal></term>
<listitem><para>The main application, containing the bulk of the code. Building this module will create the DrJava application.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>dynamicjava</literal></term>
<listitem><para>The DynamicJava interpreter, which implements the functionality behind the Interactions Pane.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>javalanglevels</literal></term>
<listitem><para>A Java preprocessor used to provide the Language Levels facility.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>plt</literal></term>
<listitem><para>General-purpose utility classes, including things that are "missing" from the Java API like predicates and tuples.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>platform</literal></term>
<listitem><para>A collection of platform-dependent code, such as the concrete compiler interfaces and special OS-specific GUI setup instructions.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>docs</literal></term>
<listitem><para>The project documentation, including this document and end-user help files.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>eclipse</literal></term>
<listitem><para>A wrapper for the interactions pane that allows it to be run as a plug-in to the Eclipse IDE.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>jedit</literal></term>
<listitem><para>A similar wrapper for the interactions pane in the JEdit IDE.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>misc</literal></term>
<listitem><para>Files that don't belong in a specific module.</para></listitem>
</varlistentry>
</variablelist></para>
<para>You may find it helpful to streamline the check-out process by creating an alias or a script file for the check-out command.</para>
</section>
<section>
<title>Building the Sources</title>
<para>In the <filename>drjava</filename> directory, you will find the file <filename>build.xml</filename>. This is the module's Ant script, containing instructions that automate a variety of development tasks. While in the <filename>drjava</filename> directory, enter:
<informalexample><para><literal>ant help</literal></para></informalexample>
or just
<informalexample><para><literal>ant</literal></para></informalexample>
The name <literal>help</literal> refers to an Ant <firstterm>target</firstterm>. Different targets can be used to accomplish different tasks, and they are often set up to recognize dependencies. For example, the <literal>test</literal> target recognizes its dependency on the <literal>compile</literal> target; when you ask Ant to run the tests, it will automatically compile them first. In this particular example, the <literal>help</literal> target (which is set up as the default when none is specified) simply prints a message about the script and the environment settings it expects. If an error occurs here, Ant may not be properly set up.</para>
<para>Second, enter the following command:
<informalexample><para><literal>ant -p</literal></para></informalexample>
You will see a list of all the documented targets in the project. Note that, due to the dependencies between targets, the <literal>build</literal> target will run <literal>generate-source</literal>, <literal>compile</literal>, <literal>test</literal>, and <literal>jar</literal>. That is, it will do everything required to build and test a new application. Try it out:
<informalexample><para><literal>ant build</literal></para></informalexample>
The process will take awhile. Ant will generally log each action it takes to the console; you should make sure you can follow what's going on. Here's a summary of the major steps:
<itemizedlist>
<listitem>
<formalpara>
<title><literal>generate-source</literal></title>
<para>Performs any necessary preprocessing before the Java compiler is invoked. For example, a <filename>Version.java</filename> file is created so that a unique version number for this build will be accessible to the code (in particular, the DrJava application's <guilabel>About</guilabel> dialog box).</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>do-compile</literal></title>
<para>Invokes the <command>javac</command> compiler (the specific version used depends on your command path). Generated class files will be placed in a new <filename>classes</filename> directory, with the subdirectories <filename>base</filename> and <filename>test</filename> for standard and test classes, respectively. Any compiler errors or warnings will be printed to the console. Where warnings are expected, they will be tagged in the code with a <literal>@SuppressWarnings</literal> annotation. Thus, any warnings you see during compilation highlight a problem that should be addressed.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>unjar-libs</literal></title>
<para>Expands the <filename>*.jar</filename> files in the <filename>lib</filename> directory into <filename>classes/lib</filename>. These library classes will be bundled with the finished product.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>test</literal></title>
<para>Runs the JUnit tests in <filename>classes/test</filename> (the specific version of <command>java</command> used depends on your command path). This will constitute the bulk of the build time. A summary of the running time for each test will be logged, and if a failure occurs, testing will halt immediately.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>jar</literal></title>
<para>Creates the <filename>drjava.jar</filename> file. This is the executable application. It will contain a <filename>MANIFEST.MF</filename> file listing the build's unique version number and your user name.</para>
</formalpara>
</listitem>
</itemizedlist>
</para>
<para>Now that you've built the application, you can run it with the following command:
<informalexample><para><literal>java -jar drjava.jar</literal></para></informalexample>
You can also run the application in some systems by double-clicking on the <filename>drjava.jar</filename> file. And the Ant script includes a variety of <literal>run</literal> commands that act as shortcuts: <literal>ant run-jar</literal>, for example, will compile, build a jar file, and run the application with assertions and error logging turned on.</para>
<note>
<title>Mac OS X</title>
<para>When you run the <filename>drjava.jar</filename> file, the DrJava GUI may not look quite right. This is because the official OS X application release wraps the jar file in some additional packaging and settings. However, all the essential functionality should still be there in your unofficial version.</para>
</note>
</section>
<section>
<title>Modifying the Sources</title>
<para>Once you've got a fresh copy of the sources and verified that they will build correctly, you're ready to start making modifications. The source files are stored in the <filename>src</filename> directory; you should be able to explore and edit them in any IDE or text editor. IDEs will be able to interface with the build script with various degrees of sophistication. If the IDE you use does not support Ant scripts (or you'd rather not bother with making it work properly), you can either do most of your building and testing from the command line, or do your "casual" development in the IDE, and just run the scripts when you are ready to commit a change. In the latter case, you'll want to keep a few things in mind:
<itemizedlist>
<listitem><para>It's best to consider the contents of the <literal>drjava</literal> directory transient — you will want to occasionally delete the directory completely and start from a fresh checkout. Thus, IDE-specific files like project descriptions are better stored somewhere else (unless you don't mind recreating them).</para></listitem>
<listitem><para>By default, the <command>javac</command> compiler places the <filename>*.class</filename> files it generates in the same location as their sources. That approach clutters up the <filename>src</filename> directory significantly, and should be avoided. You should also avoid putting the compiled classes in one of the Ant script's target locations (such as <filename>classes/base</filename>), as that might lead to confusing behavior when you invoke the script later. The best option is to either create a <filename>classes/<replaceable>ide-name</replaceable></filename> directory in which to place your classes, or just store the IDE-compiled classes somewhere else entirely.</para></listitem>
<listitem><para>Your IDE's classpath should contain all the jar files in the <filename>lib</filename> directory (but not the <filename>lib/buildlib</filename> directory, with the exception of <filename>lib/buildlib/junit.jar</filename>).</para></listitem>
<listitem><para>You'll need to invoke the <literal>generate-source</literal> Ant target before you attempt to compile in the IDE (that is, unless the files have already been generated). Otherwise, some sources will be missing and the compilation will fail. Some IDEs may also have trouble with these files occasionally disappearing and reappearing, so you might want to ensure that the sources are in a consistent state before opening or closing the IDE application.</para></listitem>
</itemizedlist>
If you're using Eclipse, see the <link linkend="eclipse">Eclipse section</link> for instructions on setting up a project.</para>
<para>To get oriented and understand the program design, you may want to browse the <link linkend="systemArchitecture">System Architecture</link> notes, along with the javadocs from the latest release (available at <ulink url="http://drjava.org">drjava.org</ulink>). You can also generate your own up-to-date copy of the javadocs by invoking the Ant <literal>javadoc</literal> target. Before you make significant changes to the code, you should familiarize yourself with the <link linkend="bestPractices">Development Best Practices</link> section of this document.</para>
<para>Once you've made some modifications, you'll probably want to try them out. The Ant script offers a couple of ways to do this. First, you can enter
<informalexample><para><literal>ant run</literal></para></informalexample>
This will run the DrJava application located in the <filename>classes/base</filename> directory. You can also run the JUnit tests. You can run a <emphasis>specific</emphasis> test (rather than waiting for <emphasis>all</emphasis> of them to run) by typing
<informalexample><para><literal>ant -Dtest-spec=<replaceable>filterString</replaceable> test</literal></para></informalexample>
All test classes in <filename>classes/test</filename> with paths matching <replaceable>filterString</replaceable> will be run by JUnit.</para>
</section>
<section>
<title>Submitting Your Changes</title>
<para>When you're ready to submit the changes you've made to the Subversion archive (in Subversion terminology, <firstterm>commit</firstterm> the changes), and assuming you're a member of the DrJava SourceForge project, you can do so with the Ant script. While the <command>svn</command> command could be invoked directly from the command line (or some IDEs), using Ant is the preferred approach because it allows you to ensure that your changes do not break any functionality or conflict with other changes that have been made by other developers concurrently. The Ant script will run a fresh compile and all tests before committing your changes.</para>
<para>If this is the first time you've committed a change on your current system, you will need to perform a manual commit in order to check your authentication. You can do this by checking out the <filename>https://drjava.svn.sourceforge.net/svnroot/drjava/trunk/misc/authenticate</filename> directory and following the instructions in <filename>authenticate/authenticate.txt</filename>. When you commit, you will be prompted for a password (if the username is incorrect, just hit Enter and you will be prompted for a username as well). [TODO: Improve this process, if possible. It would be nice if there were just an "svn authenticate" command.] That authentication information will be stored on your system, and future commits will not require you to reenter your password.</para>
<para>After your system is set up for automatic authentication, you can perform a commit with the following:
<informalexample><para><literal>ant commit</literal></para></informalexample>
The major steps in this process are enumerated below:
<itemizedlist>
<listitem>
<formalpara>
<title><literal>clean-intermediate</literal></title>
<para>Removes all intermediate build products — that is, files that didn't come from the Subversion repository and that aren't finished products. This will include generated sources and the <filename>classes</filename> directory. Note that, typically, this target (or just <literal>clean</literal>) is also invoked directly as the need arises.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>clean-products</literal></title>
<para>Removes all final build products. This will include DrJava jar files and generated javadocs.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>update</literal></title>
<para>Downloads all new changes that have been made in the Subversion repository since you last checked out (or updated) your sources. The command will list all filenames that are being changed locally; after the update, the <literal>status</literal> Subversion command will display any discrepancies between the repository and your working copy. If there is a conflict in the update (you and someone else have both changed the same file, or perhaps specifically an overlapping part of the same file), Subversion will let you know and give you a chance to manually merge the changes. This target is also typically invoked directly as the need arises (and you should use it <emphasis>often</emphasis> to catch conflicts while they are still small).</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>build</literal></title>
<para>The project is built from scratch, as described previously. This ensures that your submission is a valid, tested copy of the program.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>clean-intermediate</literal></title>
<para>To prevent extraneous messages when the commit takes place, the project is cleaned up once again.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title><literal>commit</literal></title>
<para>You are first prompted to enter a log message describing the changes you've made. These are generally just one-line summaries. Keep in mind that your message will be read in the context of the entire project when, for example, someone wants to know what changes have been made to the application recently. If you need help in remembering what files you've touched, look at the output of <literal>update</literal>, which ran just before the project was rebuilt. Next, each file you've modified will be uploaded and the changes will be assigned a fresh revision number.</para>
</formalpara>
</listitem>
</itemizedlist>
</para>
</section>
</section>
</chapter>
