xdocs/install.xml - platform/external/apache-velocity-engine - Git at Google

 <?xml version="1.0"?>

 <document>

  <properties>
   <title>Velocity Installation</title>
   <author email="jvanzyl@locus.apache.org">Velocity Documentation Team</author>
  </properties>

 <body>

 <section name="Installation">

 <p>
 Velocity runs on a variety of platforms that have installed the Java 2
 Virtual Machine. The J2SDK is required for users who want to compile
 Velocity from its source code.
 </p>

 <p>
 Everything required to build Velocity comes with the distribution, which
 can be obtained from <a
 href="http://jakarta.apache.org/getinvolved/cvsindex.html">CVS</a> or
 from the <a
 href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">nightly
 builds</a>.  However, you will need to install Ant, an excellent
 Java-based build tool.  Ant is also a Jakarta project, and can be
 found <a href="http://jakarta.apache.org/ant/">here</a>.
 </p>

 <p>
 The directory tree of the distribution looks like :
 </p>

 <source><![CDATA[
 jakarta-velocity
   /build        - contains build scripts
   /bin          - where the built jars / classes will go
   /src          - sourcecode for Velocity, Anakia, and Texen
   /docs         - documentation in HTML form
   /docs/api     - Javadocs for Velocity source
   /examples     - example/demonstration code
   /convert      - tools to help convert WebMacro templates
   /test         - test programs and templates
   /xdocs        - source for our documentation
 ]]></source>

 </section>

 <section name="Building">

 <p>
 To make building Velocity easy and consistant, we require a Jakarta project
 called <a href="http://jakarta.apache.org/ant/">Ant</a> version 1.3 or
 higher to perform the build process. We assume that you have followed
 Ant's installation instructions and have it properly installed.  It's not
 difficult, and I think that you will find it an excellent addition to
 your programmer's toolbox.
 </p>

 <p>
 In each case below, it is assumed that you were successful in getting
 the distribution from CVS or as a nightly build, and with the latter,
 were successful in unpacking.  Also, it is assumed that you are starting
 in the 'jakarta-velocity' directory, the root of the distribution tree.
 All directory references will be relative to 'jakarta-velocity'.
 </p>

 <p>
 Change to the <filename>build</filename> directory (<code>cd
 build</code>). Then, to build the jar file, simply type:
 </p>

 <source><![CDATA[
 ant
 ]]></source>

 <p>
 Executing this script will create a <filename>bin</filename> directory
 within the Velocity distribution directory. The <filename>bin</filename>
 directory will contain the compiled class files (inside a
 <filename>classes</filename> directory) as well as a
 <filename>velocity-XX.jar</filename> file, where XX is the current
 version number. Be sure to update your classpath to include Velocity's
 <filename>.jar</filename> file.
 </p>

 <p>
 Note that to build any of the specific build targets, as detailed in
 the <a href="developer-guide.html">developers guide</a>, simply add
 the target name to the command line.  For example, to build the Javadoc
 API documentation :
 </p>

 <source><![CDATA[
 ant javadocs
 ]]></source>

 <p>
 Velocity should build 'out of the box', independent of your classpath.
 If you get an error building Velocity, try a different nightly build (as
 sometimes we make a mistake and the CVS at the time of the nightly
 snapshot isn't complete) or refresh from CVS (you might have gotten a
 CVS snapshot while a developer was checking things in.)
 </p>

 <p>
 If the problems persist, do not hesitate to ask the Velocity community
 via our mail lists. They can be found <a
 href="http://jakarta.apache.org/site/mail.html">here</a>. Please read
 and understand the the guidelines for participating in any Jakarta mail
 list.
 </p>

 </section>

 <section name="Testing Your Installation">

 <p>
 The Velocity developers use an automated test facility, and it is
 included in the distribution. You can use it to make sure that all is
 well with your build of Velocity.
 </p>

 <p>
 To run the test suite, simply use the build target
 <filename>test</filename> when you build :
 </p>
 <source><![CDATA[
 ant test
 ]]></source>

 <p>
 If all is well, you should see output like :
 </p>

 <source><![CDATA[
 test:
 Running JUnit template tests for Velocity ...
 Adding TemplateTestCase : arithmetic
 Adding TemplateTestCase : array
 Adding TemplateTestCase : block
    .
    .
    .
 Adding TemplateTestCase : math
 Adding TemplateTestCase : range
 Adding TemplateTestCase : get
 Adding TemplateTestCase : velocimacro2
 Adding TemplateTestCase : foreach-type
 Adding ContextSafetyTestCase.
 ......................................
 Time: 2.553

 OK (38 tests)
 ]]></source>

 <p>
 Note that the number of tests may vary from those shown above, but if
 you see 'OK' after the tests are run, all is well.  Now it's time to use
 Velocity.
 </p>
 </section>

 </body>
 </document>
	<?xml version="1.0"?>

	<document>

	<properties>
	<title>Velocity Installation</title>
	<author email="jvanzyl@locus.apache.org">Velocity Documentation Team</author>
	</properties>

	<body>

	<section name="Installation">

	<p>
	Velocity runs on a variety of platforms that have installed the Java 2
	Virtual Machine. The J2SDK is required for users who want to compile
	Velocity from its source code.
	</p>

	<p>
	Everything required to build Velocity comes with the distribution, which
	can be obtained from <a
	href="http://jakarta.apache.org/getinvolved/cvsindex.html">CVS</a> or
	from the <a
	href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">nightly
	builds</a>. However, you will need to install Ant, an excellent
	Java-based build tool. Ant is also a Jakarta project, and can be
	found <a href="http://jakarta.apache.org/ant/">here</a>.
	</p>

	<p>
	The directory tree of the distribution looks like :
	</p>

	<source><![CDATA[
	jakarta-velocity
	/build - contains build scripts
	/bin - where the built jars / classes will go
	/src - sourcecode for Velocity, Anakia, and Texen
	/docs - documentation in HTML form
	/docs/api - Javadocs for Velocity source
	/examples - example/demonstration code
	/convert - tools to help convert WebMacro templates
	/test - test programs and templates
	/xdocs - source for our documentation
	]]></source>

	</section>

	<section name="Building">

	<p>
	To make building Velocity easy and consistant, we require a Jakarta project
	called <a href="http://jakarta.apache.org/ant/">Ant</a> version 1.3 or
	higher to perform the build process. We assume that you have followed
	Ant's installation instructions and have it properly installed. It's not
	difficult, and I think that you will find it an excellent addition to
	your programmer's toolbox.
	</p>

	<p>
	In each case below, it is assumed that you were successful in getting
	the distribution from CVS or as a nightly build, and with the latter,
	were successful in unpacking. Also, it is assumed that you are starting
	in the 'jakarta-velocity' directory, the root of the distribution tree.
	All directory references will be relative to 'jakarta-velocity'.
	</p>

	<p>
	Change to the <filename>build</filename> directory (<code>cd
	build</code>). Then, to build the jar file, simply type:
	</p>

	<source><![CDATA[
	ant
	]]></source>

	<p>
	Executing this script will create a <filename>bin</filename> directory
	within the Velocity distribution directory. The <filename>bin</filename>
	directory will contain the compiled class files (inside a
	<filename>classes</filename> directory) as well as a
	<filename>velocity-XX.jar</filename> file, where XX is the current
	version number. Be sure to update your classpath to include Velocity's
	<filename>.jar</filename> file.
	</p>

	<p>
	Note that to build any of the specific build targets, as detailed in
	the <a href="developer-guide.html">developers guide</a>, simply add
	the target name to the command line. For example, to build the Javadoc
	API documentation :
	</p>

	<source><![CDATA[
	ant javadocs
	]]></source>

	<p>
	Velocity should build 'out of the box', independent of your classpath.
	If you get an error building Velocity, try a different nightly build (as
	sometimes we make a mistake and the CVS at the time of the nightly
	snapshot isn't complete) or refresh from CVS (you might have gotten a
	CVS snapshot while a developer was checking things in.)
	</p>

	<p>
	If the problems persist, do not hesitate to ask the Velocity community
	via our mail lists. They can be found <a
	href="http://jakarta.apache.org/site/mail.html">here</a>. Please read
	and understand the the guidelines for participating in any Jakarta mail
	list.
	</p>

	</section>

	<section name="Testing Your Installation">

	<p>
	The Velocity developers use an automated test facility, and it is
	included in the distribution. You can use it to make sure that all is
	well with your build of Velocity.
	</p>

	<p>
	To run the test suite, simply use the build target
	<filename>test</filename> when you build :
	</p>
	<source><![CDATA[
	ant test
	]]></source>

	<p>
	If all is well, you should see output like :
	</p>

	<source><![CDATA[
	test:
	Running JUnit template tests for Velocity ...
	Adding TemplateTestCase : arithmetic
	Adding TemplateTestCase : array
	Adding TemplateTestCase : block
	.
	.
	.
	Adding TemplateTestCase : math
	Adding TemplateTestCase : range
	Adding TemplateTestCase : get
	Adding TemplateTestCase : velocimacro2
	Adding TemplateTestCase : foreach-type
	Adding ContextSafetyTestCase.
	......................................
	Time: 2.553

	OK (38 tests)
	]]></source>

	<p>
	Note that the number of tests may vary from those shown above, but if
	you see 'OK' after the tests are run, all is well. Now it's time to use
	Velocity.
	</p>
	</section>

	</body>
	</document>