1998-10-07 23:29:26 +04:00
|
|
|
So you want to run Bonsai? It's better that you know how Bonsai works
|
|
|
|
since your obviously going to be hacking around in the code to change
|
|
|
|
it to your individual site configuration.
|
|
|
|
|
|
|
|
o What Bonsai can do for you:
|
|
|
|
|
|
|
|
Bonsai allows you to query the contents of your CVS tree, figuring out
|
|
|
|
the differences between arbitrary versions and/or branches of a file
|
|
|
|
and allows you to watch those changes over time.
|
|
|
|
|
|
|
|
One of the problems with CVS is that although it allows you to define
|
|
|
|
logical groups of directories into a module, it has no way to define a
|
|
|
|
module that represents a specific branch within one or more of those
|
|
|
|
directories. Bonsai allows you to define a module that represents
|
|
|
|
both a directory and a branch within that directory in your CVS
|
|
|
|
repository.
|
|
|
|
|
|
|
|
Bonsai is tree control.
|
|
|
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
o How does it work?
|
|
|
|
|
|
|
|
To do all this, Bonsai requires access to the source of your CVS
|
|
|
|
repository. This means that it will actually read the source files in
|
|
|
|
their ,v format. It is not enough that you have access to a checked
|
|
|
|
out copy of an arbitrary CVS tree. Bonsai also reads the modules that
|
|
|
|
you have defined in the modules file in the CVSROOT directory of your
|
|
|
|
CVS repository. The logical mappings that you set up in that file
|
|
|
|
define the base Bonsai modules that Bonsai will use to set up your
|
|
|
|
queries.
|
|
|
|
|
|
|
|
In order to keep track of these changes in a format that is easily
|
|
|
|
queried Bonsai also requires access to a relational database, in this
|
|
|
|
case MySQL. Once your CVS tree is in place and Bonsai has been
|
|
|
|
installed, you will import the important data from your CVS repository
|
|
|
|
into the Bonsai database. This doesn't import the entire repository
|
|
|
|
verbatim, it only reads and stores the information that it needs
|
|
|
|
including information about users, dates, file names, versions and
|
|
|
|
branch information.
|
|
|
|
|
|
|
|
To keep track of changes over time, Bonsai also requires notification
|
|
|
|
through some kind of asynchronous method to know that you have updated
|
|
|
|
a file. It keeps track of these changes through email. In CVS
|
|
|
|
every time that you make a check-in, any scripts that are defined in the
|
|
|
|
loginfo file in the CVSROOT directory of your CVS repository will be
|
|
|
|
run and the information about that check-in will be passed to that
|
|
|
|
script. Bonsai requires that you add a script to that file that will
|
|
|
|
automatically generate a specially formatted email. That email will
|
|
|
|
then be sent to a special account and, in turn, a script. That script
|
|
|
|
will then parse the email and update the Bonsai database with the
|
|
|
|
check-in information.
|
|
|
|
|
|
|
|
This method, while seemingly roundabout, provides a few advantages.
|
|
|
|
It keeps you from constantly polling your CVS tree to check for
|
|
|
|
changes. This can be a very intensive operation on large
|
|
|
|
repositories. This method is pretty reliable. Mail messages are
|
|
|
|
rarely lost on systems.
|
|
|
|
|
|
|
|
Bonsai requires that it always have read access to the CVS repository.
|
|
|
|
It does not ever need to write to the repository so this means you can
|
|
|
|
use a read-only nfs setup or some other mirroring strategy.
|
|
|
|
|
|
|
|
The last part of Bonsai is the web based interface. This interface is
|
|
|
|
where you do most of the day-to-day administration and querying. The
|
|
|
|
interface uses the backend database and the configuration files that
|
|
|
|
you set up.
|
|
|
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
o How do I set up my administration password?
|
|
|
|
|
|
|
|
When you build bonsai, the program "trapdoor" is built and installed
|
|
|
|
into the data directory in your Bonsai installation tree. Change to
|
|
|
|
the data directory in your installation and run the command:
|
|
|
|
|
|
|
|
trapdoor <your admin password> > passwd
|
|
|
|
|
|
|
|
If you look at the file you will see your admin password in standard
|
|
|
|
unix crypt() format.
|
|
|
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
o Ok, I've installed the files. What do I do now?
|
|
|
|
|
|
|
|
First, you need to define logical Bonsai modules on top of the modules
|
|
|
|
that you have already defined in CVS. Any CVS modules that you do not
|
|
|
|
define here will still show up in the Bonsai query interface.
|
|
|
|
However, defining Bonsai modules allows you access to the most
|
|
|
|
commonly used modules and allows you fast access to the branches of a
|
|
|
|
particular module. Also, to import a directory from CVS into Bonsai
|
|
|
|
it must be included as part of one of the Bonsai modules.
|
|
|
|
|
|
|
|
To set up the Bonsai modules you need to edit the configdata script in
|
|
|
|
the data/ directory of your Bonsai installation. The first part of
|
|
|
|
this file contains a list of the Bonsai modules that you want to
|
|
|
|
define and looks something like this:
|
|
|
|
|
|
|
|
set treelist {default module_a module_b module_c}
|
|
|
|
|
|
|
|
Please note the "default" module. You can define this module to be
|
|
|
|
any of the modules in your CVS tree. It is probably best that you
|
|
|
|
define it as your most used. It _must_ be defined.
|
|
|
|
|
|
|
|
For each of the Bonsai modules you need to define the information that
|
|
|
|
describes that module. For example, for you default module you can
|
|
|
|
define the following information:
|
|
|
|
|
|
|
|
set treeinfo(default,module) XYZSource
|
|
|
|
set treeinfo(default,branch) {}
|
|
|
|
set treeinfo(default,repository) {/cvsroot}
|
|
|
|
set treeinfo(default,description) {XYZ Sourcecode}
|
|
|
|
set treeinfo(default,shortdesc) {XYZ}
|
|
|
|
|
|
|
|
Each of the treeinfo settings describes the following things:
|
|
|
|
|
|
|
|
module: This is the logical module as defined in your modules file on
|
|
|
|
the CVS repository.
|
|
|
|
|
|
|
|
branch: This is the branch within that module. As above, you don't
|
|
|
|
have to have one of these defined. If you don't it's the same as the
|
|
|
|
HEAD branch.
|
|
|
|
|
|
|
|
repository: This is the directory that contains the repository.
|
|
|
|
|
|
|
|
description: This is the long description for the module, used
|
|
|
|
throughout the web interface.
|
|
|
|
|
|
|
|
shortdesc: This is a shorter version of the description.
|
|
|
|
|
|
|
|
Here is another example using a branch:
|
|
|
|
|
|
|
|
set treeinfo(module_a,module) ABCSource
|
|
|
|
set treeinfo(module_a,branch) {ACB_MERGE_1_0_BRANCH}
|
|
|
|
set treeinfo(module_a,repository) {/cvsroot}
|
|
|
|
set treeinfo(module_a,description) {ABC Sourcecode}
|
|
|
|
set treeinfo(module_a,shortdesc) {ABC}
|
|
|
|
|
|
|
|
Also in the configdata file you need to define the absolute paths to
|
|
|
|
some more commonly used commands and configuration information. These
|
|
|
|
are pretty self explanatory:
|
|
|
|
|
|
|
|
set cvscommand /usr/local/bin/cvs
|
|
|
|
set rlogcommand /usr/bin/rlog
|
|
|
|
set rcsdiffcommand /usr/bin/rcsdiff
|
|
|
|
set cocommand /usr/bin/co
|
|
|
|
set lxr_base http://www.abc.com/webtools/lxr/source
|
|
|
|
set mozilla_lxr_kludge TRUE
|
|
|
|
|
|
|
|
Once you have set up these configuration items you also need to make a
|
|
|
|
directory in your data directory that has the same name as each of the
|
|
|
|
modules above. For example, for the default module defined above you
|
|
|
|
would need to create a directory called "ABCSource".
|
|
|
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
o How do I import data?
|
|
|
|
|
|
|
|
You can do this from the administration menu in Bonsai. Go to the
|
|
|
|
toplevel of Bonsai and choose the module that you want to import by
|
|
|
|
using the pull down menu. Then click on the link near the bottom of
|
|
|
|
the page for administration. This will take you to the administration
|
|
|
|
page for that module. If this is the first time importing data, find
|
|
|
|
the section that has a button labeled "Rebuild CVS history". When you
|
|
|
|
fill in your administration password and click on the button, all of
|
|
|
|
the history information for that Bonsai module will be rebuilt.
|
|
|
|
|
|
|
|
You need to do this once for all of the modules that you have defined.
|
|
|
|
Unfortunately, there is no way to import an entire CVS tree from the
|
|
|
|
root.
|
|
|
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
o How do I set up mail for bonsai?
|
|
|
|
|
|
|
|
There are three things that you need to do to to set up email for
|
|
|
|
bonsai.
|
|
|
|
|
|
|
|
o You need to set up an account that will accept the email from Bonsai
|
|
|
|
and process it. When you have set up that user's .forward file to run
|
|
|
|
the script that handles the email. This is what a sample .forward
|
|
|
|
file looks like, please note that the script takes one argument which
|
|
|
|
is the directory where all of your bonsai data resides:
|
|
|
|
|
2004-04-27 10:15:25 +04:00
|
|
|
"|/home/httpd/html/webtools/bonsai/handleCheckinMail.pl /home/httpd/html/webtools/bonsai"
|
1998-10-07 23:29:26 +04:00
|
|
|
|
|
|
|
o You need to set up an alias for "bonsai-checkin-daemon" to the
|
|
|
|
account that will process the email. This is where the mail will be
|
|
|
|
sent to when checking into CVS. Also create an alias called
|
|
|
|
"bonsai-daemon" for error mail.
|
|
|
|
|
|
|
|
o You need to add the script that creates the email to the loginfo
|
|
|
|
file in CVS. To do this you can add a line to the loginfo file that
|
|
|
|
looks like this:
|
|
|
|
|
|
|
|
# For bonsai
|
|
|
|
ALL /home/httpd/html/webtools/bonsai/dolog.pl -r /usr/local/cvsroot bonsai-checkin-daemon@your-bonsai-host.your-company.com
|
|
|
|
#
|
|
|
|
|
|
|
|
This will generate a piece of email every time someone checks in code
|
|
|
|
and should be handled with the setup above.
|