<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>

  <header>
    
    <title>GOM: Good Practices</title>
	  <authors>
  		<person name="Adam R. B. Jack" email="ajack@apache.org"/>
  	  </authors>
  	</header>

<body>  	
	
	<section><title>Why good practices?</title>
		<p>There are a number of reasons why an optimal Apache Gump Descriptor ought be
			a goal. Some are to be nice to Gump, and it's resources. Some are so
			Gump can be nice to your project. <strong>In short</strong>, don't ask Gump to do more than it needs, and don't put
			barriers in the way of the frequent Gumping of your project. 
		</p>
	</section>
  	
  	<section><title>Ant</title>  	
  		<section><title>Selecting a minimal target</title> 
  			<p>Select an ant target (from your build.xml, or whichever) that minimally compiles the code, and creates output jars.
  				Try to avoid targets that create full distributions (in numerous formats), or perform unnecessary work like
  				javadoc generation. 
  			</p>
  			<p>For your *-test project (see 'Use a separate Test Project') do unit tests only.</p>
  		</section>  	
	  	<section><title>Let Gump set your final jar name</title>
	  		<p>Gump runs set @@DATE@@, which ought be set into the
	  		jar name. Use a <link href="builder.html#property">property</link> for this.
  			</p>
	  	</section>
	  	<section><title>Example</title>	  		
  			<source>
        &lt;ant buildfile=&quot;build.xml&quot; target=&quot;gump&quot;&gt;
          &lt;property name=&quot;DATE_STAMP&quot; value=&quot;@@DATE@@&quot;/&gt;        	
        &lt;/ant&gt;
  				
  			</source>
	  	</section>
  	</section>
  	
  	<section><title>Dependencies</title>
  		<section><title>Use optional dependencies</title>
  		<p>Use a <link href="project.html#option">option</link> instead of
  		<link href="project.html#depend">depend</link> when at all possible.</p>
  		<p>The fewer mandatory dependencies a project has the more often it will
  			be Gumped, the better <em>Friend Of Gump</em> it'll be, and
  			will make a much better dependency for downstream projects.</p>
  		<p>Project often set dependencies on <em>junit</em> or <em>checkstyle</em>
  			and then fail to even get Gumped to <em>compile</em> when those fail.
  			Setting those two to optional, and then making the buildfile check
  			if they are available before attempting the task is a nice way
  			to go.</p>  		
  		</section>
  		<section><title>Depend upon ant with inherit="runtime"</title>	
  			<p>This way, you only pick up the jars it needs to run, you don't
  				need more cluttering the classpath.</p>
  		</section>
  	</section>
  	
  	<section><title>Projects</title>
  		<section><title>Use a separate Test Project</title>
  		<p>If at all possible, split your project into (at least) two -- one (named <em>your-project</em>) being the main
  			compilation/archive &amp; the other (named <em>your-project</em><strong>-test</strong>) that
  			just runs unit tests.
  		</p>
  		<p>This requires only the second to depend upon <em>junit</em>, say &amp; reduces the dependencies
  			of the first.
  		</p>
  		<p>This allows downstream dependees to select which of your projects they wish to depend upon. If they depend upon 
  			<em>your-project</em> (and <strong>perhaps optionally</strong> on <em>your-project-test</em>) then
  			if some obscure unit test fails they still get Gumped &amp; don't miss a run.</p>
	  	</section>
  	</section>
  	
</body>
</document>
