cvs commit: jakarta-turbine-tdk/xdocs tdk-howto.xml

quintonm    2003/04/10 17:12:30

  Modified:    xdocs    tdk-howto.xml
  Log:
  Updates for the tdk-howto from Jeffery Painter [[email protected]].
  
  Revision  Changes    Path
  1.8       +91 -31    jakarta-turbine-tdk/xdocs/tdk-howto.xml
  
  Index: tdk-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-turbine-tdk/xdocs/tdk-howto.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- tdk-howto.xml	31 Mar 2003 15:43:29 -0000	1.7
  +++ tdk-howto.xml	11 Apr 2003 00:12:30 -0000	1.8
  @@ -36,7 +36,7 @@
   Before using the TDK, you are going to need to have a Java Software
   Development Kit supporting Java version 1.2 or later installed on your machine.
   Sun's Java SDK can be downloaded from their website located
  -<a href="http://java.sun.com/j2se/1.3/">here.</a>
  +<a href="http://java.sun.com/j2se/downloads.html">here.</a>
   </p>
   
   <p>
  @@ -44,6 +44,8 @@
   anything. If you do not have Ant installed, you can find out
   how to install Ant
   <a href="http://jakarta.apache.org/ant/manual/install.html">here</a>.
  +The TDK version 2.2.1 is known to have compatibility issues when using Ant 
  +with version less than 1.5.
   </p>
   
   <p>
  @@ -153,7 +155,8 @@
   ]]></source>
   
   <p>
  -should to the trick.  This is all that you have to do to install the TDK.
  +should to the trick. If you have met the above prerequisites, you will not 
  +need to download anything else to proceed with the installation.
   </p>
   
   </section>
  @@ -167,30 +170,46 @@
   </p>
   
   <p>
  -1.  Open up the file "build.properties" in the root TDK directory. Change the
  -property "target.package" to the name of the package that you would like your
  -java files to live in and the property "target.directory" to the directory that
  -you would like your classes to be created in.  These two values are usually a
  -mirror of one another.  Finally, change the property "tdk.project" to the
  -name of the application that you would like to create.  Usually this is the same
  +1.  Open up the file "build.properties" in the root TDK directory. Change the 
  +property "target.package" to the name of the package that you would like your 
  +java files to live in and the property "target.directory" to the directory that 
  +you would like your classes to be created in. These two values are usually a 
  +mirror of one another. Finally, change the property "tdk.project" to the 
  +name of the application that you would like to create. Usually this is the same 
   as the identifier specified at the end of your target.package.
   </p>
   
   <p>
  -2.  Set the JAVA_HOME environment value for your system.  On *nix/BSD using the
  -Bash shell, this can be done with:
  +2.  Setup your local environment variables. You will need both JAVA_HOME and 
  +ANT_HOME environment values for your system. On *nix/BSD using the Bash shell, 
  +this can be done with. It may be smart to go ahead and add these to your startup 
  +system login scripts if you have not already. Your CLASSPATH environment should 
  +not affect Ant's ability to build your TDK however, if you do run into a problem, 
  +you should be able to set CLASSPATH to be empty and build the tdk sample app. 
  +I would suggest setting a third variable for ease in the rest of this sample, TDK_HOME
   </p>
   
   <source><![CDATA[
  +export ANT_HOME="/PATH/TO/ANT/"
   export JAVA_HOME="/PATH/TO/JDK/"
  +export TDK_HOME="/PATH/TO/TDK/"
   ]]></source>
   
   <p>
  -3.  Run Ant in the root directory of the TDK installation. The sample
  -application will be generated with the default name of
  -<strong>newapp</strong>. If you wish to change the name of the default
  -sample app then you must change the <strong>turbine.app.name</strong>
  -property in the <strong>build.properties</strong> file.
  +3.  Change to the TDK_HOME directory and modify the <strong>build.properties</strong> file.  
  +You will need to add an additional property called <strong>tdk.home</strong> which should be set 
  +the same as your environment TDK_HOME.  If you wish to change the name of your 
  +application, you would adjust the property <strong>tdk.project</strong> to the name you wish.
  +</p>
  +
  +<source><![CDATA[
  +tdk.home = /PATH/TO/TDK
  +tdk.project = newapp
  +]]></source>
  +
  +<p>
  +4.  Run Ant in the root directory of the TDK_HOME directory. The sample application 
  +will be generated with the default name of <strong>newapp</strong>.
   </p>
   
   <source><![CDATA[
  @@ -198,28 +217,69 @@
   ]]></source>
   
   <p>
  -from your root TDK directory.  This will create most of the files necessary for
  -running your turbine app.
  +executed from your TDK_HOME directory, will create most of the files necessary for running your turbine app. 
   </p>
   
   <p>
  -4.  Once the initial set of files has been created, you will need to go into
  -the directory "/TDKROOT/webapps/APPNAME/WEB-INF/build" and edit
  -your "build.properties" file.  This file is used to specify properties
  -such as the type of database you are using and your DB connection info.  This
  -information is used to create the tables Turbine will be using and the classes
  -used to access them.  At this time you should also copy your JDBC drivers
  -(renaming .zip files to .jar files) into the
  -"webapps/APPNAME/WEB-INF/lib" directory if you are using a database for which
  -the TDK does not provide JDBC drivers. These files will be important when
  -creating the database tables in the next step.
  +5.  Once the initial set of files has been created, you will need to go into the 
  +directory <strong>/TDK_HOME/webapps/newapp/WEB-INF/build</strong> and edit your <strong>build.properties</strong> file. 
  +This file is used to specify properties such as the type of database you are using and your DB 
  +connection info.  The first adjustment you need to make is to add the <strong>tdk.home</strong>
  +directive to the <strong>build.properties</strong> file.
   </p>
   
  +<source><![CDATA[
  +# -------------------------------------------------------------------
  +#  P R O J E C T  P R O P E R T I E S
  +# -------------------------------------------------------------------
  +
  +tdk.home = /path/to/tdk
  +]]></source>
  +
  +<p>
  +The information in <strong>build.properties</strong> is used to create the tables Turbine will be using 
  +and the classes used to access them. At this time you should also copy your JDBC drivers 
  +(renaming .zip files to .jar files) into the <strong>TDK_HOME/webapps/newapp/WEB-INF/lib</strong> directory if 
  +you are using a database for which the TDK does not provide JDBC drivers. These files will 
  +be important when creating the database tables in the next step.
  +</p>
  +
  +<p>
  +To build the sample app, you will need to add the following configuration scope for torque. Since torque has 
  +been decoupled from the turbine environment, these values are not set by default any longer. Please check 
  +with your database vendor if you need assistance setting up your database values. Note that the <strong>manualCreation</strong> 
  +directive is set to true if you do not wish the tdk to create your database and tables. Set it to false to 
  +automatically build your sample application database. Turbine will still use the old database values in order 
  +to start up the application once you have completed building, so you do need both types of entries 
  +in your properties file. The following example will configure the tdk to build the sample <strong>newapp</strong>
  +database for MySQL.
  +</p>
  +
  +<source><![CDATA[
  +# -------------------------------------------------------------------
  +#  D A T A B A S E  S E T T I N G S
  +# -------------------------------------------------------------------
  +
  +database = mysql
  +databaseDriver = org.gjt.mm.mysql.Driver
  +databaseUrl = jdbc:mysql://localhost/newapp
  +databaseUser = dbUser
  +databasePassword = dbPassword
  +databaseHost = localhost
  +
  +torque.database.name = newapp
  +torque.database.manualCreation = false
  +torque.database.driver = org.gjt.mm.mysql.Driver
  +torque.database.createUrl = jdbc:mysql://localhost/newapp
  +torque.database.buildUrl = jdbc:mysql://localhost/newapp
  +torque.database.user = dbUser
  +torque.database.password = dbPassword
  +]]></source>
  +
   <p>
  -5.  Go to the directory "/TDKROOT/webapps/APPNAME/WEB-INF/build" and run the
  -command "ant init"  This command <strong>must be run</strong> before
  -attempting to use the TDK.  It creates the database tables and OM
  -classes for accessing them.
  +6.  Go to the directory "/TDK_HOME/webapps/newapp/WEB-INF/build" and run the 
  +command "ant init".  This command <strong>must be run</strong> before attempting to use the TDK. 
  +It creates the database tables and OM classes for accessing them.
   </p>
   
   <p>