Read Me

######################### start of copyright info ##########################

    VDRAssistant: a flexible application to assist you on tasks
                  in (distributed) VDR-environments.

    Copyright (C) 2007-2010 Reinhard Mantey

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
=============================================================================

Hello,

VdrAssistant is a multi-application suite intended for distributed environments,
so installing is not as easy like: configure && make && make install ...
There exists many choices that depend on individual taste, setup of database, 
etc.

So let me try to guide you through the process of build the suite.

When you read this, you probabely got the sources from svn. Fine!
I suppose, that you have a working java development environment with ant and
may be eclipse (you find .project and .classpath ready for eclipse - just create
a new project with the directory your in) ...
Well, eclipse is not needed - but in case you'll like to dive into ...

I use different ant-files to not conflict with netbeans or other tools, that 
might change existing build.xml-files. One way to avoid lots of typing is 
adding an alias to your .bashrc or .profile or whatever keyfile your shell 
uses for initial setup:
   alias xant='ant -f srbuild.xml'

Of cause, VdrAssistant uses the framework SRJRCFrames - as both have the same
origen. To achive that, you'll have to install the framework at the same level
as VdrAssistant. Let's assume, that /usr/local/src is the base directory for
your projects, so you'll directories should look like:
   /usr/local/src/srjrcframes
   /usr/local/src/vdrassistant

The common parts of the framework are shared with projects using it. To ease 
that sharing, create a link to the common directory from the frameworks 
parent directory:
   /usr/local/src/common
   /usr/local/src/srjrcframes
   /usr/local/src/vdrassistant

So first of all, we have to build the framework:
   cd /usr/local/src/srjrcframes
   xant dist (or if you did not create an alias: ant -f srbuild.xml dist)

Before we can build VdrAssistant, we have to integrate the framework.
There's a helper script called createLinks.sh, which we execute now:
   cd /usr/local/src/vdrassistant
   ./createLinks.sh

After that we can start the build of VdrAssistant with:
   cd /usr/local/src/vdrassistant
   xant dist (or if you did not create an alias: ant -f srbuild.xml dist)
   
That will create all needed jarfiles and already put them all together in a
new subdirectory called "xdist", which is a ready to use working directory.
It also created both installers ready to use:
   - VdrAssistant-xx.run - the bash installer (first step)
   - VdrAssistant-xx.jar - the java installer (second step)

How to install:
---------------
1. Bash-installer:
   The bash installer is intended to install the system services of VdrAssistant
   and (optionally) setup the first mysql database for use of VdrAssistant.

   Both steps are independant.

2. Java-installer:
   The java installer is intended to install the GUI of VdrAssistant.
   Additionally it will be used to update database schema, install sample data
   and setup environment.

3. Usage of installers:   
   None of the installers is intended to be executed with root-privileges!
   sudo is used to perform the tasks that need system-privileges. So ensure, 
   that sudo is installed and that you're allowed to use sudo
   (check /etc/sudoers).

   VdrAssistant makes no assumptions about the machines the services will run
   at. By intention, the distribution of every component to another machine is 
   supported. Of cause, it is possible to install all components to the same 
   machine, but that is not the primary focus.

   Using the bash-installer to create a database is fine for users, that have no
   idea about databases and management of databases. But for this audience,
   mysql will be the only database supported. 
   All other users should know how to create a database and how to execute
   statements, that create/change database schema objects. Those users should
   start with the java-installer.

   As said, a database should exists, as well as a db-admin for remote usage.
   When the java installer is able to connect to the given database, it will
   create a list of statements, needed to bring the database up to date.
   If the database is empty, it will print all statements to populate the
   schema.

   That statements can be saved and executed by a database client application.
   The installers don't care about how the schema is updated.
   It's up to you!

   After having executed the schema changes, let the java installer validate the
   schema again. If all is ok, it will print the status, that the database is up
   to date and installation can begin.

   At that stage, the bash-installer can be used to install the system services
   to any machine, that has a database client and is allowed to connect to the 
   database. Skip the database creation and you're on the way.

OK - that's it. Your VdrAssistant applications should now run and work fine.

If you're interested in hacking/participation, let's talk about other tasks from
build system:

xant website - assembles the website like the one that is hosted at sourceforge
               The built website can be found at web/build

xant apidoc  - generates the javadocs
               result can be found at web/build/javadoc

xant test    - runs the testsuites
               reports can be found at build.reports/html

As VdrAssistant handles recordings and I don't want to waste space of 
sourceforge, I created a different setup for test cases:
   Each testcase takes its parameters from java system properties. Those system
   properties are setup from property files.
   Each project should have a directory testConfig, which is the root for all
   property files like the src-directory being the root for all java files.

   Let's look at DBUtilTest from SRJRCFrames. That file is located at
/usr/local/src/srjrcframes/SRLibAppBase/test/de/schwarzrot/data/access/support/DBUtilTest.java

   There exists 2 ways to setup the property values used by that test case:
1. all testcases use the same property values 
   then you create a file
/usr/local/src/srjrcframes/testConfig/de/schwarzrot/data/access/support/DBUtilTest.properties
   and write all test properties in there.

2. each testcase use different property values
   then you create a directory
/usr/local/src/srjrcframes/testConfig/de/schwarzrot/data/access/support/DBUtilTest
   and place property files in there, having the same name a the test cases:
/usr/local/src/srjrcframes/testConfig/de/schwarzrot/data/access/support/DBUtilTest/testMyMeta.properties
/usr/local/src/srjrcframes/testConfig/de/schwarzrot/data/access/support/DBUtilTest/testPgMeta.properties
   Each file should contain the same property names having different values.

Those testconfiguration is not part of source-tree or can be found at 
repository, as each database can be named different, you're users will be 
different or at least their passwords ...
Same is true for recordings.

The naming of the system properties is verbose, so I'm sure, you can guess what
you'll need to get the testcase running.

If you have any questions/problems/suggestions - don't hesitate to use the
forums or mailing lists from sourceforge (as usual, you only have to register):
 help forum:       http://sourceforge.net/projects/vdrassistant/forums/forum/759561
 open discussions: http://sourceforge.net/projects/vdrassistant/forums/forum/759560

or the mailing lists: 
 user-ML:      https://lists.sourceforge.net/lists/listinfo/vdrassistant-user
 developer-ML: https://lists.sourceforge.net/lists/listinfo/vdrassistant-developers
 
email is MY preferred way to communicate, so why not use the ML?

HAVE FUN