Preface

Author: $Author$
Version: $Revision$
Location: $URL$

Scope

This document describes how to set up the LiveSupport development environment.

Introduction

LiveSupport uses a well-defined development environment. Most of the LiveSupport-specific files are included in the version control system, but some preparation and setup has to be made on system used to develop LiveSupport as well.

Steps

The following steps needed to be taken for setting up the LiveSupport development environment.

install development tools
set up additional system resources
check out the sources
configure the environment
set up tools used by LiveSupport
personalize your development environment

Install development tools

Install all the tools needed for the development of LiveSupport. Please see the development tools document for a list of tools needed.

Set up additional system resources

The LiveSupport development environment uses some system resources, that are not reasonable to include in the environment itself.

Test database

One such resource is an ODBC datasource to a test database. This database has to be accessible for executing the test suites and applications within the LiveSupport development environment.

First, LiveSupport expects a PostgreSQL database, and an ODBC Data Source accessible to it through unixODBC. Please refer to the documentation of these tools to set them up.

The test environment assumes that it can connect to the PostgreSQL database as localhost via a TCP/IP connection, as the user test. To achieve this access, please make sure to edit postgresql.conf (usually /var/lib/postgres/data/postgresql.conf), to have to following line:

tcpip_socket = true

and also edit pg_hba.conf (usually /var/lib/postgres/data/pg_hba.conf) to include the following line, before other lines related to access through localhost:

host    all         all         127.0.0.1         255.255.255.255   password

After the above two manual edits to the PostgreSQL configuration, execute the script livesupport/bin/setup_test_db.sh , as root to create the required database user, database and ODBC datasource.

Web server

Second, LiveSupport expects:

Apache httpd server running on the development computer
PHP interpreter
PHP apache module
PHP iconv extension (--with-iconv)
DOMXML PHP extension - an XMLv2 module for PHP
PostgreSQL support in PHP
PEAR

Check out the sources

The LiveSupport development directory tree can be accessed anonymously via Subversion, at svn+ssh://code.campware.org/home/svn/repo/livesupport/trunk/livesupport. The following Subversion command would check out the development tree:

svn checkout svn+ssh://code.campware.org/home/svn/repo/livesupport/trunk/livesupport

This will check out and create the LiveSupport development directory structure.

Configure the environment

The development environment is most easily set up by running the following script:

The development environment as to be configured with an autoconf-style configure script. To do this, simply type:


cd livesupport
./bin/setupDevelopmentEnvironment.sh

This script will set up the libraries used by LiveSupport (by compiling and installing them under livesupport/usr), and set up the development environment for all LiveSupport modules.

Personalize your LiveSupport development environment

The LiveSupport development environment can be run in two ways: either only one developer actively doing LiveSupport development on the system, or multiple developers sharing a system for LiveSupport development. In the former case, only one database instance, scheduler daemon and apache (XML-RPC and HTTP/HTML) entry point is needed. In the latter case, each user will have their own database instance, scheduler daemon and apache entry points.

Only one developer doing development on the system

If only one developer is doing development on the system, there is no need to personalize the resources used by the development environment. The following resources are expected on the system.

LiveSupport expects an ODBC Data Source with the following parameters:

DSN: LiveSupport-test
username: test
password: test

This data source should point to a PostgreSQL instance of the same name. Only one developer at the time should access this datasource, as the test suites regularly create and destroy database tables.

The scheduler daemon will use the port 3344.

Please check settings in var/conf.php files in both the storageServer and archiveServer modules and create two symlinks with name corresponding to the 'URL configuration' part of var/conf.php files. Here is an example for default values:

http://localhost:80/livesupportStorageServer/ should point to the <livesupport-src>/modules/storageServer/var directory
http://localhost:80/livesupportArchiveServer/ should point to the <livesupport-src>/modules/archiveServer/var directory
http://localhost:80/admin/ should point to the <livesupport-src>/modules/htmlUI/var directory

Please make <livesupport-src>/modules/htmlUI/var/templates_c/ and <livesupport-src>/modules/htmlUI/var/html/img/ writable for apache.

Multiple developers doing development on the system

In case multiple developers are sharing a system for LiveSupport development, each resource has to be personalized. Please run the livesupport/bin/user_setup_db.sh script as root to make the appropriate steps for personalization. The script expects the name of the user as a mandatory parameter, e.g. invoke as:

cd livesupport
./bin/user_setup_db.sh --user ls_developer_user

The script will set up the following resources:

a PostgreSQL user named test with the password test (if it does not exist)
a PostgreSQL database named LiveSupport-ls_developer_user
an ODBC data source of the same name
define a user-specific port for the scheduler daemon
make certain the directories in the development environment are writable by apache
create personalized configuration files in ~/.livesupport/
create symlinks from ~/public_html/ to XML-RPC and HTML entry points

After running the above script, the livesupport development environment for the specified user will be unique on the system, and will not conflict with resources used by other developers. For example, the LiveSupport HTML user interface for the user will be reachable at:

http://localhost/~ls_developer_user/livesupport/htmlUI/var

Ready to roll

With the above steps completed, the LiveSupport modules and products are ready to be compiled and developed further. Have fun!