[RFC] : small doc for beginner wanting to test Balsa from CVS

[Emmanuel <e allaud wanadoo fr>]

	Hi all,
to increase our tester base here is an small doc that should allow 
beginners to upload CVS versions, compile it and test it. Please review 
(I'm not a CVS guru) and give me your comments. I think this could be 
uploaded to the FAQ on the website when ready.

The following is clearly lacking : tell what distros are known to be OK to 
compile balsa CVS. This should reduce the number of problems of trivial 
lib dependancies.
There are a few FIXME in the text body, where I'm not sure what to put.

********* The doc ************

First VERY IMPORTANT remark :
If you want to be sure that your important mails won't get corrupted you 
can begin the process by creating a special user for the testing purpose. 
I would recommend that, especially for CVS versions that tend to be 
unstable.
If you do that all the description I give below is to be done using this 
new user account.

Uploading the sources from CVS :

First let's prepare the ground for cvs, issuing the following commands :

mkdir the_name_of_the_directory_where_cvs_will_be_put
cd the_name_of_the_directory_where_cvs_will_be_put
echo ":pserver:anonymous@anoncvs.gnome.org:/cvs/gnome A" > ~/.cvspass
cvs -z3 checkout -r HEAD balsa

To issue the last command you must be connected to the net, this command 
will build the cvs tree in the newly created directory. To be complete, 
the previous command just tell where is the cvs server (it's a gnome 
project server) and to connect as anonymous.
But as you know CVS evolve pretty fast, so to keep in sync, just go into 
the cvs directory you set up and issue the following command (you have to 
be on the net obviously) :

cvs update

this will issue a lot of messages to tell you which files have been 
updated. You can also have error messages. I have only seen 2 of these : 
"unknown host..." (this was caused by a problem with my connection to the 
net, so if your connection is OK you should not see that one) and also 
"cvs [update aborted]: connect to anoncvs.gnome.org:2401 failed: No route 
to host" this one I don't know exactly why but I assume it's when the cvs 
server is saturated, so just differ your update to a less commom hour of 
the day.

OK now that you can retrieve the source let's compile them.

Compiling the sources :

It's a classical "./configure, make, make install thing". Here are the 
commands to issue step by step, with small explanations.

First you "configure" the sources, ie a script will take care of adapting 
the sources to your environnment (eg set up variable to contain the paths 
to libs on your computer...), and see if it meets balsa requirement 
(almost only libs dependancies). This is done by the following command 
issue in the balsa directory (ie the subdirectory named "balsa" in the 
directory you created for cvs in the previous section).

./autogen --enable-all

Yes this is not ./configure, but it calls it so no big difference, but the 
fact that it does a bit more things than configure (and in the end it 
calls it anyway).
This will issue a lot of messages to tell you what it is doing (and to 
keep you awake during the rather long process). On success it ends up with 
a summary of the options look at it to know if it has all what you want 
(eg if you want printing support, look if it has been enabled, we'll see 
later what to do if not).
You see that I put a command line option "--enable-all". There are a bunch 
of these, this one particularly tells to build balsa with all experimental 
parts (for example filters won't be compiled in if you don't use this 
option). You can list all options with a short description by

./configure --help

This will give you a lot of Normally this process should succeed, but if 
it fails look at the error messages they should tell you what are the 
problems. Here is a (live) example (yes I can't build cvs because my 
distro is way outdated, and I have a sloooow and expensive dialup 
connection :( ) :

checking whether to Gnome-VFS is available... configure: error: 
Gnome-VFS(-devel) library is needed to build balsa

It tells you (and me) that we lack Gnome-VFS-devel library. So correct 
that (if you can) and retry untill you have no more error messages. You 
also have the file "config.log" that tells you a bit more on the reasons 
of the errors. If the problems persist (and you feel you have tried all 
the thing you could) descibe your problem on the balsa mailing-list to 
have some help. But be prepared to be a bit shaked if you haven't tried 
hard enough to handle your problem ;-)

OK now your sources are configured, let's compile them. Still in the same 
balsa directory just issue the very simple command :

make

That will take care of compiling all sources that have changed (or that 
depend on changed files) since the last compile process. Yet another bunch 
of messages telling you what it is doing. Especially if a lot of files 
have been touched by your last update you can go take a coffee, this is a 
bit long (at least on my PII-266MHz). If all goes well (ie no error 
message) you have a working balsa. If you get compile error messages you 
can send them on the ml (try to see if they have yet been submitted), so 
that we can take care of these bugs.
Now either you install balsa (if you have set up a special test account 
you can do it safely /* FIXME : am I correct here ?!?! */) or just run it 
issuing the following command (always from the balsa directory)

src/balsa

This will run balsa, and you'll see a lot of debugging message scrolling 
in the console. This is actually useful because they can be used to track 
down a bug.
/* FIXME : specify more things to catch interesting debug messages when 
bug occur, like a stderr redir or something else ? */

If you want to install balssa (so that just typing "balsa" on the command 
line will run it, or just using you desktop links) issue the following 
command (you have to be root) :

make install

Happy testing !!