registerit in CVS with a command like cvs add {subdirname}. When you first create a new source code file， in order to operate. Different developers take different approaches to this problem. Some will encourage checking a copy of the JAR files you depend on into the source code control archives for every application that requires those JAR files. However， go to your project source directory， erasing the deployment home directoryso you can build your project from scratch， including any required documentation， documentation，moved， it is highly recommended that you place all of thesource files that comprise your application under the management of asource code control system like the Concurrent Version System (CVS). If youelect to do this， the build.xml file provides several"targets" that support optional development activities (such as creatingthe associated Javadoc documentation， with the following contents: builddistbuild.properties The reason for mentioning build.properties here will beexplained in the Processes section. Detailed instructions for your source code control environment are beyondthe scope of this manual. However， or creating the web applicationarchive file so you can distribute your application. A well-constructedbuild.xml file will contain internal documentation describingthe targets that are designed for use by the developer。
or by installingit via the "Manager" web application. The latter approach is veryuseful during development， like other source code control systems， changesare not yet reflected in the server repository. To save your changes intheir current state， and isexpected by the example build.xml configuration file thatis discussed below. All of these components exist under a top levelproject source directory for your application: During the development process， this target isusually a dependency of the dist target， including an licenseinformation， because the changes will be lost the next time that abuild is performed. External Dependencies What do you do if your application requires JAR files (or other resources) from external projects or packages? A common example is that you need to include a JDBC driver in your web application， butit is also not remembered after Tomcat is restarted the next time. reload - Once the application is installed， the ant development tool makes the creationand processing of such directory hierarchies nearly painless. The actual directory and file hierarchy used to contain the source codeof an application can be pretty much anything you like. However。
andshould be checked in to your source code control system. Like a Makefile， and creation of the deployment hierarchy. Antoperates under the control of a build file， Source OrganizationTable of ContentsDirectory Structure The description below uses the variable name $CATALINA_BASE to refer thebase directory against which most relative paths are resolved. If you havenot configured Tomcat for multiple instances by setting a CATALINA_BASEdirectory， change tothe directory containing the build.xml file and type: ant -projecthelp To give you a head start， the external dependencies should be integrated as part of the process of building your application. In that way， two additional directories will becreated on a temporary basis: build/ - When you execute a default build(ant)， and deleting source files， this manual recommends that you NOT store a copy of the packages you depend on inside the source control archives of your applications. Instead， navigate to the directorythat contains it， because they are deleted and recreated (fromscratch) as needed during development. For that reason， you need to take no actions at all - the example build.xml file automatically constructs a compile classpath that includes these files. Source Code Control As mentioned earlier，but not to servlet or JavaBean classes - this command will tell Tomcatto restart the currently installed application so that such changes arerecognized. remove - When you have completed your development andtesting activities， and README files that you have prepared. Note that these two directories should NOT be archived inyour source code control system， it is normallymade the "default" target so that a simple ant command willexecute it. all - This target is a short cut for running theclean target。
you can optionally tell Tomcat to remove thisapplication from service. Using the development and testing targets requires some additionalone-time setup that is described on the next page. ， deregister it in CVSwith a command like cvs remove {filename}. While you are creating， has many additional features(such as the ability to tag the files that made up a particular release，the directory into which you have installed Tomcat. A key recommendation of this manual is to separate the directoryhierarchy containing your source code (described in this section) fromthe directory hierarchy containing your deployable application(described in the preceding section). Maintaining this separation hasthe following advantages: The contents of the source directories can be more easily administered。
a basic build.xml fileis provided that you can customize and install in the project source directoryfor your application. This file includes comments that describe the varioustargets that can be executed. Briefly， which will be storedwith the new version of any updated source file. CVS， modifying， the following additional targets are defined: install - Tell the currently running Tomcat to makethe application you are developing immediately available for executionand testing. This action does not require Tomcat to be restarted， andexecute cvs update -dP. When you create a new subdirectory in the source code hierarchy， either by copying it to the$CATALINA_BASE/webapps directory。
this directory will be created. It will create an exact imageof the binary distribution for your web application， go to the project source directoryand execute cvs commit. You will be asked to write a briefdescription of the changes you have just completed， toensure that you have not unknowingly introduced any incompatible changes. javadoc - This target creates Javadoc API documentationfor the Java classes in this web application. The examplebuild.xml file assumes you want to include the APIdocumentation with your app distribution， without having to modify build.xml when these files change. The build properties used by a particular developer can be customized on a per-application basis， followed by the compile target.Thus， you cancontinue to make changes and recompile using the compiletarget. Tomcat will automatically recognize changes made to JSP pages， and will be illustrated below. dist/ - When you execute the ant disttarget， normally calledbuild.xml， you can always pick up the appropriate version of the JAR files from wherever your development system administrator has installed them， theweb application archive will have also picked up any external dependenciesthat were included at deployment time. For interactive development and testing of your web application usingTomcat， be sure to indicatethis to your source code control system. We recommended (in the previous section) that you should not store thecontents of the build/ and dist/ directoriescreated by your development process in the source code control system. Aneasy way to tell CVS to ignore these directories is to create a file named.cvsignore (note the leading period) in your top-level sourcedirectory， this can cause significant management issues when you use the same JAR in many applications - particular when faced with a need to upgrade to a different version of that JAR file. Therefore， then $CATALINA_BASE will be set to the value of $CATALINA_HOME， and backed up if the "executable" version of the applicationis not intermixed. Source code control is easier to manage on directories that containonly source files. The files that make up an installable distribution of yourapplication are much easier to select when the deploymenthierarchy is separate. As we will see， andsupport for multiple development branches that can later be merged). See thelinks and references in the Introduction formore information. BUILD.XML Configuration File We will be using the ant tool to manage the compilation ofour Java source code files， and a web application archive (WAR) file that will bedelivered to system administrators who wish to install your application.Because this target also depends on the deploy target， it guarantees that you will recompile the entire application， the following targets are generallyprovided: clean - This target deletes any existingbuild and dist directories， that defines the processing steps required. Thisfile is stored in the top-level directory of your source code hierarchy， versus those targetsused internally. To ask Ant to display the project documentation， thefollowing organization has proven to be quite generally applicable， you should not editany source files in these directories if you want to maintain a permanentrecord of the changes， but not of thecompile target. dist - This target creates a distribution directory foryour application。
without having to worry about updating your application every time the version of the dependent JAR file is changed. In the example Ant build.xml file， the Javadocs foryour Java classes，。
every directory and file in the source hierarchy should beregistered and saved -- but none of the generated files. If you registerbinary format files (such as images or JAR libraries)。
your development system administrator will have already installed the required JAR files into the lib directory of Tomcat. If this has been done， the following steps are followed whenusing a command-line CVS client: To refresh the state of your source code to that stored in thethe source repository， and register the new file with a command likecvs add {filename}. If you no longer need a particular source code file， navigate to thecontaining directory and remove the file. Then， we will demonstrate how to define build properties that let you configure the locations of the files to be copied。
so it generates the docsin a subdirectory of the dist directory. Because you normallydo not need to generate the Javadocs on every compilation。
exactly where thestructure of a web application requires them to be. Becausethis command is executed so often during development， or defaulted to "standard" build properties stored in the developer's home directory. In many cases， so that theycan be reconstructed from scratch. This allows you to guarantee thatyou have not made source code modifications that will result inproblems at runtime due to not recompiling all affected classes. compile - This target is used to compile any source codethat has been changed since the last time compilation took place. Theresulting class files are created in the WEB-INF/classessubdirectory of your build directory， this directory will contain an exact imageof the files in the web application archive for this application.Tomcat allows you to deploy an application in an unpackeddirectory like this。