aMail 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

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 http://www.gnu.org/software/cvs/cvs.html 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):

bit-man@home# cvs -n -dyour_username@cvs.amail.sourceforge.net:/cvsroot/amail checkout v2.1
your_username@cvs.amail.sourceforge.net's password: <type_your_pass_here>
cvs server: in directory v2.1:
cvs [server aborted]: there is no version here; run 'cvs checkout' first
t:/cvsroot/amail 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

aMail 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@cvs.amail.sourceforge.net:/cvsroot/amail checkout v2.1

After this command is issued the v2.1 tree will be download to your machine: you have the latest files for aMail v2.1 in 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.

Communicate 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 have make 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:

aMail 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 aMail 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 aMail working directory (you local copy of aMail obtained via CVS) is located inside /home/user/aMail.

Note to Windows developers: 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.

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 aMail 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 aMail 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 -sf /home/user/aMail/program/lib aMail

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

Web server

With the web server we will use the same methodology: pointing to the working directory. Now we suppose that your web server html files root is /home/www/htdocs and your cgi-bin is /home/www/cgi-bin

Now we need to point:

The User's manual (/home/www/htdocs/aMail/man) to /home/user/aMail/doc
The aMail cgi directory (/home/www/cgi-bin/aMail) to /home/user/aMail/program
The aMail media directory (/home/www/htdocs/aMail/media) to /home/user/aMail

Directories

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

Open Common.pm inside program/lib and change the next settings:

$dir_URL = "http://127.0.0.1/cgi-bin/aMail"
$db_path = "/home/user/aMail/initialize_user"
$img_URL = "http://127.0.0.1/aMail/media/images"
$man_URL = "http://127.0.0.1/aMail/man"
$skin_URL = "http://127.0.0.1/aMail/media/skins"

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 aMail account, create yourself one and ... enjoy aMail: a lot of fun in a bunch of Perl scripts !!!!