======== GETTING STARTED =========

These instructions are intended for developers wanting to work on the
source of daisy, and thus explains how to get things running in a development
environment. All other users should use the binary daisy distribution, and follow
the instructions provided with therein.

If you only want to compile everything and build a binary distribution,
without setting up a runtime environment for during development, certain
steps can be skipped, these will be indicated with [skip when building dist only].
This is useful when you want to try out a SVN snapshot without having
plans to work on Daisy itself.

To build a binary distribution:
 - first follow the instructions in this file
 - then follow the instructions in applications/daisywiki/README.txt for building the frontend
 - then follow the instructions in distro/README.txt

Creating the MySQL database [skip when building dist only]
---------------------------

Required MySQL version: 4.0.20 or higher, 4.1.7 or higher

Assign access rights: login as root user to mysql:

mysql -uroot -pYourSecretPassword

On some MySQL installations, the root user has no password, in that case drop
the -p parameter.

Then grant the necessary access rights using the following commands: (this will
automatically create the users)

GRANT ALL ON daisyrepository.* TO daisy@"%" IDENTIFIED BY "daisy";
GRANT ALL ON daisyrepository.* TO daisy@localhost IDENTIFIED BY "daisy";

(The localhost entries are necessary because otherwise the default access rights
for anonymous users @localhost will take precedence.)

and create the database using:

CREATE DATABASE daisyrepository;


Maven installation
------------------

Maven is the tool used to build Daisy.

Download version 1.0 from http://maven.apache.org

Copy a xalan jar file to MAVEN_HOME/lib/endorsed. 
Xalan can be downloaded from http://xml.apache.org/xalan-j/downloads.html
With more recent releases, the Xalan code has been split up in a xalan.jar
and a serializer.jar, be sure to copy them both.

Apparently there is a problem somewhere if the local maven repository is located
in a directory with spaces in the name (default location is ~/.maven). Since this
is by default the case on Windows, users of that OS should work around this by creating
a build.properties file in their home directory (usually c:\document and settings\USERNAME\)
with the following property in it: maven.home.local=d:\\some_directory


Merlin installation
-------------------

[when building dist only: only installation of the plugins as described
in the last two paragraphs is required, afterwards you can remove merlin]

Download Merlin 3.3.0 from:

http://www.apache.org/dist/avalon/merlin/binaries/

Installation of merlin simply consists of extracting the archive somewhere,
and letting the environment variable MERLIN_HOME point to the created directory.
Then add MERLIN_HOME/bin to your PATH.

Locate the 3 jar files which you can find in the plugins directory in MERLIN_HOME. 
This directory contains three subdirectories which each contain a /plugin 
directory. The jar file can be found there.

Copy these 3 jars to the MAVEN_HOME/plugins directory.

Torque Maven plugin installation
--------------------------------
We use the Apache Torque generator to generate database-specific database creation
SQL scripts from and XML definition.

The torque Maven plugin can be easily installed like this:

maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.1.1

OpenJMS installation [skip when building dist only]
--------------------

* download OpenJMS version 0.7.6.1 from http://openjms.sourceforge.net/

* unzip, and set OPENJMS_HOME environment variable

* make a database and corresponding users on MySQL:

CREATE DATABASE openjms;
GRANT ALL ON openjms.* TO openjms@"%" IDENTIFIED BY "openjms";
GRANT ALL ON openjms.* TO openjms@localhost IDENTIFIED BY "openjms";

* Put mysql database driver somewhere (e.g. in OPENJMS_HOME/lib),
  and reference it in the CLASSPATH by editing
  OPENJMS_HOME/bin/setenv.sh (or .bat for Windows)

* edit OPENJMS_HOME/config/openjms.xml

Inside the Connectors element, add:

    <Connector scheme="tcp">
      <ConnectionFactories>
        <QueueConnectionFactory name="TCPQueueConnectionFactory"/>
        <TopicConnectionFactory name="TCPTopicConnectionFactory"/>
      </ConnectionFactories>
    </Connector>

Replace the DatabaseConfiguration element with:

  <DatabaseConfiguration>
    <RdbmsDatabaseConfiguration
      driver="com.mysql.jdbc.Driver"
      url="jdbc:mysql://localhost/openjms?useServerPrepStmts=false" 
      user="openjms" 
      password="openjms"
      maxActive="10"
      maxIdle="5"
      evictionInterval="3600"
      testQuery="select current_date" />
  </DatabaseConfiguration>

