======== 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
Note: Maven 2 will not work.

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

ActiveMQ configuration
----------------------
Make a database and corresponding users on MySQL:

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

Create a copy of repository/server/activemq-conf.xml.template:
cp repository/server/activemq-conf.xml.template repository/server/activemq-conf.xml

In this file you can specify you database connection settings, just look for the 
<bean id="dataSource" ...
(the defaults are probably fine if MySQL is running on localhost)

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.12-bin.jar

4/ path to the activemq configuration file.

(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
              (linux: ./daisy-repository-init-dev)
   Note the "-dev" suffix!

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 on each question.

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):

On Linux:
./start-repository

On Windows:
start-repostiory.bat

Note: if your Maven repository directory is in a non-standard location, you might
      have to edit the script and modify the value of the -repository argument.
      This will especially be the case on Windows.

Note: this script opens a debug port on port 8001 (can be removed if not wanted).

merlin -repository ~/.maven/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