svn commit: r1039073 - /incubator/river/site/trunk/content/river/building-river.mdtext

[th...@apache.org]

Author: thobbs
Date: Thu Nov 25 15:32:37 2010
New Revision: 1039073

URL: http://svn.apache.org/viewvc?rev=1039073&view=rev
Log:
Added additional notes on running the jtreg tests and also use of forward rather than back slashes.

Modified:
    incubator/river/site/trunk/content/river/building-river.mdtext

Modified: incubator/river/site/trunk/content/river/building-river.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/building-river.mdtext?rev=1039073&r1=1039072&r2=1039073&view=diff
==============================================================================
--- incubator/river/site/trunk/content/river/building-river.mdtext (original)
+++ incubator/river/site/trunk/content/river/building-river.mdtext Thu Nov 25 15:32:37 2010
@@ -20,23 +20,19 @@ Notice:    Licensed to the Apache Softwa
 
 Before you can start building River a word of warning;
 
-## Warning
+## A note on paths
 
 The build process does not place nicely if you have spaces in your path names.  This includes the install path of the JDK.  
 
 This can be circumvented, at least on a Windows/Cygwin by using the first 6 characters of the name with a space in, and postfixing a tilde and the number 1.
 
-For example:
-
-    C:\Program Files
-
-Would become:
-
-    C:\Progra~1
+For example; `C:\Program Files` would become; `C:\Progra~1`
 
 If the first six characters of your path name are not a unique name, for example if you have the two paths "C:\Program Files" and "C:\Program Something Else" then the number after the tilde may well be different.  It is suggested that you experiment using the Windows command shell to establish the correct 'tilde plus number' name for your path.
 
-So Windows users please be particular aware.  Also, where path separators are specified colons (:) should be used in preference to semi-colons (;)  even on Windows.
+So Windows users please be particular aware.  
+
+If you are running on Windows, it is also advisable to use a forward slash '/' are the path separator.  This is acceptable to both Java and Ant, and has the added benefit that the paths will be correct if you decide to run the JTREG tests (some of which require a Unix-like/Cygwin environment to run scripts in).  This is particularly important for the `river.home` property which is inherited from in the `qa/build.xml` file and subsequently passed onto the various classes which make up the jtreg tests.
 
 ## Check out the code
 
@@ -90,6 +86,8 @@ Make sure that you have the following in
     jdk1.5.home=/path/to/java1.5 
     jtreg.dir=$RIVER_HOME/jtsk/qa/jtreg
 
+> Please note the remark above about using paths which contains spaces and the use of '/' over '\'.
+
 Execute the following:
 
     cd $RIVER_HOME
@@ -123,22 +121,29 @@ You can find the test categories on [Tes
 
 You must first download and install jtreg following the instructions on their site.
 
+Some of these tests are run as BASH scripts, therefore, if running the jtreg tests on Windows a Cygwin (or similar) environment is necessary.
+
 The JTREG tests can then be run by execute the following:
 
     cd $RIVER_HOME/qa
+    ant harness-runtime
     ant jtreg
 
-If you should cancel a test run, you must run the following before you can start the run again.
+  - If you should cancel a test run, you must run the following before you can start the run again.
 
     ant jtreg-teardown
 
-JTREG will create the directory `$RIVER_HOME/qa/jtreg/JTreport` which contains a report of the test run.
+  - The `harness-runtime` target need only be run once, unless you have changed the core River code and wish to re-run the jtreg tests on the modified code
 
-It is known that test `net/jini/url/httpmd/TestEqual.java` fails.  Please see [Jira issue River-375](https://issues.apache.org/jira/browse/RIVER-375) for details.
+JTREG will create the directory `$RIVER_HOME/qa/jtreg/JTreport` which contains a report of the test run.
 
-> **There are problems with running these tests on Windows which are currently being investigated.**
+#### Running specific JTREG tests
 
+_todo_
 
-#### Running specific JTREG tests
+#### Known Problems
+There are the following known problems with the jtreg tests:
 
-_todo_
\ No newline at end of file
+ 1. Running the tests in a Windows/Cygwin environment is not working yet
+ 1. Some of the tests require a kerberos environment, so these will obviously fail when no such setup is available
+ 1. It is known that test `net/jini/url/httpmd/TestEqual.java` fails.  Please see [Jira issue River-375](https://issues.apache.org/jira/browse/RIVER-375) for details.
\ No newline at end of file