User: user57
Date: 01/11/16 20:19:12
Modified: src/docs/developers buildsystem.jsp cvs.jsp navigation.jsp
slogan.jsp
Added: src/docs/developers buildsystem-faq.jsp quickstart.jsp
Log:
o cleaned up main.css, so it is more readable
o touched up some problems with buildsystem.jsp
o changed CVS module formatting, removed trailing ant fluff and
re-formated the top of cvs.jsp
o added a quick start guide
o added a buildsystem faq (still needs more q to a)
o added the quick start, build system and SF project info page to the
developer navigation.
* eventually want to replace these nav links to a single Guides page,
which can list over all of them... but for now these are the big ones
developers will want to see.
o minor non-visual formatting changes to slogan and picateam
Revision Changes Path
1.2 +191 -101 newsite/src/docs/developers/buildsystem.jsp
Index: buildsystem.jsp
===================================================================
RCS file: /cvsroot/jboss/newsite/src/docs/developers/buildsystem.jsp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- buildsystem.jsp 2001/11/16 02:14:00 1.1
+++ buildsystem.jsp 2001/11/17 04:19:12 1.2
@@ -1,23 +1,44 @@
<jsp:include page="head.jsp" flush="true"/>
+<!-- $Id: buildsystem.jsp,v 1.2 2001/11/17 04:19:12 user57 Exp $ -->
<jsp:include page="slogan.jsp" flush="true">
<jsp:param name="SLOGAN" value="BUILD SYSTEM GUIDE"/>
</jsp:include>
<!-- ==================================================================== -->
+<!-- Preface -->
+
+<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
+
+<p class="text">
+ This document is meant as a general guide to the JBoss build system. If
+ you are looking to get working with the sources right away you are better
+ off looking at the <a href="quickstart.jsp">Quick Start Guide</a>.
+
+<p class="text">
+ For a list of frequently asked questions (and their answers) check out
+ the <a href="buildsystem-faq.jsp">Build System FAQ</a>.
+
+<!-- end picateam block --></td></tr></table>
+
+<!-- ==================================================================== -->
+
<p class="head"><a name="Contents">Contents</a>
- <ul>
- <li><a class="link" href="#Overview">Overview</a>
- <li><a class="link" href="#Project_Overview">Project Overview</a>
- <li><a class="link" href="#Module_Overview">Module Overview</a>
- <li><a class="link" href="#The_build_Module">The <em>build</em> Module</a>
+
+<p class="text">
+ <ul class="text">
+ <li><a href="#Introduction">Introduction</a>
+ <li><a href="#Project_Overview">Project Overview</a>
+ <li><a href="#Module_Overview">Module Overview</a>
+ <li><a href="#The_build_Module">The <em>build</em> Module</a>
</ul>
<!-- ==================================================================== -->
-<p class="head"><a name="Overview">Overview<a/>
+<p class="head">
+ <a name="Introduction">Introduction<a/>
-<p class="text">
+<p class="text"><a name="About_Ant"></a>
The JBoss build system is based on
<a href="http://jakarta.apache.org/ant";>Ant</a> from our friends at the
<a href="http://jakarta.apache.org";>Apache Jakarta</a> project.
@@ -44,36 +65,40 @@
really need to execute a shell command, Ant has an exec rule that allows
different commands to be executed based on the OS that it is executing on.
+<p class="text">
+ <a href="#Contents">[Contents]</a>
+
<!-- ==================================================================== -->
-<p class="head"><a name="Project_Overview">Project Overview<a/>
+<p class="head">
+ <a name="Project_Overview">Project Overview<a/>
<p class="text">
Each project contains a set of modules. Each project has at least a
- <em>build</em>, <em>tools</em>, <em>thirdparty</em>, one or more <em>local
- modules</em> and zero or more <em>external modules</em>.
+ <tt>build</tt>, <tt>tools</tt>, <tt>thirdparty</tt>, one or more
+ <em>local</em> modules and zero or more <em>external</em> modules.
<p class="text">
- <em>tools</em> is a special module which contains the scripts and libraries
+ <tt>tools</tt> is a special module which contains the scripts and libraries
required by the build system to run correctly. This inclues ant,
buildmagic and other required ant libs. Its layout looks like this:
- <pre>
- bin/
- lib/
- </pre>
+ <blockquote>
+ <tt>bin/</tt><br>
+ <tt>lib/</tt><br>
+ </blockquote>
<p class="text">
This module is included in each project by the CVS module definition file
(<tt>CVSROOT/modules</tt>). In most cases the tools module for each
- project is simply included from the <tt>/tools</tt> CVS module.
+ project is simply included from the <tt>tools</tt> CVS module.
<p class="text">
- Even though there is a <tt>tools/bin</tt> directory, files in there are
+ Even though there is a <tt>tools/bin/</tt> directory, files in there are
not meant to be executed directly by the user.
<p class="text">
- <em>thirdparty<em> is another special module, which is included from the
- <em>/thirdparty</em> CVS module.
+ <tt>thirdparty</tt> is another special module, which is included from the
+ <tt>thirdparty</tt> CVS module.
<p class="text">
Some projects have selected a sub-set of directories to include from
@@ -83,116 +108,135 @@
<p class="text">
The structure is setup to split up each thirdparty library, program or
package by <tt><em>vendor-name</em>/<em>package-name</em>/*</tt>.
-
-<p class="text">
Library files are forced into a <tt>lib/</tt> directory if the imported
version did not supply one. This helps keep things consistent.
<p class="text">
+ For example, the JAXP v1.1 package from SUN would look like:
+ <blockquote>
+ <tt>sun/jaxp/</tt><br>
+ <tt>sun/jaxp/LICENSE</tt><br>
+ <tt>sun/jaxp/lib/</tt><br>
+ <tt>sun/jaxp/lib/jaxp.jar</tt><br>
+ <tt>sun/jaxp/lib/crimson.jar</tt><br>
+ <tt>sun/jaxp/lib/xalan.jar</tt><br>
+ </blockquote>
+
+<p class="text">
With the current CVS organization local and external modules are equivilant.
This is likly to change when the CVS repository is reorganized. The logical
difference is that external modules exist as the specific modules
of another project which are included as a dependency of a local module.
<p class="text">
- <a class="link" href="#Contents">Contents</a>
+ <a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head"><a name="Module_Overview">Module Overview</a>
<p class="text">
- The <em>build</em> and other project specific or external modules have the
+ The <tt>build</tt> and other project specific or external modules have the
same layout:
- <pre>
- build.sh
- build.bat
- build.xml
- </pre>
+ <blockquote>
+ <tt>build.sh</tt><br>
+ <tt>build.bat</tt><br>
+ <tt>build.xml</tt><br>
+ </blockquote>
+
+<p class="text">
+ Other files required by the build system are stored in the <tt>etc/</tt>
+ directory. Each can have an optional local properties example file:
+ <blockquote>
+ <tt>etc/local.properties-example</tt><br>
+ </blockquote>
<p class="text">
- Each can have an optional:
- <pre>
- module/etc/local.properties-example
- </pre>
+ Currently only the <tt>build</tt> modules have this, so that user local
+ configuration can be placed in one central location.
-<p class="test">
+<p class="text">
Local and external modules are generally modules containing source files
to compile, or simply source modules. These modules have the following
extra layout:
- <pre>
- src/
- src/main
- </pre>
-
-<p class="text">
- Currently only the build modules have this, so that local configuration can
- be placed in one central location.
+ <blockquote>
+ <tt>src/</tt><br>
+ <tt>src/main/</tt><br>
+ </blockquote>
+
+ <!--
+ | need to provide a detailed list of the src/* directories
+ | and the types of files which should be contained under them
+ -->
+
+<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
<tt>build.xml</tt> contains all of the build control elements. It will
attempt to install a <tt>etc/local.properties-example</tt> file to
- <tt>local.properties</tt> if one exists. It will then include
- <tt>local.properties</tt>. This file allows users to override or configure
- the build system to suite there needs with out having to modify the
- main build file and accidentially check in those changes which would
- affect all users.
+ <tt>local.properties</tt> if one exists. It will then include that file.
+ This allows users to override or configure the build system to suite
+ there needs with out having to modify the main build file and
+ accidentially check in those changes which would affect all users.
+<!-- end picateam block --></td></tr></table>
+
<p class="text">
Each module has the same basic <tt>build.xml</tt> format (even
- <em>build</em> modules). Each has been seperated into major sections:
+ <tt>build</tt> modules). Each has been seperated into major sections:
<ul class="text">
- <li>Initialization
- <li>Configuration
- <li>Compile
- <li>Archives
- <li>Documents
- <li>Install
- <li>Release
- <li>Tests
- <li>Cleaning
- <li>Workspace
- <li>Help
- <li>Misc
- <li><em>Other project or module specific sections</em>
+ <li><tt>Initialization</tt>
+ <li><tt>Configuration</tt>
+ <li><tt>Compile</tt>
+ <li><tt>Archives</tt>
+ <li><tt>Documents</tt>
+ <li><tt>Install</tt>
+ <li><tt>Release</tt>
+ <li><tt>Tests</tt>
+ <li><tt>Cleaning</tt>
+ <li><tt>Workspace</tt>
+ <li><tt>Help</tt>
+ <li><tt>Misc</tt>
+ <li><em>Other project or module specific sections</em>
</ul>
<p class="text">
- The sections which you are more likly to change are Configuration, Compile,
- Archives & Install. Initialization and some parts of Configuration should
- NOT be changed, or should be changed int ALL files to keep things
- consistent.
+ The sections which you are more likly to change are <tt>Configuration</tt>,
+ <tt>Compile</tt>, <tt>Archives</tt> & <tt>Install</tt>.
+ <tt>Initialization</tt> and some parts of <tt>Configuration</tt> should
+ <b>NOT</b> be changed, or should be changed in <b>ALL</b> files to keep
+ things consistent.
<p class="text">
Configuration is split up into targets:
<ul class="text">
- <li>_configure
- <li>_configure-tools
- <li>_configure-libraries
- <li>_configure-modules
- <li>_configure-tasks
+ <li><tt>_configure</tt>
+ <li><tt>_configure-tools</tt>
+ <li><tt>_configure-libraries</tt>
+ <li><tt>_configure-modules</tt>
+ <li><tt>_configure-tasks</tt>
</ul>
<p class="text">
Each target should setup the tasks properties and paths which are required
- for the particular tool, library, module or task. <em>_configure</em>
+ for the particular tool, library, module or task. <tt>_configure</tt>
contains some module specific names and then calls the others.
<p class="text">
Each module must have the following targets:
<ul class="text">
- <li>all
- <li>most
- <li>main
- <li>release
- <li>tests
- <li>clean
- <li>clobber
+ <li><tt>all</tt>
+ <li><tt>most</tt>
+ <li><tt>main</tt>
+ <li><tt>release</tt>
+ <li><tt>tests</tt>
+ <li><tt>clean</tt>
+ <li><tt>clobber</tt>
</ul>
<p class="text">
These targets are assumed to exist and are called by the
- <em>build</em> module.
+ <tt>build</tt> module.
<p class="text">
Each module will attempt to include a <tt>../build/local.properties</tt>
@@ -202,34 +246,36 @@
<p class="text">
The module where a build is started from (using <tt>build.sh</tt> or
<tt>build.bat</tt>) will create a <tt>build.log</tt> file.
- For <em>build</em> modules that call other modules, only once
+ For <tt>build</tt> modules that call other modules, only once
<tt>build/build.log</tt> will be created.
<p class="text">
- Modules <em>install</em> files into a <tt><em>module</em>/output/*</tt>
- directory with the 'install' target.
+ Modules <tt>install</tt> files into a <tt><em>module-dir</em>/output/*</tt>
+ directory with the <tt>install</tt> target.
<p class="text">
- Each module has a also has a <em>release</em> target which can generate a
- release archive for each. For the <em>build</em> module, this will
+ Each module has a also has a <tt>release</tt> target which can generate a
+ release archive for each. For the <tt>build</tt> module, this will
contain a release for the project. In most cases individiual module
releases are not used.
<p class="text">
- Each module also has <em>release-zip</em>, <em>release-tar</em>,
- <em>release-tgz</em> and <em>release-all</em> targets, which build the
+ Each module also has <tt>release-zip</tt>, <tt>release-tar</tt>,
+ <tt>release-tgz</tt> and <tt>release-all</tt> targets, which build the
appropriate archive type based on the name.
<p class="text">
- <a class="link" href="#Contents">Contents</a>
+ <a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
- <a name="The_build_Module">The <em>build</em> Module</p></a>
+ <a name="The_build_Module">The <tt>build</tt> Module</p></a>
+
+<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
- The <em>build</em> module is responsible for executing the build systems
+ The <tt>build</tt> module is responsible for executing the build systems
of other modules, then <em>pulling</em> the output from those modules to
create a release distribution for the project.
@@ -238,41 +284,85 @@
which will iterate over the module list and execute
<tt><em>target-name</em></tt>.
+<!-- end picateam block --></td></tr></table>
+
<p class="text">
The module list is controlled by the configuration done in the
- <em>_configure-modules</em> section in the <tt>build/build.xml</tt> file.
+ <tt>_configure-modules</tt> section in the <tt>build/build.xml</tt> file.
This section defines modules, and groups of modules. The module list can
be specified on the command line by setting the
<tt>-Dmodules=<em>list</em></tt> property or you can specify a module group
list by setting <tt>-Dgroups=<em>list</em></tt>.
<p class="text">
- List names are seperated by ',' (comma). You will need to quote lists
- which contain spaces, or simply omit the spaces. The build system does
- not make any attempt to correctly identify inter-module dependencies,
+ List names are seperated by '<tt>,</tt>' (comma). You will need to quote
+ lists which contain spaces, or simply omit the spaces. The build system
+ does not make any attempt to correctly identify inter-module dependencies,
so you will have to list the modules which are required in the correct
order.
<p class="text">
- The build module also has a 'Module Pass-through Hooks' section, which
- contains targets for each module named
+ For example, assume you have a project which defines 4 modules:
+ <blockquote>
+ <tt>module_A</tt><br>
+ <tt>module_B</tt><br>
+ <tt>module_C</tt><br>
+ <tt>module_D</tt><br>
+ </blockquote>
+
+<p class="text">
+ and two groups:
+ <blockquote>
+ <tt>group_AB</tt> (<tt>module_A</tt>, <tt>module_B</tt>)<br>
+ <tt>group_CD</tt> (<tt>module_C</tt>, <tt>module_D</tt>)<br>
+ </blockquote>
+
+<p class="text">
+ To execute <tt>module_A</tt> by itself you would use something like this:
+ <blockquote>
+ <code>./build/build.sh -Dmodules=module_A</code><br>
+ </blockquote>
+
+<p class="text">
+ To execute <tt>module_A</tt> then <tt>module_B</tt> you could:
+ <blockquote>
+ <code>./build/build.sh -Dmodules=module_A,module_B</code><br>
+ <br><font size="-1">or</font><br><br>
+ <code>./build/build.sh -Dgroups=group_AB</code><br>
+ </blockquote>
+
+<p class="text">
+ Finally to execute all of the modules you could:
+ <blockquote>
+ <code>./build/build.sh
-Dmodules=module_A,module_B,module_C,module_D</code><br>
+ <br><font size="-1">or</font><br><br>
+ <code>./build/build.sh -Dgroups=group_AB,group_CD</code><br>
+ </blockquote>
+
+<p class="text">
+ The build module also has a <tt>Module Pass-through Hooks</tt> section,
+ which contains targets for each module named
<tt>_module-<em>module-name</em>-<em>target-name</em></tt>.
These targets are called during the execution of the
<tt>modules-<em>target-name</em></tt> calls after the target has
- completed. There is also a
+ completed.
+
+<p class="text">
+ There is also a
<tt>_module-<em>module-name</em>-<em>target-name</em>-prepare target</tt>
which will be called just before execution, but is rarely used. These
targets do not need to be defined and should not be if they are not going
to be used.
<p class="text">
- Currently only post execution targets are defined for the <em>most</em>
- and <em>all</em> targets, where the '*-all' depends on the '*-most'
- target. These pull the output files from the modules output directory
- and install them into the projects output directory in the proper manner
- for the release.
+ Currently only post execution targets are defined for the <tt>most</tt>
+ and <tt>all</tt> targets, where the <tt>*-all</tt> depends on the
+ <tt>*-most</tt> target. These pull the output files from the
+ <em>modules</em> <tt>output/</tt> directory and install them into the
+ <em>projects</em> <tt>output/</tt> directory in the proper manner for
+ the release.
<p class="text">
- <a class="link" href="#Contents">Contents</a>
+ <a href="#Contents">[Contents]</a>
<jsp:include page="navigation.jsp" flush="true"/>
1.9 +42 -36 newsite/src/docs/developers/cvs.jsp
Index: cvs.jsp
===================================================================
RCS file: /cvsroot/jboss/newsite/src/docs/developers/cvs.jsp,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- cvs.jsp 2001/11/16 02:12:24 1.8
+++ cvs.jsp 2001/11/17 04:19:12 1.9
@@ -6,19 +6,22 @@
<!-- CONTENT -->
<p class="head">JBOSS IS DEVELOPED PUBLICLY</p>
+
+<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
+
<p class="text">
- <jsp:include page="/common/picateam.jsp" flush="true" />
JBoss is a free implementation of the J2EE interfaces from SUN.
Our code is co-developed and the source is freely available.
You can either get a daily snapshot of the sources to browse or if you
plan on working with the source tree directly, you can set up a CVS
environment on your machine.
+<!-- end picateam block --></td></tr></table>
+
<p class="text">
- We host our CVS at SourceForge.
- <a class="link" href="http://sourceforge.net";><img
src="http://sourceforge.net/sflogo.php?group_id=22866"; width="88" height="31"
border="0" alt="SourceForge Logo"></a>
- <ul>
- <li><a class="link" href="http://sourceforge.net/projects/jboss";>JBoss
Project Info</a>
+ Our CVS repository (amoung other things) is hosted by our friends at
+ <a class="link" href="http://sourceforge.net";>
+ <img src="http://sourceforge.net/sflogo.php?group_id=22866"; border="0"
alt="SourceForge" align="absmiddle"></a>
</ul>
</p>
@@ -68,42 +71,47 @@
created via <tt>CVSROOT/modules</tt>, so look there for more information
about how they work.
- <ul class="text">
- <li><b>jboss-all</b>: Everything required to build JBoss.
- <li><b>jboss-website</b>: The JBoss website.
- <li><b>jboss-mq</b>: The JBossMQ standalone server.
- <li><b>jboss-plugins</b>: Plugins to the JBoss server.
- <li><b>tools</b>: Tools for building modules.
- <li><b>thirdparty</b>: Thridparty support libraries.
- </ul>
+ <blockquote>
+ <dl class="text">
+ <dt><b>jboss-all</b></dt>
+ <dd>Everything required to build JBoss.</dd>
+
+ <dt><b>jboss-website</b></dt>
+ <dd>The JBoss website.</dd>
+
+ <dt><b>jboss-mq</b></dt>
+ <dd>The JBossMQ standalone server.</dd>
+
+ <dt><b>jboss-plugins</b></dt>
+ <dd>Plugins to the JBoss server.</dd>
+
+ <dt><b>tools</b></dt>
+ <dd>Tools for building modules.</dd>
+
+ <dt><b>thirdparty</b><dt>
+ <dd>Thridparty support libraries.</dd>
+ </dl>
+ </blockquote>
<p class="text">
The following aliases are also available:
-
- <ul class="text">
- <li><b>website</b>: jboss-website
- <li><b>plugins</b>: jboss-plugins
- </ul>
-
- <p class="head">Building Guide and Instructions</p>
- <p class="text">
- For information on building the sources please see our
- <a href="/developers/buildsystem.jsp">Build System Guide</a>
- for further instructions.
+ <blockquote>
+ <dl class="text">
+ <dt><b>website</b></dt>
+ <dd>jboss-website</dd>
+
+ <dt><b>plugins</b></dt>
+ <dd>jboss-plugins</dd>
+ </dl>
+ </blockquote>
<p class="head">CVS Administration Polcies</p>
<p class="text">
- For our policies on CVS versioning and branching see:
- <a class="link" href="CVSAdmin.jsp">CVS Admin</a>.
+ For our policies on CVS versioning and branching see the
+ <a class="link" href="CVSAdmin.jsp">CVS Administration Guide</a>.
- <p class="text">
- <ul>
- <li><a class="link" href="http://jakarta.apache.org/ant";>Ant Home</a>
- </ul>
- </p>
-
<p class="head">WHAT IS CVS (Concurrent Versions System) ?</p>
<p class="text">
@@ -120,9 +128,7 @@
instructing CVS to merge the work when each developer is done.
<p class="text">
- <ul class="text">
- <li><a class="link" href="http://www.cvshome.org";>CVS Home</a>
- </ul>
- </p>
+ Visit the <a class="link" href="http://www.cvshome.org";>CVS Homepage</a>
+ for more information.
<jsp:include page="navigation.jsp" flush="true"/>
1.10 +6 -4 newsite/src/docs/developers/navigation.jsp
Index: navigation.jsp
===================================================================
RCS file: /cvsroot/jboss/newsite/src/docs/developers/navigation.jsp,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- navigation.jsp 2001/11/16 02:12:24 1.9
+++ navigation.jsp 2001/11/17 04:19:12 1.10
@@ -80,10 +80,12 @@
JBOSS.ORG
</td></tr></table>
-
- <a class="linkmenu" href="jboss-projects.jsp">JBoss
Projects</a><br>
- <a class="linkmenu" href="contrib.jsp">Contribute</a><br>
- <a class="linkmenu" href="cvs.jsp">CVS</a><br>
+ <a class="linkmenu"
href="jboss-projects.jsp">JBoss Projects</a><br>
+ <a class="linkmenu" href="contrib.jsp">Contribute</a><br>
+ <a class="linkmenu" href="cvs.jsp">CVS</a><br>
+ <a class="linkmenu" href="quickstart.jsp">Quick Start</a><br>
+ <a class="linkmenu" href="buildsystem.jsp">Build System</a><br>
+ <a class="linkmenu"
href="http://sourceforge.net/projects/jboss";>SF Project Info</a><br>
</td>
<td bgcolor="#ffcc00" valign="top"><img src="/pictures/btb5.gif"></td>
1.2 +17 -21 newsite/src/docs/developers/slogan.jsp
Index: slogan.jsp
===================================================================
RCS file: /cvsroot/jboss/newsite/src/docs/developers/slogan.jsp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- slogan.jsp 2001/10/05 18:23:52 1.1
+++ slogan.jsp 2001/11/17 04:19:12 1.2
@@ -1,26 +1,22 @@
<!-- MAIN CONTENT -->
<table cellspacing="0" cellpadding="0" border="0" width="100%" height="20">
- <tr>
-
-
- <td colspan="2" width="195"><img src="/pictures/t.gif" width="195"
height="1"></td>
- <td width="100%" align="left" valign="center" nowrap><p class="slogan">
- <img src="/pictures/cog1.gif" width="44" height="13"
align="absmiddle">
-
- <!-- SLOGAN -->
-
- <%= request.getParameter("SLOGAN") %>
- <img src="/pictures/cog2.gif" width="44" height="13"
align="absmiddle">
- </td>
- <td width="65"><img src="/pictures/main3.gif" width="65"
height="20"></td>
- </tr>
- <tr>
- <td bgcolor="#eeeeee"><img src="/pictures/t.gif" width="115"
height="540"></td>
- <td valign="top" background="/pictures/mainfill.gif"><img
src="/pictures/main1.gif" width="80" height="340"></td>
- <td width="100%" bgcolor="#eeeeee" valign="top"><br>
-
- <table celspacing="0" cellpadding="0" border="0" width="100%">
- <tr>
+ <tr>
+ <td colspan="2" width="195"><img src="/pictures/t.gif" width="195"
height="1"></td>
+ <td width="100%" align="left" valign="center" nowrap><p class="slogan">
+ <img src="/pictures/cog1.gif" width="44" height="13" align="absmiddle">
+ <!-- SLOGAN -->
+ <%= request.getParameter("SLOGAN") %>
+ <img src="/pictures/cog2.gif" width="44" height="13" align="absmiddle">
+ </td>
+ <td width="65"><img src="/pictures/main3.gif" width="65" height="20"></td>
+ </tr>
+ <tr>
+ <td bgcolor="#eeeeee"><img src="/pictures/t.gif" width="115" height="540"></td>
+ <td valign="top" background="/pictures/mainfill.gif"><img
src="/pictures/main1.gif" width="80" height="340"></td>
+ <td width="100%" bgcolor="#eeeeee" valign="top"><br>
+ <table celspacing="0" cellpadding="0" border="0" width="100%">
+ <tr>
<td><div align="justify">
+<!-- PAGE CONTENT -->
1.1 newsite/src/docs/developers/buildsystem-faq.jsp
Index: buildsystem-faq.jsp
===================================================================
<jsp:include page="head.jsp" flush="true"/>
<!-- $Id: buildsystem-faq.jsp,v 1.1 2001/11/17 04:19:12 user57 Exp $ -->
<jsp:include page="slogan.jsp" flush="true">
<jsp:param name="SLOGAN" value="BUILD SYSTEM FAQ"/>
</jsp:include>
<!-- ==================================================================== -->
<!-- Preface -->
<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
Find the answers to the most frequently asked questions about the
build system here.
<!-- end picateam block --></td></tr></table>
<!-- ==================================================================== -->
<p class="head"><a name="Contents">Contents</a>
<p class="text">
<ul class="text">
<li><a href="#Ant_directly">Why can't I use <tt>ant</tt> directly?</a>
</ul>
<!-- ==================================================================== -->
<p class="head">
<a name="Ant_directly">Why can't I use <tt>ant</tt> directly?<a/>
<p class="text">
The JBoss build system is based on Ant, but requires a very specific
environemnt to execute in. To facilitate easy usage and minimize user
problems we have choosen to provide a JBoss specific <tt>build.sh</tt>
and <tt>build.bat</tt> which perform the proper environemnt setup for
the build system to run smoothly.
<p class="text">
There are also number of support and tool libraries which are required
for some of the optional ant tasks as well as other custom tasks which
help the build system do it's job. The correct versions of these
libraries are kept in the <tt>tools</tt> module from CVS and should be
included as a sub-module of the project you have checked out.
<p class="text">
See the <a href="buildsystem.jsp">Build System Guide</a>
for more details.
<p class="text">
<a href="#Contents">[Contents]</a>
<jsp:include page="navigation.jsp" flush="true"/>
1.1 newsite/src/docs/developers/quickstart.jsp
Index: quickstart.jsp
===================================================================
<jsp:include page="head.jsp" flush="true"/>
<!-- $Id: quickstart.jsp,v 1.1 2001/11/17 04:19:12 user57 Exp $ -->
<jsp:include page="slogan.jsp" flush="true">
<jsp:param name="SLOGAN" value="QUICK START GUIDE"/>
</jsp:include>
<!-- ==================================================================== -->
<!-- Preface -->
<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
This document is meant to help developers who are new to the project
or for those who might not fully understand how to check out the correct
CVS module and build it.
<p class="text">
This guide will <b>NOT</b> show you how to write code, nor will it
explain how JBoss functions or instruct you on how to use your computer
or make a cup of coffee. Though it is possible that such guide documents
exist or are in the process of being brought to life, don't expect to find
any of that information here.
<!-- end picateam block --></td></tr></table>
<p class="text">
Unless specified otherwise, all examples given are formated for UNIX
users and assume that the current working directory (CWD) is the project
directory which contains the <tt>build/</tt> sub-directory. Windows
users can <em>probably</em> substitute <tt>/</tt> for <tt>\</tt>,
<tt>.sh</tt> for <tt>.bat</tt> and omit any preceding <tt>.</tt> to
create runnable command examples.
<p class="text">
Some of the output examples have been truncated either horizontally,
vertically or both to preserve the layout of this page. Truncation
is marked by <tt>...</tt>.
<p class="text">
If you are looking for more detailed information about the build system
check out the <a href="buildsystem.jsp">Build System Guide</a>
or to peruse the list of frequently asked questions (and their answers)
look at the <a href="buildsystem-faq.jsp">Build System FAQ</a>.
<!-- ==================================================================== -->
<p class="head"><a name="Contents">Contents</a>
<p class="text">
<ul class="text">
<li><a href="#Introduction">Introduction</a>
<li><a href="#Requirements">Requirements</a>
<li><a href="#Getting_the_Sources">Getting the Sources</a>
<li><a href="#Get_To_Know_Your_Environment">Get To Know Your Environment</a>
<li><a href="#Start_the_Build">Start the Build</a>
<li><a href="#Start_JBoss">Start JBoss</a>
<li><a href="#Run_the_Testsuite">Run the Testsuite</a>
<li><a href="#What_To_Do_Next">What To Do Next</a>
</ul>
<!-- ==================================================================== -->
<p class="head">
<a name="Introduction">Introduction<a/>
<p class="text">
Hello friends and welcome to the wonderful world of JBoss! In the next
few mintutes (hours or days, depending on how fast your computer, network
connection and cognitive ability is) this guide will show you how to:
<ul class="text">
<li>Check out the latest development source files from CVS
(or download a nightly snapshot)
<li>Setup your build environemnt
<li>Build a partial or complete development server release
<li>Start up the server instance
<li>Connect to the instance
<li>Execute the testsuite
</ul>
<p class="text">
This guide will focus on the <tt>jboss-all</tt> project. This project
contains everything used to build the full production release of JBoss
and is used by most developers when working on the sources. There are
other methods to check out the components that it provides, but we
do not suggest that you try to do that.
<p class="text">
There are other projects available, which use the same build system.
Sections of this guide, which are specific to CVS or the build system
can <em>probably</em> apply to those projects as well; your millage may
vary.
<p class="text">
To follow the guide, simply read the sections in order and perform the
tasks which each section defines.
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="Requirements">Requirements<a/>
<p class="text">
To effectivly build JBoss make sure to meet the following:
<ul class="text">
<li>A UNIX (posix) or Windows (win32) compatible operating system.
<li>A Java Developers Kit (JDK) version 1.3 or compatible compiler and
class libraries.
<li>100-350 megabytes of disk space<sup>*</sup>:
<ul class="text">
<li>50-100 megabytes for the sources, tools and support libraries.
<li>100-150 megabytes to build a full developement release
and the testsuite.
<li>50-100 megabytes to build javadocs.
</ul>
<li>A CVS client or access to a snapshot of the development sources.
<li>A brain, a sense of humor and some paitence. =)
</ul>
<p class="text">
<b>*</b> Disk space requirements are rougly based on the
<tt>jboss-all</tt> project. Other projects may require more or less
space.
<p class="text">
Windows users can <em>optionaly</em> install the
<a href="http://sources.redhat.com/cygwin";>Cygwin</a> tools available from
<a href="http://www.redhat.com";>RedHat</a>. This is in no way a
requirement, but could make your life easier if you are used to using a
UNIX-like OS but are stuck on Windows.
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="Getting_the_Sources">Getting the Sources<a/>
<p class="text">
You can get the sources for the <tt>jboss-all</tt> project from CVS
or from a nightly CVS snapshot.
<p class="text">
To get the sources from CVS, follow the instructions on the
<a href="cvs.jsp">CVS</a> page to get and setup your CVS client.
Once you have done that you can check out the module:
<blockquote>
<code>cvs -z3 checkout jboss-all</code><br>
</blockquote>
<p class="text">
You should see output similar to:
<font size="-1"><pre>
U tools/bin/ant
U tools/bin/ant.bat
U tools/bin/antRun
U tools/bin/antRun.bat
U tools/bin/antx.bat
U tools/bin/lcp.bat
U tools/bin/runant.pl
U tools/bin/runant.py
U tools/lib/JavaStyle.jar
U tools/lib/ant.jar
...
U thirdparty/apache/axis/lib/axis.jar
U thirdparty/apache/axis/samples/addr/Address.class
U thirdparty/apache/axis/samples/addr/AddressBook.class
U thirdparty/apache/axis/samples/addr/AddressBook.wsdl
...
</pre></font>
<p class="text">
To get the sources from a nightly
<a href="/snapshots/">snapshot</a> simply download the
appropriate archive format for the <tt>jboss-all</tt> project
(<a href="/snapshots/jboss-all.zip">zip</a> or
<a href="/snapshots/jboss-all.tgz">tgz</a>), and extract it.
<p class="text">
Once you have checked out or extracted the project sources you
should have a <tt>jboss-all/</tt> directory with a sub-directory layout
similar<sup>*</sup> to this:
<blockquote>
<tt>CVS/</tt><br>
<tt>tools/</tt><br>
<tt>thirdparty/</tt><br>
<tt>build/</tt><br>
<tt>j2ee/</tt><br>
<tt>naming/</tt><br>
<tt>server/</tt><br>
<tt>pool/</tt><br>
<tt>connector/</tt><br>
<tt>messaging/</tt><br>
<tt>security/</tt><br>
<tt>cluster/</tt><br>
<tt>admin/</tt><br>
<tt>testsuite/</tt><br>
<tt>plugins/</tt><br>
</blockquote>
<p class="text">
<b>*</b> The exact directory layout will change as modules are added or
removed from the project. As long as there were no problems durring the
checkout everything should be fine.
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="Get_To_Know_Your_Environment">Get To Know Your Environment<a/>
<p class="text">
Now that you have the sources you might want to poke around a little
to become more comfortable with the module and directory structure.
<p class="text">
The sub-directories inside of <tt>jboss-all/</tt> are each module
directories (except for the <tt>CVS/</tt> directory, which we will
ignore from now on).
<p class="text">
Each module contains the same basic layout with a few exceptions, which
you are about to learn.
<p class="text">
The <tt>tools</tt> module is a special module which contains scripts,
libraries and other files which are required for the the build system
to function. Unless you are adding new functionality to the build
system or updating a support library, you can safely ignore it.
<p class="text">
Next is the <tt>thirdparty</tt> module, which holds as you might guess,
libraries and other support files which are dependencies of the project
and are maintained by a thirdparty vendor.
<p class="text">
The <tt>plugins</tt> modules, is really just an organization tool to
seperate the core modules from optional plugin components to the server.
The component modules that are here are considered standard plugins and
are included in JBoss releases. Each directory under <tt>plugins/</tt>
is a regular module (as described below).
<p class="text">
Finally there is the <tt>build</tt> module. This module controls the
building of all other modules and is responsible for generating project
release directories and archives.
<p class="text">
All of the other modules follow a standard layout and usually contain
source files which are stored in the <tt>src/</tt> sub-directory.
<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
Each module has a <tt>build.xml</tt> which is the build control file and
contains all of the information, targets and tasks to build the module.
<p class="text">
The build system is based on Ant, but you <b>MUST</b> use the given
<tt>build.sh</tt> or <tt>build.bat</tt> scripts to start the process.
Do <b>NOT</b> expect that executing <tt>ant -f build.xml</tt> will work,
because it <b>WILL NOT</b>.
<!-- end picateam block --></td></tr></table>
<p class="text">
Once you are comfortable we can start building. As an optional step, you
can <em>pre-initialize</em> the build system and define or set some user
local properties, which can alter the behavior of the build:
<blockquote>
<code>./build/build.sh init</code><br>
</blockquote>
<p class="text">
This will create (among other things) a <tt>./build/local.properties</tt>
file, which you should take a look at now. This file allows you to change
how the build system works with out accidentially checking in your local
changes. If this is the first time you are building the sources you might
want to leave things as they are, or you might run into problems.
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="Start_the_Build">Start the Build<a/>
<p class="text">
Finally we are ready to actually start up the build and make it do
something useful!
<p class="text">
The default project build configuration is setup to build all of the
standard components which are included in a production release, so
all we have todo is tell the build system to start:
<blockquote>
<code>./build/build.sh</code><br>
</blockquote>
<p class="text">
This may take minutes or hours depending on how fast (or slow) your
computer is. On an Intel Pentium 3 800 512m running RedHat 7.2 it
takes about 3 minutes.
<p class="text">
The output of the build should be slightly verbose and look something like
this:
<font size="-1"><pre>
Searching for build.xml ...
Buildfile: /home/jason/ws/jboss-all/build/build.xml
init:
_init-child:
_init-local-properties:
[copy] Copying 1 file to /home/jason/ws/jboss-all/build
_init-buildlog:
_configure:
_configure-tools:
_configure-libraries:
_configure-modules:
[echo] groups: default
[echo] modules:
j2ee,naming,server,security,messaging,pool,connector,admin,cluster...
_configure-tasks:
_init-show-environment:
modules-most:
[execmodules]
======================================================================
== Executing 'most' in module 'j2ee'...
==
...
install-dependencies:
[copy] Copying 3 files to
/home/jason/ws/jboss-all/build/output/jboss-3.0.0alpha/lib
[copy] Copying 29 files to
/home/jason/ws/jboss-all/build/output/jboss-3.0.0alpha/lib/ext
[copy] Copying 7 files to
/home/jason/ws/jboss-all/build/output/jboss-3.0.0alpha/client
install:
most:
main:
BUILD SUCCESSFUL
Total time: 2 minutes 17 seconds
</pre></font>
<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
You may see some warnings durring the build, probably due to the usage of
deprecated methods or something, but you can safely ignore those. If
everything built with no errors you should see a <tt>BUILD SUCCESSFUL</tt>
message at the end (as shown above).
<!-- end picateam block --></td></tr></table>
<!--
| Show some error siturations too.
-->
<p class="text">
In this example the <em>default</em> target was used. There are a number
of other targets which are used to produce more output, show information
or clean things up which you should play with too. To get a list of the
most common targets and a brief description, re-run the build and
specify the <tt>help</tt> target:
<blockquote>
<code>./build/build.sh help</code><br>
</blockquote>
<p class="text">
This command should output something like this:
<font size="-1"><pre>
Searching for build.xml ...
Buildfile: /nfs/home/jason/ws/jboss/tmp/jboss-all/build/build.xml
help:
[help]
[help] The The JBoss Build module.
[help]
[help] all Executes all modules and builds everything.
[help] clean Cleans up most generated files.
[help] clobber Cleans up all generated files.
[help] main Executes the default target (most).
[help] most Executes all modules and builds most
everything.
[help] release-all Builds a distribution for each archive type.
[help] release-tar Builds a TAR release distribution.
[help] release-tgz Builds a TAR-GZIP release distribution.
[help] release-zip Builds a ZIP release distribution.
[help] run-basic-testsuite Execute the testsuite.
[help] run-jboss Runs the JBoss server.
[help] run-testsuite Execute the testsuite.
[help] testcase Run a test case.
[help] tests Execute all tests.
[help]
[help] -Dgroups=<group>[(,<group>)*] Specify the module groups.
[help] -Dmodules=<module>[(,<module>)*] Specify the modules.
[help] (overrides groups).
[help] -Dtest=<testcase> Specify the testcase to run.
[help] -projecthelp for all targets
[help] -help for full options
[help]
BUILD SUCCESSFUL
Total time: 2 seconds
</pre></font>
<p class="text">
To help you and JBoss build system maintainers debug problems a
<tt>build.log</tt> file is created when the build system initializes,
which contains all of the output which is written to console.
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="Start_JBoss">Start JBoss<a/>
<p class="text">
Once you have successfully built a development release of JBoss, we can
then start up the server. But before we do that lets look at what the
build system actually did.
<p class="text">
In each module directory (other than <tt>tools</tt>, <tt>thirdparty</tt>
and <tt>plugins</tt>) there is an <tt>output/</tt> sub-directory. This
directory contains all of the <em>output</em> that the build system for
that module has created. No other files (short of <tt>build.log</tt>
and <tt>local.properties</tt>) are created outside of this directory.
<p class="text">
The files which are most important to start a JBoss instance are in the
<tt>output/</tt> directory of the <tt>build</tt> module. Take a look
and you should see a versioned sub-directory for the release which you
have sources for. The version used above is JBoss v3.0. 0alpha, so there
is a <tt>build/output/jboss-3.0.0alpha/</tt> directory. In there is the
exact file system layout which is used to build a production release
archinve. This is also the layout which JBoss requires to run.
<p class="text">
At the time this document was written the layout looked like this:
<blockquote>
<tt>lib/</tt><br>
<tt>lib/ext/</tt><br>
<tt>client/</tt><br>
<tt>docs/</tt><br>
<tt>docs/images/</tt><br>
<tt>docs/jms-examples/</tt><br>
<tt>docs/cluster/</tt><br>
<tt>docs/cluster/examples/</tt><br>
<tt>deploy/</tt><br>
<tt>deploy/farm/</tt><br>
<tt>deploy/lib/</tt><br>
<tt>bin/</tt><br>
<tt>conf/</tt><br>
<tt>conf/default/</tt><br>
<tt>conf/boot-server/</tt><br>
<tt>conf/cluster/</tt><br>
<tt>db/</tt><br>
<tt>db/jbossmq/</tt><br>
<tt>db/hypersonic/</tt><br>
<tt>log/</tt><br>
<tt>tmp/</tt><br>
<tt>admin/</tt><br>
<tt>admin/client/</tt><br>
<tt>admin/client/lib/</tt><br>
<tt>admin/components/</tt><br>
</blockquote>
<p class="text">
Now back to actually starting the server. There both UNIX and Windows
scripts to <em>run</em> the server in the <tt>bin/</tt> directory. To
start the server by hand from the project root directory you run (change
release directory according to the version you are using):
<blockquote>
<code>./build/output/jboss-3.0.0alpha/bin/run.sh</code><br>
</blockquote>
<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
There is also a <tt>run-jboss</tt> target, which performs the same
action and takes care of using the correct release directory based on
the current version automatically:
<blockquote>
<code>./build/build.sh run-jboss</code><br>
</blockquote>
<!-- end picateam block --></td></tr></table>
<p class="text">
Using the build system to start JBoss will re-direct the server output
to <tt>build/run.log</tt> <em>instead</em> of writting them to console.
This target is meant to make it easer to run the testsuite, you may or
may not want to use it.
<p class="text">
The server should produce output similar to the following (either to
console or to the log file):
<font size="-1"><pre>
================================================================================
JBoss Bootstrap Environment
JAVA: /opt/java/jdk/bin/java
JAVA_OPTS: -server -Djboss.boot.loader.name=run.sh
-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.crimson.jaxp.DocumentBuilderFactoryImpl
-Djavax.xml.parsers.SAXParserFactory=org.apache.crimson.jaxp.SAXParserFactoryImpl
CLASSPATH: /home/jason/ws/jboss-all/build/output/jboss-3.0.0alpha/bin/run.jar:
================================================================================
[GPA] Microkernel ClassLoaders and Libraries initialized
Libraries adding URLClassLoader 1836372353 key URL
file:/home/jason/ws/jboss-all/build/output/...
Libraries adding URLClassLoader -1140360937 key URL
file:/home/jason/ws/jboss-all/build/output/...
Libraries adding URLClassLoader -237481782 key URL
file:/home/jason/ws/jboss-all/build/output/...
[19:13:05,862,root] Started Log4jService,
config=file:/home/jason/ws/jboss-all/build/output/...
[19:13:05,947,GPA] General Purpose Architecture [GPA]
[19:13:05,957,GPA] Java version: 1.3.1_01,Sun Microsystems Inc.
[19:13:05,968,GPA] Java VM: Java HotSpot(TM) Server VM 1.3.1_01,Sun Microsystems Inc.
[19:13:05,978,GPA] OS-System: Linux 2.4.7-10,i386
[19:13:05,989,GPA] JBoss Version : 3.0.0alpha(200111161633)
[19:13:06,014,GPA] JBoss start time : Fri Nov 16 19:13:03 PST 2001
...
</pre></font>
<p class="text">
When the server is <em>mostly</em> started it should log a message like:
<font size="-1"><pre>
[19:16:48,956,Default] JBoss 3.0.0alpha(200111161633) [RABBIT-HOLE] Started in
0m:40s:844ms
</pre></font>
<p class="text">
There could still be services deploying or other initialization going on,
but for the most part the server is up and running now.
<p class="text">
A simple test would be to attempt to connect to the HTML JMX Console,
which should show you the <em>Agent View</em> of the <em>MBeans</em> which
are currently loaded in the server. Todo this simple point your favorite
web-browser at the <tt>http://<em>hostname</em>:8082</tt>, where
<em>hostname</em> is the name of the host where you are running the server
from.
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="Run_the_Testsuite">Run the Testsuite<a/>
<p class="text">
Before any changes are commited, the Testsuite <b>MUST</b> be run to
ensure that such changes have not broken anything. To help make it easy
to run the testsuite, a <tt>run-testsuite</tt> target has been added to
the build system.
<p class="text">
The <tt>run-testsuite</tt> target, will first compile the
<tt>testsuite</tt>, or if it has already compiled, simply ensure that
it has done so completely. Then it will start up
<a href="http://www.junit.org";>JUnit</a> and run through the test cases.
<p class="text">
The testsuite requires that JBoss already be running, or else most if
not all of the tests will fail. It also assumes that it will connect to
a server which as the default configuration. If for example, the Naming
services is not running on the default port of 1099, the tests which
connect to the server via JNDI will fail. To avoid these problems simply
use the <tt>run-jboss</tt> target to start the server, then from another
shell use the <tt>run-testsuite</tt> target.
<p class="text">
The output and analysis of the testsuite is rather comlicated and out of
the scope of this document.
<!--
| Should provide some details on how to generate the reports, if they
| need generation and where the user can point their brower to look at
| them.
-->
<p class="text">
<a href="#Contents">[Contents]</a>
<!-- ==================================================================== -->
<p class="head">
<a name="What_To_Do_Next">What To Do Next</a>
<!-- picateam block --><table><tr><td><jsp:include page="/common/picateam.jsp"
flush="true"/></td><td>
<p class="text">
Well, be sure to give yourself a nice pat on the back for getting this far.
As for what you will do next, only you really know that. We suggest
reading over the <a href="buildsystem.jsp">Build System Guide</a>,
the <a href="buildsystem-faq.jsp">Build System FAQ</a> to get
the full view of the build system.
<p class="text">
If you are looking for other non-build system developer docs, you can
<em>probably</em> find them on the
<a href="/developers">Developers Site</a>.
<!-- end picateam block --></td></tr></table>
<p class="text">
Be sure to check out the
<a href="http://sourceforge.net/projects/jboss";>Project Info</a>
for JBoss on <a href="http://sourceforge.net";>SourceForge</a>, as well
as the <a href="contrib.jsp">Contributors Guide</a> too.
<p class="text">
Good luck, happy coding and remember we love you!
<p class="text">
<a href="#Contents">[Contents]</a>
<jsp:include page="navigation.jsp" flush="true"/>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development
