acoliver 2002/11/24 09:16:19
Modified: xdocs/site guides.xml
docs/site guides.html
Added: xdocs/site idedevelopers.xml
docs/site idedevelopers.html
Log:
added a new guide for those "special" ide developers ;-)
Revision Changes Path
1.9 +1 -0 jakarta-site/xdocs/site/guides.xml
Index: guides.xml
===================================================================
RCS file: /home/cvs/jakarta-site/xdocs/site/guides.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- guides.xml 28 May 2002 03:48:01 -0000 1.8
+++ guides.xml 24 Nov 2002 17:16:19 -0000 1.9
@@ -94,6 +94,7 @@
</li>
<li><a href="contact.html"> Contact Information</a></li>
<li><a href="getinvolved.html"> Get Involved</a></li>
+ <li><a href="idedevelopers.html">The IDE Developer's Guide</a></li>
</ul>
<h2>Moderator's Guide</h2>
1.1 jakarta-site/xdocs/site/idedevelopers.xml
Index: idedevelopers.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Andrew C. Oliver</author>
<title>IDE Developer's Guide</title>
</properties>
<body>
<section name="IDE Developer's Guide">
<p>
There is a new breed of developer in today's
<a href="http://java.sun.com";>Java</a> community that is rapidly
discovering <a href="http://www.apache.org";>Apache</a> and more
frequently the <a href="http://jakarta.apache.org";>Jakarta</a> part
of the greater Apache community. These developers often come to us
with little or no command-line experience, some cut their teeth on
tools like <a href="http://www.microsoft.com";>Microsoft's</a>
Visual Basic or other such tools and later moved on to IDEs such as
<a href="http://www.borland.com/jbuilder/";>JBuilder</a>,
<a href="http://www.netbeans.org/";>Netbeans</a> and now
<a href="http://www.eclipse.org/";>Eclipse</a>. While the first
generation of Java developer became intimately familiar with command
line tools, the JDK, the classpath and the ins and outs of things that
are now the core of Java development, this "new breed" of developer
often has little knowledge outside his own IDE, and sometimes doesn't
even understand what it is doing. This guide does not hope to fix that
but hopes to improve the situation and give the "IDE Developer" a stepping
block, a starting point, if you will so that they too can participate
in our <a href="http://jakarta.apache.org";>Apache Jakarta</a> community.
</p>
</section>
<section name="The classpath">
<p>
The Classpath is the fundemental concept behind Java's library usagage.
Think of the Classpath as the Java PATH in Windows or UNIX. Instead of
telling the operating system where to find executables, it tells Java
where to find class files. You can read more about the classpath
<a href="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/classpath.html";>
here</a>, and <a
href="http://java.sun.com/docs/books/tutorial/getStarted/cupojava/win32.html";>here</a>
</p>
<p>
Most IDEs abstract you from the classpath by having you declare and set
up libraries. A common mistake that most IDE developers make is to
include two versions of the same library in the classpath often in the
wrong order. This can cause a number of problems including errant behavior
and strange jar sealing exceptions. Its best to start from scratch and
never just "bootstrap" your project with a classpath from another project
that is full of things it doesn't need.
</p>
<p>
<a href="http://jakarta.apache.org";>Apache Jakarta</a> is known for being
full of helpful expert developers, however, the a quick way to wear out
your welcome is to demand assistance without sorting out your classpath
first. There is nothing more frustrating than a hard to kill bug that
is actually fixed just someone has the old version in their classpath.
So whether you're setting it in your IDE's library manager or at the
commandline, shell script, or through <a
href="http://jakarta.apache.org/ant";>your Ant build tool</a>: make sure you know what
is in your classpath and
that only what you need is there.
</p>
<p>TODO: IDE specific instructions for JBuilder, Netbeans and Eclipse.</p>
</section>
<section name="Ant and Compilation">
<p>
Most IDE developers see the IDE as the only modern and humane way to
program and any other tools as primitive. This attitude will probably
get you laughed out of Jakarta and for good reason. When you're working
with multiple developers accross multiple platforms, this is a very
limited world view to have. Think of it, how well does your carefully
crafted "project" file help run nightly automated builds so that all the
code that has been checked in to version control can be verified?
What about building on UNIX? Running unit tests as part of the build?
Lastly, what about complex dependencies and source structures due to
multiple code bases belonging to a project? (IDEs are notoriously
rigid in the source directory structures they allow, some are breaking this
presupposition, but some of the more popular ones still haven't). There
is a tool which meets all of these requirements and is the Cat's Meow too.
Its called <a href="http://jakarta.apache.org/ant";>Ant</a>.
</p>
<p>
Ant started out as the build tool for the popular servlet engine
now known as <a href="http://jakarta.apache.org/tomcat";>Tomcat</a>.
Ant's cousin in the C world is called Make. However unlike Make, Ant
doesn't give you pathetic error messages about using tabs instead of
spaces (sick! really sick!) and has a much more easily digestible
syntax. Ant's syntax is based on XML, mostly because they didn't want
to write a parser when there were plenty around. And writing an ant
build.xml file is WAY easier than writing a makefile. Most modern
Java IDEs support Ant either natively or through plugins. Some even
have GUIs to abstract you from the build file, however, you will need
to acquire some familiarity with Ant over time as these tools often
break with the complex build procedures often required. Read more about
Ant <a href="http://jakarta.apache.org/ant";>here</a>, <a
href="http://www.amazon.com/exec/obidos/tg/detail/-/1930110588/qid=1038156813/sr=8-4/ref=sr_8_4/102-7589210-1797738?v=glance&s=books&n=507846#product-details";>here</a>
and <a
href="http://www.amazon.com/exec/obidos/tg/detail/-/0596001843/qid=1038156852/sr=1-3/ref=sr_1_3/102-7589210-1797738?v=glance&s=books";>here</a>.
</p>
</section>
<section name="CVS and Version control">
<p>
Its a depressing fact, but most companies either do not use, or misuse
revision control. Are you emailing files around? That is the wrong way
to work on the team. Without proper sourcecode control we'd be up the
creek without a paddle at the Apache Jakarta project. So we make
extensive use of CVS here. One day this may change to a more modern and
sophisticated revision control program like <a
href="subversion.tigris.org">Subversion</a> but that day hasn't quite come yet.
</p>
<p>
Revision control ensures that the old version of code is kept and that
the deltas (or changes) are stored for newer versions. By using
<a href="http://www.cvshome.org/docs/manual/cvs_4.html#SEC48";>Tags</a> you
can even reproduce an entire software release from history. By using
<a href="http://www.cvshome.org/docs/manual/cvs_5.html#SEC58";>Branches</a> you
can develop two versions at once. For instance
if we release 1.0 of our software, and start working on the 2.0 version
only to discover a bug in 1.0; we can still create a 1.1 without getting
any of the 2.0 code mixed in. This isn't only power, its a necessity!
</p>
<p>
You NEED to read <a href="http://www.cvshome.org/docs/manual/";>this</a> if
you don't understand how CVS works. Even if you never use the command-line
tools, you need to understand the concepts behind CVS. At least scan it
even if you're familiar with other revision control systems like
Visual SourceSafe or PVCS, because CVS is its own beast.
</p>
<p>
All of the Apache Jakarta Project's software is stored in CVS under
revision control. And to contribute to the project you need to create
"patches" with the cvs diff -u command (or the GUI equivilent). The
-u specifies the more brief and useful format. To do that you need to
have a working copy of the software. Instructions and a list of modules
can be found <a href="http://jakarta.apache.org/site/cvsindex.html";>here</a>.
You'll even find instructions on how to use GUI tools with CVS, many of
which are free. <a href="http://www.eclipse.org";>Eclipse</a> and
<a href="http://www.netbeans.org";>Netbeans</a> already have very good
support for CVS built in.
</p>
</section>
</body>
</document>
1.20 +1 -0 jakarta-site/docs/site/guides.html
Index: guides.html
===================================================================
RCS file: /home/cvs/jakarta-site/docs/site/guides.html,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- guides.html 12 Nov 2002 15:30:06 -0000 1.19
+++ guides.html 24 Nov 2002 17:16:19 -0000 1.20
@@ -235,6 +235,7 @@
</li>
<li><a href="contact.html"> Contact Information</a></li>
<li><a href="getinvolved.html"> Get Involved</a></li>
+ <li><a href="idedevelopers.html">The IDE Developer's Guide</a></li>
</ul>
<h2>Moderator's Guide</h2>
<p>What mailing list moderators
need to know.</p>
1.1 jakarta-site/docs/site/idedevelopers.html
Index: idedevelopers.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<!-- Content Stylesheet for Site -->
<!-- start the processing -->
<!-- ====================================================================== -->
<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
<!-- Main Page Section -->
<!-- ====================================================================== -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="author"
value="Andrew C. Oliver">
<meta name="email" value="[EMAIL PROTECTED]">
<title>The Jakarta Site - IDE Developer's Guide</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td colspan="2">
<a href="http://jakarta.apache.org";><img
src="http://jakarta.apache.org/images/jakarta-logo.gif"; align="left" border="0"/></a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td width="20%" valign="top" nowrap="true">
<p><strong>About Jakarta</strong></p>
<ul>
<li> <a href="../index.html">Welcome</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/news/index.html";>News & Status</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/mission.html";>Our Mission</a>
</li>
<li> <a href="http://jakarta.apache.org/site/faqs.html";>Our
FAQs</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/library.html";>Reference Library</a>
</li>
<li> <a
href="http://www.google.com/advanced_search?q=+site:jakarta.apache.org&hl=en&as_qdr=all";>Search
Jakarta</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/vendors.html";>Vendor Support</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/contact.html";>Contacting Us</a>
</li>
</ul>
<p><strong>Download</strong></p>
<ul>
<li> <a
href="http://jakarta.apache.org/site/binindex.html";>Binaries</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/sourceindex.html";>Source Code</a>
</li>
</ul>
<p><strong>Get Involved</strong></p>
<ul>
<li> <a
href="http://jakarta.apache.org/site/getinvolved.html";>How to ...</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/cvsindex.html";>CVS Repositories</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/mail.html";>Mailing Lists</a>
</li>
<li> <a href="http://jakarta.apache.org/site/bugs.html";>Bug
Database</a>
</li>
</ul>
<p><strong>SubProjects</strong></p>
<ul>
<li> <a href="../alexandria/index.html">Alexandria</a>
</li>
<li> <a href="../ant/index.html">Ant</a>
</li>
<li> <a href="../avalon/index.html">Avalon</a>
</li>
<li> <a href="../bcel/index.html">BCEL</a>
</li>
<li> <a href="../bsf/index.html">BSF</a>
</li>
<li> <a href="../cactus/index.html">Cactus</a>
</li>
<li> <a href="../commons/index.html">Commons</a>
</li>
<li> <a href="../ecs/index.html">ECS</a>
</li>
<li> <a href="../james/index.html">James</a>
</li>
<li> <a href="../jetspeed/index.html">Jetspeed</a>
</li>
<li> <a href="../jmeter/index.html">JMeter</a>
</li>
<li> <a href="../log4j/index.html">Log4J</a>
</li>
<li> <a href="../lucene/index.html">Lucene</a>
</li>
<li> <a href="../ojb/index.html">OJB</a>
</li>
<li> <a href="../oro/index.html">ORO</a>
</li>
<li> <a href="../poi/index.html">POI</a>
</li>
<li> <a href="../regexp/index.html">Regexp</a>
</li>
<li> <a href="../slide/index.html">Slide</a>
</li>
<li> <a href="../struts/index.html">Struts</a>
</li>
<li> <a href="../taglibs/index.html">Taglibs</a>
</li>
<li> <a href="../tomcat/index.html">Tomcat</a>
</li>
<li> <a href="../turbine/index.html">Turbine</a>
</li>
<li> <a href="../velocity/index.html">Velocity</a>
</li>
<li> <a href="../watchdog/index.html">Watchdog</a>
</li>
</ul>
<p><strong>Project Management</strong></p>
<ul>
<li> <a
href="http://jakarta.apache.org/site/whoweare.html";>Who We Are</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/guidelines.html";>Project Guidelines</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/newproject.html";>New Subprojects</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/jakarta-site2.html";>Website Maintenance</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/acknowledgements.html";>Acknowledgements</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/legal.html";>Legal</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/jspa-position.html";>Apache on the JSPA</a>
</li>
</ul>
</td>
<td width="80%" align="left" valign="top">
<table
border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="IDE Developer's Guide"><strong>IDE Developer's Guide</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
There is a new breed of developer in today's
<a href="http://java.sun.com";>Java</a> community that is rapidly
discovering <a href="http://www.apache.org";>Apache</a> and more
frequently the <a href="http://jakarta.apache.org";>Jakarta</a> part
of the greater Apache community. These developers often come to us
with little or no command-line experience, some cut their teeth on
tools like <a href="http://www.microsoft.com";>Microsoft's</a>
Visual Basic or other such tools and later moved on to IDEs such as
<a href="http://www.borland.com/jbuilder/";>JBuilder</a>,
<a href="http://www.netbeans.org/";>Netbeans</a> and now
<a href="http://www.eclipse.org/";>Eclipse</a>. While the first
generation of Java developer became intimately familiar with command
line tools, the JDK, the classpath and the ins and outs of things that
are now the core of Java development, this "new breed" of developer
often has little knowledge outside his own IDE, and sometimes doesn't
even understand what it is doing. This guide does not hope to fix that
but hopes to improve the situation and give the "IDE Developer" a stepping
block, a starting point, if you will so that they too can participate
in our <a href="http://jakarta.apache.org";>Apache Jakarta</a> community.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="The classpath"><strong>The classpath</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
The Classpath is the fundemental concept behind Java's library usagage.
Think of the Classpath as the Java PATH in Windows or UNIX. Instead of
telling the operating system where to find executables, it tells Java
where to find class files. You can read more about the classpath
<a href="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/classpath.html";>
here</a>, and <a
href="http://java.sun.com/docs/books/tutorial/getStarted/cupojava/win32.html";>here</a>
</p>
<p>
Most IDEs abstract you from the classpath by having you declare and set
up libraries. A common mistake that most IDE developers make is to
include two versions of the same library in the classpath often in the
wrong order. This can cause a number of problems including errant behavior
and strange jar sealing exceptions. Its best to start from scratch and
never just "bootstrap" your project with a classpath from another project
that is full of things it doesn't need.
</p>
<p>
<a href="http://jakarta.apache.org";>Apache Jakarta</a> is known for being
full of helpful expert developers, however, the a quick way to wear out
your welcome is to demand assistance without sorting out your classpath
first. There is nothing more frustrating than a hard to kill bug that
is actually fixed just someone has the old version in their classpath.
So whether you're setting it in your IDE's library manager or at the
commandline, shell script, or through <a
href="http://jakarta.apache.org/ant";>your Ant build tool</a>: make sure you know what
is in your classpath and
that only what you need is there.
</p>
<p>TODO: IDE specific instructions
for JBuilder, Netbeans and Eclipse.</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Ant and Compilation"><strong>Ant and Compilation</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Most IDE developers see the IDE as the only modern and humane way to
program and any other tools as primitive. This attitude will probably
get you laughed out of Jakarta and for good reason. When you're working
with multiple developers accross multiple platforms, this is a very
limited world view to have. Think of it, how well does your carefully
crafted "project" file help run nightly automated builds so that all the
code that has been checked in to version control can be verified?
What about building on UNIX? Running unit tests as part of the build?
Lastly, what about complex dependencies and source structures due to
multiple code bases belonging to a project? (IDEs are notoriously
rigid in the source directory structures they allow, some are breaking this
presupposition, but some of the more popular ones still haven't). There
is a tool which meets all of these requirements and is the Cat's Meow too.
Its called <a href="http://jakarta.apache.org/ant";>Ant</a>.
</p>
<p>
Ant started out as the build tool for the popular servlet engine
now known as <a href="http://jakarta.apache.org/tomcat";>Tomcat</a>.
Ant's cousin in the C world is called Make. However unlike Make, Ant
doesn't give you pathetic error messages about using tabs instead of
spaces (sick! really sick!) and has a much more easily digestible
syntax. Ant's syntax is based on XML, mostly because they didn't want
to write a parser when there were plenty around. And writing an ant
build.xml file is WAY easier than writing a makefile. Most modern
Java IDEs support Ant either natively or through plugins. Some even
have GUIs to abstract you from the build file, however, you will need
to acquire some familiarity with Ant over time as these tools often
break with the complex build procedures often required. Read more about
Ant <a href="http://jakarta.apache.org/ant";>here</a>, <a
href="http://www.amazon.com/exec/obidos/tg/detail/-/1930110588/qid=1038156813/sr=8-4/ref=sr_8_4/102-7589210-1797738?v=glance&s=books&n=507846#product-details";>here</a>
and <a
href="http://www.amazon.com/exec/obidos/tg/detail/-/0596001843/qid=1038156852/sr=1-3/ref=sr_1_3/102-7589210-1797738?v=glance&s=books";>here</a>.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="CVS and Version control"><strong>CVS and Version
control</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Its a depressing fact, but most companies either do not use, or misuse
revision control. Are you emailing files around? That is the wrong way
to work on the team. Without proper sourcecode control we'd be up the
creek without a paddle at the Apache Jakarta project. So we make
extensive use of CVS here. One day this may change to a more modern and
sophisticated revision control program like <a
href="subversion.tigris.org">Subversion</a> but that day hasn't quite come yet.
</p>
<p>
Revision control ensures that the old version of code is kept and that
the deltas (or changes) are stored for newer versions. By using
<a href="http://www.cvshome.org/docs/manual/cvs_4.html#SEC48";>Tags</a> you
can even reproduce an entire software release from history. By using
<a href="http://www.cvshome.org/docs/manual/cvs_5.html#SEC58";>Branches</a> you
can develop two versions at once. For instance
if we release 1.0 of our software, and start working on the 2.0 version
only to discover a bug in 1.0; we can still create a 1.1 without getting
any of the 2.0 code mixed in. This isn't only power, its a necessity!
</p>
<p>
You NEED to read <a href="http://www.cvshome.org/docs/manual/";>this</a> if
you don't understand how CVS works. Even if you never use the command-line
tools, you need to understand the concepts behind CVS. At least scan it
even if you're familiar with other revision control systems like
Visual SourceSafe or PVCS, because CVS is its own beast.
</p>
<p>
All of the Apache Jakarta Project's software is stored in CVS under
revision control. And to contribute to the project you need to create
"patches" with the cvs diff -u command (or the GUI equivilent). The
-u specifies the more brief and useful format. To do that you need to
have a working copy of the software. Instructions and a list of modules
can be found <a href="http://jakarta.apache.org/site/cvsindex.html";>here</a>.
You'll even find instructions on how to use GUI tools with CVS, many of
which are free. <a href="http://www.eclipse.org";>Eclipse</a> and
<a href="http://www.netbeans.org";>Netbeans</a> already have very good
support for CVS built in.
</p>
</blockquote>
</p>
</td></tr>
<tr><td><br/></td></tr>
</table>
</td>
</tr>
<!-- FOOTER -->
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr><td colspan="2">
<div align="center"><font color="#525D76" size="-1"><em>
Copyright © 1999-2002, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
![http://jakarta.apache.org/images/jakarta-logo.gif"](http://jakarta.apache.org/images/jakarta-logo.gif"){kind=link}