Replace the AdministeredDestinations element with:

  <AdministeredDestinations>
    <AdministeredTopic name="daisy">
      <Subscriber name="fullTextIndexer"/>
      <Subscriber name="emailNotifier"/>
    </AdministeredTopic>
    <AdministeredQueue name="fullTextIndexerJobs"/>
  </AdministeredDestinations>

Add the following elements (as child of the root element):

  <SecurityConfiguration securityEnabled="true"/>
  <TcpConfiguration port="3030" jndiPort="3035"/>

By default, a user "admin/openjms" is configured, which is also used
by the default daisy configuration (which is ok in a development
environment, see the daisy distro instructions on how/where to change this
if needed).

* Create the database tables:

dbtool.sh -create -config $OPENJMS_HOME/config/openjms.xml
or
dbtool.bat -create -config %OPENJMS_HOME%\config\openjms.xml

* Start OpenJMS using OPENJMS_HOME/bin/startup.sh

Installing Daisy Maven plugins
------------------------------
Install Daisy-specific Maven plugins by opening a command prompt
at the Daisy root directory and executing:

cd tools/genscript-plugin
maven plugin:install

and

cd tools/recode-plugin
maven plugin:install

and

cd tools/versioninfo-plugin
maven plugin:install


Compiling
---------

Daisy consists of a number of separate projects. The projects can all
be built in one go simply by executing maven in the base daisy directory:

maven -Dmaven.repo.remote=http://cocoondev.org/repository,http://www.dpml.net,http://www.ibiblio.org/maven

(If the iBiblio Maven repository is down or very slow, consider using a Maven 1 repository mirror like
http://mirrors.sunsite.dk/maven/. Just substitute this URL with the iBiblio one.)

This will build the different artifacts in the correct order and install
them in your local maven repository.

Note: the -Dmaven.repo.remote argument only needs to be specified the first
time you perform a build, after the first build all required artifacts will
be installed in the local Maven repository.

Configuring [skip when building dist only]
-----------

Go to the directory daisy/repository/server

Copy the file myconfig.xml.template to myconfig.xml

Edit the myconfig.xml file and adjust 

1/ the value in the <directory> tags to point to the directories where 
the blobs resp. the index files may be stored. (the directories must exist).
(NOTE: On windows you can use forward slashes in the pathname here.)

2/ the values for the emailer-configuration (fromAddress and smtpHost)

3/ the <driverClasspath> tag should contain the path to the JDBC driver jar.
Usually this is:
/your-home-dir/.maven/repository/mysql/jars/mysql-connector-java-3.1.7-bin.jar

(note: other configuration present in the file
repository-server/src/conf/block.xml can be overridden in
a similar way, such as the database access parameters)

Creating the Repository [skip when building dist only]
-----------------------

1) Go to the daisy root directory.

2) Go to install/target.

3) Execute:   daisy-repository-init-dev --advanced
              (linux: ./daisy-repository-init-dev --advanced)

4) This program will ask a number of parameters, which for a development
   environment you can best leave to their defaults, thus simply press
   enter, except:
    * when asked for the password for the user 'internal', enter 'defaultpwd' (without the quotes)
    * when you reach the "drop database" question, answer yes.
    * when asked to create a daisy data directory, answer no.

Running the Repository server [skip when building dist only]
-----------------------------

Set the MERLIN_HOME environment variable and point it to your merlin installation. 
Put MERLIN_HOME/bin in your PATH

Execute (from daisy/repository/server):
merlin -repository ~/.maven/repository/ -config myconfig.xml src/conf/block.xml

The -repository argument ensures that merlin uses the same runtime repository as
Maven. This is required because all the daisy jars build during the compiling
step reside there. On Windows you should put an explicit path to your
maven repository after the -repository argument.
E.g. merlin -repository c:\maven_base\repository -config myconfig.xml src/conf/block.xml


Executing testcases
-------------------

There is a set of automated testcasing verifying various parts of the repository
functionality. For information on running these, see the file
repository/test/README.txt

[you don't need to do this right now]

Repository API documentation [skip when building dist only]
----------------------------
To view the repository API documentation, go to the directory
daisy/repository/api and execute:

maven javadoc

Then you can view the javadoc by opening

target/docs/apidocs/index.html

in your browser.

Building and running the Cocoon-based DaisyWiki Application
-----------------------------------------------------------

See applications/daisywiki/README.txt