TRex Developers setup

Hi developer,

it seems that you're anxious to put you fingers at work. Then ... let's rock and roll !!!

Briefly the step to follow are:

SSH setup (optional)
CVS setup
- Download and install
- Test
Repository
CVS documentation
TRex setup

SSH SETUP

SSH stands for Secure SHell and is intended as a replacement for telnet, rlogin, etc. whose main problem is the data transmision in the clear (all data, including passwords).

This set of programs can be downloaded from OpenSSH and installed in your system (please look for install and setup information for your platform).

Please keep in mind that ssh will not be used by you directly, instead it will be used by CVS (look at the next section).

Once you followed the instructions and ssh has been setup, then you must tell CVS to use ssh, exporting the CVS_RSH environment variable:

export CVS_RSH=ssh

If you get 'permission denied' errors with no prompt for a password, you do not have this environment variable set properly or SSH is not available to your system. Fix this before suspecting a password problem.

CVS SETUP

CVS is a version control system. Using it, you can record the history of sources files, and documents.

Download and install

You can download it from CVS home at GNU (or the Cygwin Linux-like environment for Windows dudes) and follow the instructions in the downloaded package (it's so well documented that no further comments are required).

Test

To test if your SSH and CVS setup have been made right, issue the next command (making the obviuos replacements) and noticing that each new TRex version has a fantasy name ("machinery", in this case, is the first public available one) :

bit-man@home# cvs -n -dyour_username@trex.cvs.sourceforge.net:/cvsroot/trex checkout machinery
your_username@cvs.trex.sourceforge.net's password: <type_your_pass_here>
cvs server: in directory machinery:
cvs [server aborted]: there is no version here; run 'cvs checkout' first
t:/cvsroot/trex checkout

If something in the style appears, the you have successfully setup CVS. In case something was wrong and you followed the instructions, please take a look at SourceForge docs.

REPOSITORY

TRex has its own files repository for program storage: the CVS tree.
It's main use is intended for developers, and to work with it you must make a few things.

Creating your own copy

Change to a new directory and type the following, making necessary obvious substitutions for your loginname.

cvs -dloginname@trex.cvs.sourceforge.net:/cvsroot/trex checkout machinery

After this command is issued the "machinery" tree will be download to your machine.

Make your homework

Once in this stage you can make any changes to the files (bug solving, feature addition, etc.) and these are made locally, with danger of any deletion or modification was made to the files in the original repository.

Comunicate your changes

After you have made modifications, and tested them, you'll be anxious enough that other people test your code. Then at the command prompt, inside the directory where the checkout command was issued, type:

cvs commit -m "comments for this commit"

... and after you enter your password your changes will be sent, and merged, into the CVS tree. You made history !!

Update your local copy

Obviously some people can make the same commands at the same time, so you'll be missing the changes amde by other developers. To update your files with modifications from other developers type:

cvs update

DOCUMENTATION

For further documentation on the topics used in this text, please visit:

TRex SETUP

You only have setup the development components (CVS and SSH), now you'll install the client side to test bug fixes, enhancements, and so on.

First take a look at the requirements for using TRex and install the corresponding software. Please, pay attention to the Perl module dependencies (some modules depend on other modules to work properly).

Once all is installed some tunning must be made. For the next paragraphs will be taken that your TRex working directory (you local copy of TRex obtained via CVS) is located inside /home/user/TRex.

Note to Windows dudes: In any place were is stated that you must point one directory to another, you will copy the files UNLESS you're using the an NTFS that supports file system linking. To explore a bit more about it take a look at Sysinternals' Junction or SymLink

Perl

As a general rule you will work in your local copy, so its good that the directories for each setup will be pointed to you TRex local copy (in your working directory) instead of copying them each time they are modified.

Mainly you will have to make a new class available to Perl: the TRex class.
To do this simply serch for the directory 'site' or 'site_perl' at your Perl instalation directory and make, below it, a link to your lib directory:

ln -s /home/user/TRex/machinery/modules TRex

Doing this you will create a new Perl class called TRex, and inside it one class for each pm file and directory : TRex::Common, TRex::L10N, etc.

Web server

With the web server we will use the same methodology: pointing the web server URIs to the working directory.
So, you need to build the next ones :

The User's manual : /TRex/man to /home/user/TRex/machinery/docs/users
The CGI directory : /TRex/cgi-bin to /home/user/TRex/machinery/core
The media directory : /TRex/media to /home/user/TRex/machinery/ui/aMail

Apache

If you are using Apache HTTP server, just add the this file content (with the obvious path substitutions) to the httpd.conf file.

Internet Information Server

If you are using MS IIS, the process is not so straightforward. You must :

Create a new Virtual Directory called TRex pointing it to where you have checked out TRex CVS (e.g. C:\TRex\machinery), and allow only read access and add index.html as the default document
Create a new Virtual Directory called man (under TRex virtual directory) pointing it to C:\TRex\machinery\docs\user, and allow only read access
Create a new Virtual Directory called media (under TRex virtual directory) pointing it to C:\TRex\machinery\ui\aMail, and allow only read access
Create a new Virtual Directory called cgi-bin (under TRex virtual directory) pointing it to C:\TRex\machinery\core, and allow execution access
Add the -T switch to the .pl script asociation, under IIS, to allow Perl scripts to run in tainted mode.

Logging

Logging configuration is done by :

pointing the $logConfigFile scalar (see Directories sections) to the config file (/etc/TRex/log4perl.conf)
copying the config directory to the location specified by the previous scalar
generating the directory to allow the logging system to write the logs (/var/log/TRex)

Directories

Once this has be done is time to setup the TRex directories.

Open Common.pm inside modules directory and change the next settings:

$dir_URL = "http://$localhost/TRex/cgi-bin"
$db_path = "/home/user/TRex/initialize_user"
$img_URL = "http://$localhost/TRex/media/images"
$man_URL = "http://$localhost/TRex/man"
$skin_URL = "http://$localhost/TRex/media/skins"
$logConfigFile = "/etc/TRex/log4perl.conf"

Additionally, the parameters for skin (only SourceForge is available) and language (only english and Spanish supported at this time) must be set:

$skin = "SourceForge"
$lang = 'en'

Once all of this is ended open your browser and point it to http://127.0.0.1/cgi-bin/amail/login.pl, where the login screen should appear.
Then go to the link named click here to get a new TRex account, create yourself one and ... enjoy TRex: a lot of fun in a bunch of Perl scripts !!!!