Welcome to the Daisy CMS!
                        http://www.daisycms.org

                     === BUILDING DAISY FROM SOURCE ===

There are two scenarios:

   1. You only want to build a Daisy binary distribution
        (= the same as can be downloaded)

   2. You want to set up a development environment
        (= for incremental buidling and testing)

The second scenario is quite a bit more work the first time (you need
to create databases, set up configuration, ...) but once that's done
you can make changes to the code, quickly rebuild and test. So this
scenario is intended for people who want to work on Daisy itself.


>>> If you (only) want to build a binary distribution:

 - first build the repository server by following the instructions in
   this file, skip all sections marked "[skip when building dist only]"

 - then build the frontend by following the instructions in
   applications/daisywiki/README.txt

 - then assemble the distribution by following the instructions in
   distro/core/README.txt


>>> If you run into problems during the source build:

 - You are welcome to ask for help on the Daisy mailing list.
    (please mention applicable details such as Daisy version,
     operating system, ...)

 - General feedback on confusing instructions (even if you found out how
   to do it in the end) is also welcome.

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

Required MySQL version: 4.1.7 or higher, or 5 final or higher
MySQL version 4.0 and earlier will not work correctly!

Assign access rights:

>> login as root user to MySQL:

mysql -uroot -pYourSecretPassword

(drop the -p if the root user has no password)

>> on the MySQL prompt, execute:

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

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

>> create the database by executing:

CREATE DATABASE daisyrepository charset utf8;


    +---------------------------------------------------------------+
    |                      Maven installation                       |
    +---------------------------------------------------------------+

Maven is the tool used to build Daisy.

>> download version 1.0 from http://maven.apache.org

Maven 2 will not work!

>> copy a Xalan jar file to MAVEN_HOME/lib/endorsed.

You can e.g. download it from here:
http://www.ibiblio.org/maven/xalan/jars/xalan-2.7.0.jar

>> Spaces problem on Windows:

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


    +---------------------------------------------------------------+
    |               Torque Maven plugin installation                |
    +---------------------------------------------------------------+

We use the Apache Torque generator to generate database-specific
SQL scripts from an XML definition.

>> Install the Torque Maven plugin by executing:

maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.1.1 -Dmaven.repo.remote=http://mirrors.ibiblio.org/pub/mirrors/maven


    +---------------------------------------------------------------+
    |                    ActiveMQ configuration                     |
    |                [skip when building dist only]                 |
    +---------------------------------------------------------------+

>> Log in to MySQL as before:

mysql -uroot -pYourSecretPassword

>> Create a database and corresponding users:

CREATE DATABASE activemq charset utf8;
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 usually fine if MySQL is running on localhost)


    +---------------------------------------------------------------+
    |               Installing Daisy Maven plugins                  |
    +---------------------------------------------------------------+

Daisy has some Maven plugins of itself required for the build process.

>> Execute (in the root of the source tree):

cd tools/genscript-plugin
maven plugin:install -Dmaven.repo.remote=http://mirrors.ibiblio.org/pub/mirrors/maven

cd ../../tools/recode-plugin
maven plugin:install -Dmaven.repo.remote=http://mirrors.ibiblio.org/pub/mirrors/maven

cd ../../tools/versioninfo-plugin
maven plugin:install -Dmaven.repo.remote=http://mirrors.ibiblio.org/pub/mirrors/maven


    +---------------------------------------------------------------+
    |                           Compiling                           |
    +---------------------------------------------------------------+

>> Execute (in the root of the source tree):

maven -Dmaven.repo.remote=http://cocoondev.org/repository,http://mirrors.ibiblio.org/pub/mirrors/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.)

Background info: Daisy is separated in a number of different subprojects,
the above command will built them all and put the result of them (an
"artifact" jar) in your local maven repository (~/.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 the repository server                |
    |                [skip when building dist only]                 |
    +---------------------------------------------------------------+

>> Go to the directory 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/ optionally, the values for the emailer-configuration: fromAddress and
   smtpHost

3/ add the JDBC driver. For this, uncomment the <driver> tag and
adjust the <classpath> tag to the path of the JDBC driver jar.
Usually this is:

On unix systems:
/your-home-dir/.maven/repository/mysql/jars/mysql-connector-java-3.1.12-bin.jar

On Windows:

{maven.home.local as defined above}\repository\mysql\jars\mysql-connector-java-3.1.12-bin.jar

4/ If you are using MySQL 4.1 (instead of 5), edit the JDBC URL in the myconfig.xml
   to look like this:
   <url>jdbc:mysql://localhost/daisyrepository?useServerPrepStmts=false&amp;characterEncoding=UTF-8</url>
   (useServerPrepStmts parameter must be present)


    +---------------------------------------------------------------+
    |                 Initializing the repository                   |
    |                [skip when building dist only]                 |
    +---------------------------------------------------------------+

>> Go to the root of the Daisy source tree

>> Go to install/target

>> Execute:

     daisy-repository-init-dev
     (linux: ./daisy-repository-init-dev)

   Note the "-dev" suffix !!!

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]                 |
    +---------------------------------------------------------------+

>> Change to the directory repository/server

>> Execute:

On Linux:
./start-repository

On Windows:
set MAVEN_HOME_LOCAL={maven.home.local as defined above}
start-repostiory.bat

Note: on Linux, if your Maven repository directory is in a non-standard
      location, you will have to edit the start-repository script and
      modify the value of the -r argument.

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


    +---------------------------------------------------------------+
    |                        Running testcases                      |
    |           >  optional, requires dev environment scenario      |
    |           >  just FYI, not needed to do this right now        |
    +---------------------------------------------------------------+

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


    +---------------------------------------------------------------+
    |                Repository API documentation                   |
    |                [skip when building dist only]                 |
    +---------------------------------------------------------------+

To view the repository API documentation, execute the following command
in the root of the daisy source tree:

maven daisy-javadoc

Then you can view the javadoc by opening

target/javadoc/index.html

in your browser.

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

Once you have successfully build the repository server (and in case of
the development setup scenario, have also run it), you can go on to
build the Daisy Wiki web fronted:

See applications/daisywiki/README.txt