svn commit: r1366072 - /jena/site/trunk/content/documentation/tools/index.mdtext

[rv...@apache.org]

Author: rvesse
Date: Thu Jul 26 16:31:10 2012
New Revision: 1366072

URL: http://svn.apache.org/viewvc?rev=1366072&view=rev
Log:
Added notes on checking JENAROOT and workarounds for spaces in Windows paths

Modified:
    jena/site/trunk/content/documentation/tools/index.mdtext

Modified: jena/site/trunk/content/documentation/tools/index.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/tools/index.mdtext?rev=1366072&r1=1366071&r2=1366072&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/tools/index.mdtext (original)
+++ jena/site/trunk/content/documentation/tools/index.mdtext Thu Jul 26 16:31:10 2012
@@ -8,7 +8,9 @@ a variety of tasks in developing Jena-ba
   - [schemagen](schemagen.html)
   - [eyeball](eyeball-getting-started.html)
 
-### How to set up the CLASSPATH and run Jena command line tools
+### Setting up your Environment
+
+An environment variable `JENAROOT` is used by all the command line tools to configure the class path automatically for you.  You can set this up as follows:
 
 **On Linux / Mac**
 
@@ -20,3 +22,41 @@ a variety of tasks in developing Jena-ba
   - `SET JENAROOT=`*the directory you downloaded Jena to*
   - `SET PATH=%PATH%;%JENAROOT%\bat`
 
+### Running the Tools
+
+Once you've done the above you should now be able to run the tools from the command line like so:
+
+**On Linux / Mac**
+
+ - `sparql --version`
+
+**On Windows**
+
+ - `sparql.bat --version`
+
+This command will simply print the versions of Jena and ARQ used in your distribution, all the tools support the `--version ` option.  To find out how to use a specific tool add the `--help` flag instead.
+
+Note that many examples of using Jena tools typically use the Linux style invocation because most of the Jena developers work on Linux/Mac platforms.  When running on windows simply add `.bat` as an extension to the name of the command line tool to run it, on some versions of Windows this may not be required.
+
+
+### Common Issues with Running the Tools
+
+If you receive errors stating that a class is not found then it is most likely that `JENAROOT` is not set correctly.  As a quick sanity check you can try the following to see if it is set appropriately:
+
+**On Linux / Mac**
+
+ - `cd $JENAROOT`
+
+**On Windows**
+
+ - `cd %JENAROOT%`
+
+If this command fails then `JENAROOT` is not correctly set, please ensure you have set it correctly and try again.
+
+Windows users may experience problems if trying to run the tools when their `JENAROOT` path contains spaces in it, there are two workarounds for this:
+
+ 1. Move your Jena install to a path without spaces
+ 1. Grab the latest scripts from [Trunk][1] where they have been fixed to safely handle this.  Future releases will include this fix and resolve this issue
+
+[1]: http://svn.apache.org/viewvc/jena/trunk/apache-jena/bat/
+