User: user57
Date: 01/11/15 18:14:00
Added: src/docs/developers buildsystem.jsp
Log:
o adding the start of the Build System Guide. this version contains
some overview sections for the build system. still needs to have a
quick start section and such... so don't get your boxers in a bind cause
I ain't done with this yet =P
Revision Changes Path
1.1 newsite/src/docs/developers/buildsystem.jsp
Index: buildsystem.jsp
===================================================================
<jsp:include page="head.jsp" flush="true"/>
<jsp:include page="slogan.jsp" flush="true">
<jsp:param name="SLOGAN" value="BUILD SYSTEM GUIDE"/>
</jsp:include>
<!-- ==================================================================== -->
<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>
</ul>
<!-- ==================================================================== -->
<p class="head"><a name="Overview">Overview<a/>
<p class="text">
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.
<p class="text">
What is Ant? Ant is a Java based build tool. In theory it is kind of like
make without makes wrinkles.
<p class="text">
Why? Why another build tool when there is already make, gnumake, nmake,
jam, and others? Because, they are limited to the OS, or at least the OS
type such as Unix, that you are working on. Makefiles are inherently evil
as well.
<p class="text">
Ant is different. Instead a model where it is extended with shell based
commands, it is extended using Java classes. Instead of writing shell
commands, the configuration files are XML based calling out a target tree
where various tasks get executed. Each task is run by an object which
implements a particular Task interface. Granted, this removes some of the
expressive power that is inherent by being able to construct a shell
command such as `find . -name foo -exec rm {}` but it gives you the ability
to be cross platform. To work anywhere and everywhere. And hey, if you
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="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>.
<p class="text">
<em>tools</em> 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>
<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.
<p class="text">
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.
<p class="text">
Some projects have selected a sub-set of directories to include from
this module, but due to some issues with CVS, this does not work as
desired when performing a CVS update.
<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">
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>
<!-- ==================================================================== -->
<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
same layout:
<pre>
build.sh
build.bat
build.xml
</pre>
<p class="text">
Each can have an optional:
<pre>
module/etc/local.properties-example
</pre>
<p class="test">
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.
<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.
<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:
<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>
</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.
<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
</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>
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
</ul>
<p class="text">
These targets are assumed to exist and are called by the
<em>build</em> module.
<p class="text">
Each module will attempt to include a <tt>../build/local.properties</tt>
and a <tt>./local.properties</tt>. In most cases you will want to put
local config into <tt>../build/local.properties</tt> to avoid confusion.
<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
<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.
<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
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
appropriate archive type based on the name.
<p class="text">
<a class="link" href="#Contents">Contents</a>
<!-- ==================================================================== -->
<p class="head">
<a name="The_build_Module">The <em>build</em> Module</p></a>
<p class="text">
The <em>build</em> 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.
<p class="text">
There are <tt>modules-<em>target-name</em></tt> targets for each target
which will iterate over the module list and execute
<tt><em>target-name</em></tt>.
<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.
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,
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
<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
<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.
<p class="text">
<a class="link" 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
