[Commits] (bcm) add FAQ.txt with answers to (what i assume will be) common questions. add

[commits at osafoundation.org]

Commit by: bcm
Modified files:
server/build.xml 1.45 1.46
server/docs/FAQ.txt 1.1 1.2

Log message:
add FAQ.txt with answers to (what i assume will be) common questions. add
rules to build.xml to force the user to initialize the test db before running
tests. make sure the webapp is packed before running tests. ensure that
executables have the correct permissions in the distribution tarball.

thanks to bear and grantbaillie for reviewing the build process!


ViewCVS links:
http://cvs.osafoundation.org/index.cgi/server/build.xml.diff?r1=text&tr1=1.45&r2=text&tr2=1.46
http://cvs.osafoundation.org/index.cgi/server/docs/FAQ.txt.diff?r1=text&tr1=1.1&r2=text&tr2=1.2

Index: server/build.xml
diff -u server/build.xml:1.45 server/build.xml:1.46
--- server/build.xml:1.45	Tue Apr 26 18:01:22 2005
+++ server/build.xml	Wed Apr 27 11:40:55 2005
@@ -249,6 +249,16 @@
 
   <!-- TEST TARGETS -->
 
+  <target name="test" depends="test-core"
+          description="run all tests"/>
+
+  <target name="test-init">
+    <available property="test.db.exists" type="dir"
+               file="${cosmo.test}/db"/>
+    <fail unless="test.db.exists"
+          message="You need to run 'ant test-dbsetup' first!"/>
+  </target>
+
   <target name="test-dbsetup"
           description="set up the test user database">
     <echo>Setting up test db ${cosmo.test.userdb.url}</echo>
@@ -265,10 +275,7 @@
     </sql>
   </target>
 
-  <target name="test" depends="test-core"
-          description="run all tests"/>
-
-  <target name="test-core" depends="deps"
+  <target name="test-core" depends="deps,pack,test-init"
           description="test core subsystem">
     <mkdir dir="${core.build}/testclasses"/>
     <mkdir dir="${core.test}/data"/>
@@ -369,7 +376,7 @@
 
   <target name="dist-tomcat"
           description="install and configure Tomcat">
-    <available property="tomcat.unpacked"
+    <available property="tomcat.unpacked" type="dir"
                file="${cosmo.tmp}/${ext.tomcat.package}"/>
     <antcall target="unpack-tomcat"/>
     <copy todir="${cosmo.dist.tomcat}">
@@ -472,8 +479,16 @@
           depends="dist-clean,dist">
     <tar destfile="${cosmo.dist.version}.tar.gz"
          compression="gzip" longfile="gnu">
+      <tarfileset dir="${cosmo.dist.version}" mode="755"
+                  prefix="cosmo-${cosmo.version}">
+        <include name="bin/cosmoctl"/>
+        <include name="tomcat/bin/*.sh"/>
+      </tarfileset>
       <tarfileset dir="${cosmo.dist.version}"
-                  prefix="cosmo-${cosmo.version}"/>
+                  prefix="cosmo-${cosmo.version}">
+        <exclude name="bin/cosmoctl"/>
+        <exclude name="tomcat/bin/*.sh"/>
+      </tarfileset>
     </tar>
   </target>
 

Index: server/docs/FAQ.txt
diff -u /dev/null server/docs/FAQ.txt:1.2
--- /dev/null	Wed Apr 27 11:40:57 2005
+++ server/docs/FAQ.txt	Wed Apr 27 11:40:55 2005
@@ -0,0 +1,61 @@
+
+                            Cosmo Sharing Server 0.1
+                           Frequently Asked Questions
+
+
+BUILDING
+========
+
+Q: Wow, the build seems to be downloading a lot of jars. Is that
+   normal?
+
+    A: Yes. Cosmo has a lot of external dependencies, which is why we
+       use the Ant Tasks for Maven to manage them. The jars only need
+       to be downloaded the first time you build though, and
+       afterwards only when we update our dependencies.
+
+Q: Where did all those downloaded jars go?
+
+    A: In your Maven2 repository at ~/.m2/repository.
+
+Q: Why is the building downloading JUnit if I already installed it?
+
+    A: One of the jars we depend on has its own dependency on JUnit,
+       so Maven sucks it down into your local repository (see previous
+       question). Our build doesn't look there for JUnit though; it
+       expects you to have installed JUnit in your $ANT_HOME/lib
+       directory. This has the additional benefit of allowing you to
+       use JUnit for projects other than Cosmo.
+
+Q: When running 'ant build', why do I get the error
+   "java.lang.NoClassDefFoundError: org/apache/tools/ant/types/FileList$FileName"?
+
+    A: You are using an older version of Ant and need to upgrade to
+       1.6.2 or later.
+
+
+TESTING
+=======
+
+Q: Why do I have to run a separate ant command to set up the test
+   database? Can't that be done automatically?
+
+    A: No, because we're using HSQLDB in embedded mode, which means
+       that the database is owned by a single process. To run our
+       tests, Ant forks off a separate process for JUnit. If we used
+       a single Ant command to set up the test db and run the tests,
+       then the forked JUnit JVM would not be able to access the
+       database.
+
+
+DEPLOYMENT
+==========
+
+Q: Why are you using an RDBMS anyway?
+
+    A: Because it was the easiest way to get up and running. We will
+       migrate user and role info to JCR very soon (likely in
+       0.2). This will simplify every stage of the process.
+
+
+$Id: FAQ.txt,v 1.2 2005/04/27 18:40:55 bcm Exp $