utils/jalopy/docs/build.html

   1
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
   4  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  18 -->
  19     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  20   <html><head>
  21       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  22    <title>Chapter&nbsp;2.&nbsp;Building</title><link rel="stylesheet" href="site.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="manual.html" title="Jalopy User Manual"><link rel="up" href="part-core.html" title="Part&nbsp;I.&nbsp;Jalopy core"><link rel="previous" href="installation.html" title="Chapter&nbsp;1.&nbsp;Installation"><link rel="next" href="usage.html" title="Chapter&nbsp;3.&nbsp;Usage"><link rel="preface" href="dedication.html" title="Dedication"><link rel="preface" href="acknowledge.html" title="Acknowledgements"><link rel="preface" href="introduction.html" title="Introduction"><link rel="part" href="part-core.html" title="Part&nbsp;I.&nbsp;Jalopy core"><link rel="chapter" href="installation.html" title="Chapter&nbsp;1.&nbsp;Installation"><link rel="chapter" href="build.html" title="Chapter&nbsp;2.&nbsp;Building"><link rel="chapter" href="usage.html" title="Chapter&nbsp;3.&nbsp;Usage"><link rel="chapter" href="settings.html" title="Chapter&nbsp;4.&nbsp;Settings"><link rel="part" href="part-plugins.html" title="Part&nbsp;II.&nbsp;Plug-ins"><link rel="chapter" href="plugin-ant.html" title="Chapter&nbsp;5.&nbsp;Ant Plug-in task"><link rel="chapter" href="plugin-console.html" title="Chapter&nbsp;6.&nbsp;Console Application"><link rel="chapter" href="plugin-eclipse.html" title="Chapter&nbsp;7.&nbsp;Eclipse Plug-in"><link rel="chapter" href="plugin-jbuilder.html" title="Chapter&nbsp;8.&nbsp;JBuilder OpenTool"><link rel="chapter" href="plugin-jdev.html" title="Chapter&nbsp;9.&nbsp;JDeveloper Extension"><link rel="chapter" href="plugin-jedit.html" title="Chapter&nbsp;10.&nbsp;jEdit Plug-in"><link rel="chapter" href="plugin-netbeans.html" title="Chapter&nbsp;11.&nbsp;NetBeans/Sun ONE Studio module"><link rel="appendix" href="dependencies.html" title="Appendix&nbsp;A.&nbsp;Library Dependencies"><link rel="appendix" href="license-bsd.html" title="Appendix&nbsp;B.&nbsp;The Jalopy BSD License"><link rel="appendix" href="license-antlr.html" title="Appendix&nbsp;C.&nbsp;ANTLR SOFTWARE RIGHTS"><link rel="appendix" href="license-apache.html" title="Appendix&nbsp;D.&nbsp;The Apache Software License, Version 1.1"><link rel="appendix" href="license-gnu.html" title="Appendix&nbsp;E.&nbsp;GNU GENERAL PUBLIC LICENSE Version 2, June 1991"><link rel="appendix" href="license-gnu-doc.html" title="Appendix&nbsp;F.&nbsp;GNU Free Documentation License Version 1.1, March 2000"><link rel="appendix" href="license-common-public.html" title="Appendix&nbsp;G.&nbsp;Common Public License Version 1.0"><link rel="appendix" href="license-sun-public.html" title="Appendix&nbsp;H.&nbsp;SUN PUBLIC LICENSE Version 1.0"><link rel="index" href="ix01.html" title="Index"><link rel="subsection" href="build.html#build-prerequisites" title="2.1.&nbsp;Prerequisites"><link rel="subsection" href="build.html#build-build" title="2.2.&nbsp;Building">
  23       <meta name="description" content="Jalopy Java Source Code Formatter Beautifier Pretty Printer">
  24       <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" l gen true for "http://jalopy.sf.net" r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://jalopy.sf.net" r (n 0 s 0 v 0 l 0))'>
  25     </head><body id="toppage" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="700" border="0" cellpadding="0" cellspacing="0" align="left"><tbody><tr><td><table cellpadding="0" cellspacing="0" width="100%" style="border:1px solid #336699"><tbody><tr><td height="16"></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr style="border:none"><td style="border:none"><table border="0" cellspacing="0" cellpadding="0"><tbody><tr><td class="logo">JALOPY</td><td class="sublogo" valign="bottom">Java Source Code Formatter Beautifier Pretty Printer</td></tr></tbody></table></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr><td height="10"></td></tr><tr><td bgcolor="#ff8000" height="4"></td></tr><tr><td height="20" bgcolor="#336699" style="color:#ffffff;padding-left:10px"><a href="./index.html" class="navlink">Overview</a> &#149;
  26                     <a href="./download.html" class="navlink">Download</a> &#149;
  27                     <a href="./docs.html" class="navlink">Documentation</a> &#149;
  28                     <a href="./plugins.html" class="navlink">Plug-ins</a> &#149;
  29                     <a href="./links.html" class="navlink">Links</a> &#149;
  30                     <a href="./contact.html" class="navlink">Contact</a></td></tr><tr><td height="1" bgcolor="#ffffff"></td></tr></tbody></table></td></tr><tr valign="top"><td valign="top" bgcolor="#ffffff"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tbody><tr><td height="20" bgcolor="#faebd7" style="padding-left:15px"><a href="./features.html" class="navlink2">Features</a> |
  31                     <a href="./history.html" class="navlink2">History</a> |
  32                     <a href="./manual.html" class="navlink2">Manual</a> |
  33                     <a href="./faq.html" class="navlink2">FAQ</a> |
  34                     <a href="./api/index.html" class="navlink2">Javadoc</a></td></tr><tr><td height="20" bgcolor="#ffffff"></td></tr><tr><td bgcolor="#eeeecc" height="17" align="right" style="font-size:10px;padding-right:3px">
  35                     This page generated: <strong>June 8 2004</strong></td></tr></tbody></table><table border="0" width="100%" cellspacing="0" cellpadding="5"><tr><td><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;2.&nbsp;Building</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="installation.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;I.&nbsp;Jalopy core</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="usage.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="build"></a>Chapter&nbsp;2.&nbsp;Building</h2></div></div><div></div></div><a class="indexterm" name="d0e706"></a><p>
  36 Explains the steps involved in building Jalopy from the sources.
  37 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="build-prerequisites"></a>2.1.&nbsp;Prerequisites</h4></div></div><div></div></div><a class="indexterm" name="d0e716"></a><p>
  38 The following software must be installed separately, in order to build from the
  39 sources:
  40 </p><div class="table"><a name="tab-build-prerequisites"></a><p class="title"><b>Table&nbsp;2.1.&nbsp;Software needed to build from the sources</b></p><table summary="Software needed to build from the sources" border="0" style="border-collapse: collapse;"><colgroup><col><col></colgroup><tbody><tr><td style="" valign="top">Jakarta Ant</td><td style="">
  41 Jalopy comes with a simple, Ant-based build system. So you first need to obtain and
  42 install Ant as outlined in the
  43 <a href="http://jakarta.apache.org/ant/manual/install.html" target="_top">Ant manual</a>.
  44 The build system is only tested against the Ant 1.5.4 release, but later
  45 releases of Ant may also work.
  46 </td></tr><tr><td style="" valign="top">Oasis DocBook XML DTD</td><td style="">
  47 All documentation is written using DocBook Version 4.2 markup. You can get the DTD
  48 from the
  49 <a href="http://www.oasis-open.org/committees/docbook/xml/4.2/index.shtml" target="_top">OASIS web site</a>.
  50 Unpack the sources into a folder of your choice and remember this path as it will be
  51 needed for configuration later on.
  52 </td></tr><tr><td style="" valign="top">An XSLT processor</td><td style="">
  53 The DocBook markup needs to be transformed in order to make some user-friendly appearance.
  54 This is done via XSLT and Michael Kay's Saxon is the processor I found working with the
  55 Stylesheet package I use. You should download the current stable production
  56 release from SourceForge (<a href="http://saxon.sf.net" target="_top">http://saxon.sf.net</a>)
  57 and extract the file <tt class="filename">saxon.jar</tt> into the <tt class="filename">/lib</tt>
  58 folder of your Ant installation directory.  I also had to setup saxon to use
  59 Xerces as the XML parser by editing the
  60 META-INF/services/javax.xml.parsers.SAXParserFactory file inside of
  61 saxon.jar and replacing the alfred parser with org.apache.xerces.jaxp.SAXParserFactoryImpl
  62 </td></tr><tr><td style="" valign="top">DocBook XSL Stylesheets</td><td style="">
  63 To perform the markup translation you need Norman Walsh's XSL Stylesheet package.
  64 The version that works for me is 1.62.4. You can get it from SourceForge
  65 (<a href="http://docbook.sf.net" target="_top">http://docbook.sf.net</a>).
  66 Copy the file <tt class="filename">extensions/saxon651.jar</tt> that
  67 comes with the distribution into the <tt class="filename">/lib</tt> folder of your
  68 Ant installation directory as this file is needed for sophisticated table generation.
  69 </td></tr><tr><td style="" valign="top">A CVS client (optional)</td><td style="">
  70 If you plan to get the sources directly from CVS you need a CVS client. If your system
  71 does not come with one pre-installed (most Linux machines at least have the command-line
  72 client installed by default), you will certainly want to visit any of several good sites
  73 such as <a href="http://www.cvshome.org/" target="_top">http://www.cvshome.org/</a>
  74 which <a href="http://www.cvshome.org/dev/codes.html" target="_top">lists</a> available CVS clients
  75 for different platforms, their strengths and weaknesses. For what it's worth, I prefer
  76 <a href="http://www.smartcvs.com" target="_top">SmartCVS</a>.
  77 </td></tr></tbody></table></div><p></p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="build-build"></a>2.2.&nbsp;Building</h4></div></div><div></div></div><p>
  78 The basic steps to build Jalopy from the sources are:
  79 </p><div class="orderedlist"><ol type="1"><li><p>
  80 Get and install the needed software as outlined in <a href="build.html#build-prerequisites" title="2.1.&nbsp;Prerequisites">Section&nbsp;2.1, &#8220;Prerequisites&#8221;</a>.
  81 Make sure Ant is set up correctly.
  82 </p></li><li><p>
  83 Get the sources. Either download and unpack the
  84 <a href="./download.html#source" target="_top">Jalopy source distribution</a> which
  85 contains the complete Jalopy sources. Or grab the needed modules directly from the
  86 <a href="http://sourceforge.net/cvs/?group_id=45216" target="_top">CVS</a> tree.</p></li><li><p>
  87 Change to the directory where your Jalopy sources reside. You should find a
  88 directory layout somewhat similar to the following (each directory represents a
  89 module; the minimal needed modules are printed in <span class="emphasis"><em>bold</em></span>):
  90 </p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="screen">
  91  ..
  92    ant/                  The Ant Plug-in
  93    <span class="bold"><b>build/</b></span>                The Jalopy build system
  94    console/
  95    <span class="bold"><b>docu/</b></span>                 All documentation sources
  96    eclipse/              The Eclipse Plug-in
  97    jbuilder/             The JBuilder Plug-in
  98    jdeveloper/           The JDeveloper Plug-in
  99    jedit/                The jEdit Plug-in
 100    <span class="bold"><b>main/</b></span>                 The core Jalopy sources
 101    netbeans/             The NetBeans/Sun ONE Studio Plug-in
 102 </pre></td></tr></table><p>
 103 Change directory into <tt class="filename">/build</tt> where the master build script
 104 lurks.
 105 </p></li><li><p>
 106 Adjust the global build properties to match your installation. The build
 107 system uses quite a few properties to control the build process and
 108 specify additional needed resources. You can find and adjust these properties in the file
 109 <tt class="filename">build.properties</tt>.
 110 </p><p>
 111 Luckily you only have to change some common properties to get things running:
 112 </p><div class="variablelist"><p class="title"><b>Common build properties</b></p><dl><dt><span class="term">DIR.DOCBOOK.XSL</span></dt><dd><p>
 113 Specifies the installation directory of the DocBook XSL Stylesheets package.
 114 Note that you have to specify a protocol, e.g. <tt class="filename">file:///G:/XML/docbook-xsl-1.62.4</tt>.
 115 </p></dd><dt><span class="term">DIR.DOCBOOK.DTD</span></dt><dd><p>
 116 Specifies the path where to find the DocBook XSL DTD.
 117 You have to adjust the default path to match your installation.
 118 </p></dd><dt><span class="term">LIB.PATH.<i class="replaceable"><tt>&lt;modulename&gt;</tt></i></span></dt><dd><p>
 119 Specifies additional library path(s) needed to build a certain module.
 120 You have to adjust the default path(s) to match your installation.
 121 </p></dd><dt><span class="term">PACKAGE.PATH.<i class="replaceable"><tt>&lt;libraryname&gt;</tt></i></span></dt><dd><p>
 122 Specifies the location to a directory containing the package-list file for a
 123 given library. This is optional and only needed by Javadoc to resolve links to
 124 documentation for externally referenced classes. Change the default path(s)
 125 to match your installation.
 126 </p></dd></dl></div></li><li><p>
 127 Once everything is set up, you can start a build using <span><b class="command">ant</b></span> <i class="parameter"><tt>target</tt></i>
 128 where <i class="parameter"><tt>target</tt></i> describes one of the main build targets (those with a
 129 description, use <span><b class="command">ant</b></span> <i class="parameter"><tt>-projecthelp</tt></i> to display
 130 the available targets). Just typing <span><b class="command">ant</b></span> will build the Jalopy
 131 core runtime distribution.
 132 </p></li><li><p>
 133 When a build is done, you can find the created distribution(s) in the
 134 <tt class="filename">tmp~/dist</tt> folder. The build system creates and stores all
 135 intermediate files and subdirectories under the <tt class="filename">tmp~</tt>
 136 directory.
 137 </p></li><li><p>
 138 If you make changes to the source code, just run Ant again; this will perform a
 139 faster <i class="firstterm">incremental</i> rebuild of the target.
 140 </p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installation.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="part-core.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="usage.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;1.&nbsp;Installation&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;3.&nbsp;Usage</td></tr></table></div></td></tr></table></td></tr><tr><td bgcolor="#eeeecc" height="17" style="font-size:9px;padding-left:5px"><a href="#toppage">to top</a></td></tr><tr><td height="30"><br></td></tr><tr><td height="3"></td></tr><tr><td bgcolor="#336699" height="1"></td></tr><tr><td height="1"></td></tr><tr><td bgcolor="#336699" height="16"></td></tr><tr><td bgcolor="#ff9966" height="4"></td></tr><tr><td class="footer" align="center" height="15" valign="middle">
 141             Copyright &copy; 2001-2004, <a class="footer" href="./contact.html">Marco Hunsicker</a>. All rights reserved. Hosted by <a href="http://sourceforge.net">SourceForge.net</a></td></tr></tbody></table><img src="http://sourceforge.net/sflogo.php?group_id=45216&amp;type=1" width="1" height="1" border="0" hspace="0" vspace="0" alt=""></body></html>