avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From je...@apache.org
Subject cvs commit: jakarta-avalon-excalibur NEW_PROJECTS.txt
Date Fri, 03 May 2002 12:19:49 GMT
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 <jefft@apache.org>
                                 $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 jefft@cvs.apache.org'
   - 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:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message