Changing filename conventions - no more file names with spaces.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@907115 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 344 insertions, 0 deletions

diff --git a/qpid/doc/book/src/Qpid-Java-Build-How-To.xml b/qpid/doc/book/src/Qpid-Java-Build-How-To.xml
new file mode 100644
index 0000000000..e27b5b951b
--- /dev/null
+++ b/qpid/doc/book/src/Qpid-Java-Build-How-To.xml
@@ -0,0 +1,344 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+      Apache Qpid : Qpid Java Build How To
+    </title>
+
+    <section role="h1" id="QpidJavaBuildHowTo-BuildInstructionsGeneral"><title>
+            Build
+            Instructions - General
+          </title>
+	 
+    <section role="h2" id="QpidJavaBuildHowTo-Checkoutthesource"><title>
+            Check out the
+            source
+          </title>
+	 <para>
+            Firstly, check the source for Qpid out of our subversion
+            repository:
+          </para><para>
+            <xref linkend="qpid_trunk"/>
+          </para>
+<!--h2--></section>
+    <section role="h2" id="QpidJavaBuildHowTo-Prerequisites"><title>
+            Prerequisites
+          </title>
+	 <para>
+            For the broker code you need JDK 1.5.0_15 or later. You should
+            set JAVA_HOME and include the bin directory in your PATH.
+          </para><para>
+            Check it's ok by executing java -v !
+          </para><para>
+            If you are wanting to run the python tests against the broker you
+            will of course need a version of python.
+          </para>
+<!--h2--></section>
+<!--h1--></section>
+
+    <section role="h1" id="QpidJavaBuildHowTo-BuildInstructionsTrunk"><title>
+            Build
+            Instructions - Trunk
+          </title>
+	 <para>
+            Our build system has reverted to ant as of May 2008.
+          </para><para>
+            The ant target 'help' will tell you what you need to know about
+            the build system.
+          </para>
+    <section role="h2" id="QpidJavaBuildHowTo-AntBuildScripts"><title>
+            Ant Build
+            Scripts
+          </title>
+	 <para>
+            Currently the Qpid java project builds using ant.
+          </para><para>
+            The ant build system is set up in a modular way, with a top level
+            build script and template for module builds and then a module
+            level build script which inherits from the template.
+          </para><para>
+            So, at the top level there are:
+          </para><table><title/><tgroup cols="2">
+            <tbody>
+              <row>
+                <entry>
+                  File
+                </entry>
+                <entry>
+                  Description
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  build.xml
+                </entry>
+                <entry>
+                  Top level build file for the project which defines all the
+                  build targets
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  common.xml
+                </entry>
+                <entry>
+                  Common properties used throughout the build system
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  module.xml
+                </entry>
+                <entry>
+                  Template used by all modules which sets up properties for
+                  module builds
+                </entry>
+              </row>
+            </tbody>
+          </tgroup></table><para>
+            Then, in each module subdirectory there is:
+          </para><table><title/><tgroup cols="2">
+            <tbody>
+              <row>
+                <entry>
+                  File
+                </entry>
+                <entry>
+                  Description
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  build.xml
+                </entry>
+                <entry>
+                  Defines all the module values for template properties
+                </entry>
+              </row>
+            </tbody>
+          </tgroup></table>
+<!--h2--></section>
+    <section role="h2" id="QpidJavaBuildHowTo-Buildtargets"><title>
+            Build targets
+          </title>
+	 <para>
+            The main build targets you are probably interested in are:
+          </para><table><title/><tgroup cols="2">
+            <tbody>
+              <row>
+                <entry>
+                  Target
+                </entry>
+                <entry>
+                  Description
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  build
+                </entry>
+                <entry>
+                  Builds all source code for Qpid
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  test
+                </entry>
+                <entry>
+                  Runs the testsuite for Qpid
+                </entry>
+              </row>
+            </tbody>
+          </tgroup></table><para>
+            So, if you just want to compile everything you should run the
+            build target in the top level build.xml file.
+          </para><para>
+            If you want to build an installable version of Qpid, run the
+            archive task from the top level build.xml file.
+          </para><para>
+            If you want to compile an individual module, simply run the build
+            target from the appropriate module e.g. to compile the broker
+            source
+          </para>
+<!--h2--></section>
+    <section role="h2" id="QpidJavaBuildHowTo-ConfiguringEclipse"><title>
+            Configuring
+            Eclipse
+          </title>
+	 <para>
+            1. Run the ant build from the root directory of Java trunk.
+            2. New project -&gt; create from existing file system for broker,
+            common, client, junit-toolkit, perftests, systests and each
+            directory under management
+            4. Add the contents of lib/ to the build path
+            5. Setup Generated Code
+            6. Setup Dependencies
+          </para>
+    <section role="h3" id="QpidJavaBuildHowTo-GeneratedCode"><title>
+            Generated Code
+          </title>
+	 <para>
+            The Broker and Common packages both depend on generated code.
+            After running 'ant' the build/scratch directory will contain this
+            generated code.
+            For the broker module add build/scratch/broker/src
+            For the common module add build/scratch/common/src
+          </para>
+<!--h3--></section>
+    <section role="h3" id="QpidJavaBuildHowTo-Dependencies"><title>
+            Dependencies
+          </title>
+	 <para>
+            These dependencies are correct at the time of writting however,
+            if things are not working you can check the dependencies by
+            looking in the modules build.xml file:
+          </para>
+            <programlisting>
+for i in `find . -name build.xml` ; do echo "$i:"; grep module.depends $i ; done
+</programlisting>
+          <para>
+            The <emphasis>module.depend</emphasis> value will detail which other modules
+            are dependencies.
+          </para><para>
+            broker
+          </para><itemizedlist>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>management/common
+            </para></listitem>
+          </itemizedlist><para>
+            client
+          </para><itemizedlist>
+            <listitem><para>Common
+            </para></listitem>
+          </itemizedlist><para>
+            systest
+          </para><itemizedlist>
+            <listitem><para>client
+            </para></listitem>
+            <listitem><para>management/common
+            </para></listitem>
+            <listitem><para>broker
+            </para></listitem>
+            <listitem><para>broker/test
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>junit-toolkit
+            </para></listitem>
+            <listitem><para>management/tools/qpid-cli
+            </para></listitem>
+          </itemizedlist><para>
+            perftests
+          </para><itemizedlist>
+            <listitem><para>systests
+            </para></listitem>
+            <listitem><para>client
+            </para></listitem>
+            <listitem><para>broker
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>junit-toolkit
+            </para></listitem>
+          </itemizedlist><para>
+            management/eclipse-plugin
+          </para><itemizedlist>
+            <listitem><para>broker
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>management/common
+            </para></listitem>
+          </itemizedlist><para>
+            management/console
+          </para><itemizedlist>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>client
+            </para></listitem>
+          </itemizedlist><para>
+            management/agent
+          </para><itemizedlist>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>client
+            </para></listitem>
+          </itemizedlist><para>
+            management/tools/qpid-cli
+          </para><itemizedlist>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>management/common
+            </para></listitem>
+          </itemizedlist><para>
+            management/client
+          </para><itemizedlist>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>client
+            </para></listitem>
+          </itemizedlist><para>
+            integrationtests
+          </para><itemizedlist>
+            <listitem><para>systests
+            </para></listitem>
+            <listitem><para>client
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>junit-toolkit
+            </para></listitem>
+          </itemizedlist><para>
+            testkit
+          </para><itemizedlist>
+            <listitem><para>client
+            </para></listitem>
+            <listitem><para>broker
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+          </itemizedlist><para>
+            tools
+          </para><itemizedlist>
+            <listitem><para>client
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+          </itemizedlist><para>
+            client/examples
+          </para><itemizedlist>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>client
+            </para></listitem>
+          </itemizedlist><para>
+            broker-plugins
+          </para><itemizedlist>
+            <listitem><para>client
+            </para></listitem>
+            <listitem><para>management/common
+            </para></listitem>
+            <listitem><para>broker
+            </para></listitem>
+            <listitem><para>common
+            </para></listitem>
+            <listitem><para>junit-toolkit
+            </para></listitem>
+          </itemizedlist>
+<!--h3--></section>
+<!--h2--></section>
+
+    <section role="h2" id="QpidJavaBuildHowTo-Whatnext-3F"><title>
+            What next ?
+          </title>
+	 <para>
+            If you want to run your built Qpid package, see our <xref linkend="qpid_Getting-20Started-20Guide"/> for details of
+            how to do that.
+          </para><para>
+            If you want to run our tests, you can use the ant test or
+            testreport (produces a useful report) targets.
+          </para>
+            
+<!--h2--></section>
+<!--h1--></section>	   
+</chapter>