To successfully build the JAKARTA-TAGLIBS custom tag libraries, you must download and install the following software components (where $JAKARTA_HOME refers to a directory into which you download and install the various Jakarta software components):
JAVA_HOME
environment
variable to point at the directory where your JDK is installed,
and add the $JAVA_HOME/bin
directory to your PATH.
$JAKARTA_HOME/jakarta-ant
.
If you have downloaded the source distribution, you will need to
build the executable version as follows:
cd $JAKARTA_HOME/jakarta-ant ./bootstrap.sh <-- Unix bootstrap <-- WindowsThis should cause the creation of an
ant.jar
file in
the lib
subdirectory. Set the ANT_HOME
environment variable to point at your Ant distribution directory.
$JAKARTA_HOME/jakarta-servletapi
. If you have
downloaded the source distribution, you will need to build the
executable version as follows:
cd $JAKARTA_HOME/jakarta-servletapi ./bootstrap.sh <-- Unix bootstrap <-- WindowsThis should cause the creation of a
servlet.jar
file
in the lib
subdirectory.
Source downloads of the JAKARTA-TAGLIBS distribution, as with all other Jakarta projects, are available from the Jakarta web site at http://jakarta.apache.org/downloads/sourceindex.html.
Download and unpack the JAKARTA-TAGLIBS distribution (from the link above)
into a subdirectory named jakarta-taglibs
under the
$JAKARTA_HOME
directory described above. For example, you
might end up with the following directory structure:
your_jakarta_home_directory/ jakarta-ant/ <-- Contains binary distribution of Ant lib/ <-- Binary libraries directory ant.jar <-- Ant executable classes jakarta-servletapi/ <-- Contains binary distribution of Servletapi lib/ <-- Binary libraries directory servlet.jar <-- Servlet API classes jakarta-taglibs/ <-- Contains source distribution of the JAKARTA-TAGLIBS libraries ... see below for details ... jakarta-tomcat/ <-- Contains Tomcat (if you are using it)
The distribution archive will contain the following file and directory structure:
taglib.tld
.
{library}-doc.war
web
application archive in the binary distribution. See below for more
information about the internal directory structure of web applications.
{library}-examples.war
web application archive in the
binary distribution. See below for more information about the
internal directory structure of web applications.
org.apache.taglibs.{library}
so that multiple
JAKARTA-TAGLIBS can be used in the same application if desired.
Within the doc/ and examples/ subdirectories for each custom tag library, the following directory organization is used to contain the source components of this application:
web.xml
file for this application, plus
any other files that should be copied to the WEB-INF subdirectory.
org.apache.taglibs.{library}.doc
for the documentation
application, and org.apache.taglibs.{library}.examples
for the example application.
index.html
or index.jsp
page in this directory will be the "home" page of the application when
it is deployed in a servlet container.
To build the distribution version of all included custom tag libraries,
set your current directory to the jakarta-taglibs
directory into
which you unpacked the distribution, and execute the global build script:
build <-- Window platforms ./build.sh <-- Unix platforms
In addition to the directories described earlier, two additional directory hierarchies will be created to contain the results, resulting in the following overall organization:
your_jakarta_home_directory/ build/ <-- Contains intermediate form results of building Jakarta applications taglibs/ <-- Contains intermediate form results of building JAKARTA-TAGLIBS custom libraries dist/ <-- Contains the files that will be included in binary distributions of Jakarta applications taglibs/ <-- Contains the files that will be included in the binary distribution of the JAKARTA-TAGLIBS project, as described in binary distribution documentation ... other directories as above ...
When you are working on a particular custom tag library, it is faster to
rebuild only that particular library while doing development. To do this,
change to the top level directory of that custom tag library (for example,
change to the jakarta-taglibs/jspspec
directory to work on the
JSP Specification Examples custom tag library. You can now use one of several
variants of the build script, depending on what you want to do. In
each of the following cases use build
on Windows systems, or
build.sh
on Unix systems:
../../build/taglibs
directory) of the library itself, the
documentation application, and the example application. This copies any
static files that have been changed, and recompiles any Java sourc classes
that have been changed. Because this is the most commonly executed
command, it is the default.
../../build/taglibs/{library}/doc
directory can be set
as the document root, and the application can be executed directly.
../../build/taglibs/{library}/examples
directory can
be set as the document root, and the application can be executed directly.
{library}.jar
and {library}.jar
files for this tag library into the
distribution directory (../../dist/taglibs/{library}
).
These distribution files can be copied directly into web applications
that wish to use this custom tag library.
{library}-doc.war
documentation application, and copy it into the distribution directory
(../../dist/taglibs/{library}
). This application can be
deployed and executed on any servlet container.
{library}-examples.war
examples application, and copy it into the distribution directory
(../../dist/taglibs/{library}
). This application can
be deployed and executed on any servlet container.
dist-library
, dist-doc
, and
dist-examples
).
When you perform a global build, the build dist option is invoked on each included subproject.
Adding a new custom tag library subproject to JAKARTA-TAGLIBS is fairly straightforward. It involves the following steps:
build
,
build.bat
, and build.bat
from one of the
existing subprojects, such as jspspec. Using a text editor,
customize the build.xml
file by changing the value of
the taglib.name
property to the short name of the new
custom tag library subproject you are building.
build.xml
script.
The final step is to modify the top level build.xml
script, so that a global build will include your new library. The
required changes are documented within the global build.xml
file.
NOTE: If your custom tag library requires additional JAR files from external distributions, you may be tempted to check these libraries in to the CVS repository. This behavior is prohibited by Jakarta project guidelines, because it causes many errors due to version interdependencies of shared libraries. Instead, you should include instructions in the user documentation for your library on how to acquire any additional libraries or other components that are required.