jefft 02/05/03 05:19:48
Added: . NEW_PROJECTS.txt
Log:
Add doc on how to add new projects
Revision Changes Path
1.1 jakarta-avalon-excalibur/NEW_PROJECTS.txt
Index: NEW_PROJECTS.txt
===================================================================
=======================================
Adding New Excalibur Subprojects
Being a
Voluminous and Exhaustive Discourse
involving CVS, Unix commands,
General Advice and Lore;
also including
Dependency Checking System information
Jeff Turner <[EMAIL PROTECTED]>
$Revision: 1.1 $
$Date: 2002/05/03 12:19:48 $
=======================================
This file describes what you need to do to set up a new Excalibur
subproject. For concreteness, and in keeping with Avalon's theme, let's
imagine
we're adding a new subproject called Joust (thanks Leo). Joust has
dependencies
on avalon-framework.jar, Excalibur Logger, and Instrument. It has a JUnit test
cases, one utilizing the Testcase wrapper.
1.1) Create the directory structure.
------------------------------------
- Copy and rename the 'template-product' directory to 'joust'. As it's name
suggests, 'template-product' is a skeleton build system, ready to be
populated with code.
- Delete all the 'CVS' directories under joust/. This is very important! If
you don't, and start adding and committing code, it will pollute the
'template-product' tree. Under Unix, this can be done with the command:
'find . -name "CVS" -exec rm -r {} \;'
- Add the joust/ directory to CVS, with 'cvs add joust' and 'cvs commit
joust'
1.2) Adding the code
--------------------
1.2.1) If adding new code...
----------------------------
If you are importing new code:
- Copy your source tree into the joust/src/java/ directory. Eg, we'd now have
joust/src/java/org/apache/excalibur/joust/. Likewise copy JUnit tests to
joust/src/test/.
- Do 'cvs add's and 'cvs commit's to add the new files to CVS. It's pretty
tedious; I'd do it as follows:
cvs add `find . -type d` # Add directories
cvs add `find . -type f -not -path "*/CVS/*"` # Add non-CVS files
cvs ci # commit
That's only a good idea if you have no binary files other than
.gif/.jpg/.pdf. If you do, you should instead add them by hand with
'cvs add -kb', and add the rest manually too.
1.2.2) If the code is already in CVS...
---------------------------------------
If your code is already somewhere in Apache's CVS, then you have the option of
copying it directly in the CVS repository. The advantage is that you preserve
the CVS version history. The (considerable) disadvantage is that you can do a
lot of damage by mucking around in the CVS repository directly. Only try this
if:
- losing the version history would be a tragic loss
- you are comfortable with Unix, especially file permissions, and the way you
keep typing 'ls' in DOS boxes is a cause of much mirth to your colleagues.
- You know something of what a CVS repository looks like.
Say that Joust used to be in:
all/src/java/scratchpad/org/apache/excalibur/joust/
To copy this in CVS, you would:
- Log in to cvs.apache.org:
'ssh [EMAIL PROTECTED]'
- Change your umask to make new files you create automatically
group-writable:
'umask 002'
- Go to the Apache CVS repository:
'cd /home/cvs'
- Go to the destination directory:
'cd jakarta-avalon-excalibur/joust/src'
- Create any intermediate directories:
'mkdir -p java/org/apache/excalibur/joust'
- Check that the new directories are group-writable and look like their peers
(paranoia is good..)
'ls -la java/org ; ls -la ../../event/src/java/org'
- Copy the RCS files across:
'cp -rp ../../all/src/scratchpad/org/apache/excalibur/joust/* \
java/org/apache/excalibur/joust'
Note the 'p' flag, which preserves the file ownerships and other attributes
- Log out of cvs.apache.org, and on your own box, do a 'cvs update' in the
joust directory.
Likewise, copy test cases to src/test/.
Note: never 'mv' or 'rm' files in a CVS repository! By doing so, you're
eliminating the continuity and 'audit trail' that is CVS's raison d'�tre. Eg,
if you 'mv' the RCS files, no-one will be able to check out old versions of
the
code.
If all the above steps worked, then keep in mind that once you've finished
adding Joust, you should remove the old directory the old-fashioned CVS way:
'cvs rm -f all/src/java/scratchpad/org/apache/excalibur/joust'.
1.3) Customize the project
--------------------------
1.3.1) Basic customizations
---------------------------
- Edit default.properties, and customize the top block of properties (name,
dir-name, version, etc).
- Edit and customize README.txt
1.3.2) Declare jar properties
-----------------------------
Recall that Joust has dependencies on Framework, Logger and Instrument, and
JUnit and Testcase for the unit tests.
Declare default definitions of jar properties in default.properties. These can
be copied from other projects' default.properties files:
@@ -16,8 +16,34 @@
# REQUIRED LIBRARIES
# --------------------------------------------------
+# ----- Avalon Framework, version 4.1 or later -----
+avalon-framework.home=${basedir}/../../jakarta-avalon
+avalon-framework.lib=${avalon-framework.home}/build/lib
+avalon-framework.jar=${avalon-framework.lib}/avalon-framework.jar
+
+# ----- Excalibur logger, version 1.0 or later -----
+excalibur-logger.home=${basedir}/../logger/dist
+excalibur-logger.lib=${excalibur-logger.home}
+excalibur-logger.jar=${excalibur-logger.lib}/excalibur-logger-1.0.jar
+
+# ----- Excalibur Instrument, version 0.1 or later -----
+excalibur-instrument.home=${basedir}/../instrument/dist
+excalibur-instrument.lib=${excalibur-instrument.home}
+excalibur-instrument.jar=${excalibur-instrument.lib}/excalibur-instrument-0.1.jar
+
# --------------------------------------------------
+# REQUIRED LIBRARIES FOR UNIT TESTS
+# --------------------------------------------------
+
+# ----- Excalibur Testcase, version 1.0 or later -----
+excalibur-testcase.home=${basedir}/../testcase/dist
+excalibur-testcase.lib=${excalibur-testcase.home}
+excalibur-testcase.jar=${excalibur-testcase.lib}/excalibur-testcase-1.0.jar
+
+
+# --------------------------------------------------
+
1.3.3) Add jar properties to classpaths
---------------------------------------
- Add these jar property references to the project.class.path and
test.class.path section of build.xml:
@@ -12,6 +12,9 @@
<!-- Classpath for product -->
<path id="project.class.path">
<pathelement location="${build.classes}"/>
+ <pathelement location="${avalon-framework.jar}"/>
+ <pathelement location="${excalibur-logger.jar}"/>
+ <pathelement location="${excalibur-instrument.jar}"/>
<pathelement location="${checkstyle.jar}"/>
<pathelement path="${java.class.path}"/>
</path>
@@ -26,6 +29,7 @@
<path id="test.class.path">
<pathelement location="${build.testclasses}"/>
<pathelement location="${junit.jar}"/>
+ <pathelement location="${excalibur-testcase.jar}"/>
<path refid="project.class.path"/>
</path>
<property name="cp" refid="test.class.path"/>
1.3.4) Add entries for the dependency checking system
----------------------------------------------------
Excalibur's dependency checking (depchecking) will automatically build any
subordinate Excalibur projects if they are not already built. To enable this,
add calls to the depchecking system in the project's 'dependencies' target:
@@ -35,6 +39,9 @@
<target name="dependencies" description="Check dependencies"
unless="skip.dependencies">
<ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkCommon"/>
+ <ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkFramework"/>
+ <ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkLogger"/>
+ <ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkInstrument"/>
</target>
<target name="dependencies-test" depends="dist-jar, dependencies"
@@ -42,6 +49,7 @@
<!-- Need the jar to prevent recursive deps. -->
<ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkJUnit"/>
+ <ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkTestcase"/>
</target>
1.3) See if it works
--------------------
.. by typing 'ant' :) You should get a jar, build/lib/excalibur-joust-1.0.jar.
Also run 'ant test' to make sure the test cases work.
If it all looks good, commit it.
1.4) But wait! The fun doesn't end there....
--------------------------------------------
Some extra things you should do:
- Add your new project to dependencies.txt, so people can see at a glance
what
depends on what.
- Add a Gump <project> entry in gump.xml. This is usually done by copying
another similar entry, and adding any new jar references to the <ant>
section. Please keep entries in alphabetical order :-)
- If you think another project is going to depend on Joust, you should add it
as a "target" in the dependency checking system:
@@ -382,6 +382,13 @@
<property name="proj.home" value="${basedir}/../pool"/>
</ant>
</target>
+ <target name="checkJoust">
+ <ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkRequiredFile">
+ <property name="name" value="excalibur-joust.jar"/>
+ <property name="path" value="${excalibur-joust.jar}"/>
+ <property name="proj.home" value="${basedir}/../joust"/>
+ </ant>
+ </target>
<target name="checkIO">
<ant antfile="${depchecker.prefix}/depchecker.xml"
target="checkRequiredFile">
<property name="name" value="excalibur-io.jar"/>
Then if other projects want to have Joust automatically built, they can
call:
<ant antfile="${depchecker.prefix}/depchecker.xml" target="checkJoust"/>
--Jeff
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
