User: user57
Date: 01/11/20 23:16:57
Modified: src/docs/developers/guide buildsystem-faq.jsp
Log:
o Added a section to the faq on module hooks.
Revision Changes Path
1.3 +71 -1 newsite/src/docs/developers/guide/buildsystem-faq.jsp
Index: buildsystem-faq.jsp
===================================================================
RCS file: /cvsroot/jboss/newsite/src/docs/developers/guide/buildsystem-faq.jsp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- buildsystem-faq.jsp 2001/11/21 03:21:09 1.2
+++ buildsystem-faq.jsp 2001/11/21 07:16:57 1.3
@@ -1,5 +1,5 @@
<jsp:include page="/developers/head.jsp" flush="true"/>
-<!-- $Id: buildsystem-faq.jsp,v 1.2 2001/11/21 03:21:09 user57 Exp $ -->
+<!-- $Id: buildsystem-faq.jsp,v 1.3 2001/11/21 07:16:57 user57 Exp $ -->
<jsp:include page="/developers/slogan.jsp" flush="true">
<jsp:param name="SLOGAN" value="BUILD SYSTEM FAQ"/>
</jsp:include>
@@ -19,6 +19,7 @@
<p><ul>
<li><a href="#Ant_directly">Why can't I use <tt>ant</tt> directly?</a>
+ <li><a href="#What_are_Hooks">What are <em>hooks</em>?</a>
</ul>
<!-- ==================================================================== -->
@@ -44,6 +45,75 @@
<p>See the <a href="buildsystem.jsp">Build System Guide</a>
for more details.
+
+<p>[<a href="#Contents">Contents</a>]
+
+<h2><a name="What_are_Hooks"></a>What are <em>hooks</em>?</h2>
+
+<p>If you have looked through a <tt>build/build.xml</tt> file, you may have
+ noticed a section dealing with module hooks. Just what are those hooks
+ anyways?
+
+<p>Well, a <em>hook</em> is basically a <em>callback</em> target. Well
+ what does that mean? The best way to explain the hook concept is probably
+ to explain what it is used for, or more precisely why these mysterious
+ bits exist in the build system.
+
+<p>The build system is a dynamic and modular beast. Modules comes, modules
+ go. Modules can exists in a project but not be executed due to
+ the default configuration, or the user may have decided to only run a
+ specific module list or module group. Because the list of executed modules
+ is so dynamic the build system needed a method to execute module specific
+ actions when those modules were actually exectute, or rather <em>only</em>
+ when they are executed. In comes module <em>hooks</em>.
+
+<p><em>Hooks</em> are simply targets named in a specific fasion which will
+ be executed before and/or after the module is executed (as specified by
+ the module executor... the bit which executes the list modules, and the
+ existance of the target as specified by the hook naming convention).
+
+<p>So what do these hooks really do? Well, currently hooks are only used to
+ <em>pull</em> the output of a given module and place it in the correct
+ project release location under the <tt>build/output</tt> directory.
+
+<p>The hooks define the module name, as well as the target which is called
+ on the module to allow differing behavior based on the target specified
+ by the user. This is used to only pull the files which were actually
+ generated by the current module execution.
+
+<p>For example, consider the difference between the <tt>all</tt> and
+ <tt>most</tt> targets. The first should generate all of the possible
+ files that a module has to offer, while the latter should only generate
+ files that are essential or gennerally useful. <tt>most</tt> probably
+ will not build API docs or other supplemental bits, where <tt>all</tt>
+ will.
+
+<p>Since a single hook that collects all of these outputs would probably
+ fail unless the <tt>all</tt> target is invoked, a hook is defined for
+ each target.
+
+<p>These hooks may have a relationship which allows re-use of task elements.
+ Currently all projects define hooks for the <tt>all</tt> and <tt>most</tt>
+ targets, where the <tt>all</tt> hooks depends on the <tt>most</tt> hook.
+ This is done because the <tt>all</tt> target will perform the
+ same functionality of the <tt>most</tt> target or it will simply call or
+ depend on it, and thus it is safe to collect the files from the
+ <tt>most</tt> durring calls to <tt>all</tt>. The opposite is <b>NOT</b>
+ true however. When the <tt>most</tt> target is called, it is not safe
+ to assume that the files generated from calls to <tt>all</tt> exist.
+
+<p>With any luck that all makes sense to you now. If now just remeber that
+ <em>hooks</em> are used to <em>pull</em> output from modules and generated
+ the release structure for a project. For each module that exists in a
+ project and generates output, <em>hooks</em> should be defined in the
+ projects <tt>build/build.xml</tt> file which copy the generated files
+ from module to project output.
+
+<p>If you are a adding support for a new module, or changing an existing
+ <em>hook</em>, please make sure that you test all of the targets which
+ will trigger the hook to be called before commiting the changes. Your
+ fellow developers will appreciate the extra time you took to test that
+ everything works... even if they don't show it =)
<p>[<a href="#Contents">Contents</a>]
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development
