mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-09 11:25:00 +00:00
Artem Belevich <abelevic@ctron.com> has provided absolutely wonderful
installation instructions.
This commit is contained in:
terry
parent
144490cba0
commit
6bea1154f1
440
webtools/bonsai/INSTALL
Normal file
440
webtools/bonsai/INSTALL
Normal file
@ -0,0 +1,440 @@
|
||||
# -*- mode: indented-text -*-
|
||||
#
|
||||
# Author: Artem Belevich <abelevic@ctron.com>
|
||||
#
|
||||
#
|
||||
|
||||
**********************************************************************
|
||||
|
||||
As it's said in README "This is not very well packaged code. It's
|
||||
not packaged at all. Don't come here expecting something you plop in
|
||||
a directory, twiddle a few things, and you're off and using it. Much
|
||||
work has to be done to get there."
|
||||
|
||||
This file is intended to make some things *easier* but not easy. You
|
||||
are still required to make some changes on your own. There is no
|
||||
guaranteed solution yet and it's unlikely that there will be one in
|
||||
the nearest future.
|
||||
|
||||
**********************************************************************
|
||||
|
||||
|
||||
0. OVERVIEW
|
||||
|
||||
Some time ago I've seen Linux Source Navigator (LSN) at
|
||||
http://sunsite.unc.edu/linux-source. I was impressed.
|
||||
It was and is a wanderful tool to explore Linux kernel source code.
|
||||
|
||||
Then Mozilla.org came up with a more elaborate tool that includes
|
||||
source browser with crossreferencing (LXR http://lxr.linux.no) and CVS
|
||||
tree control (Bonsai - http://www.mozilla.org/bonsai.html).
|
||||
While LXR formatting is not as pretty as LSN's one, it has a huge
|
||||
advantage - it lets you see where the identifier is defined and used.
|
||||
And Bonsai brings nice and easy (though sometimes incompatible with
|
||||
browsers other but Netscape's own) intarface to the CVS history. This
|
||||
includes getting list of changes, giffs between revisions, etc.
|
||||
|
||||
All in all LXR+Bonsai+other stuff beneath is a useful tool capable
|
||||
of handling huge projects.
|
||||
|
||||
It's not that easy to make it work with other source tree but
|
||||
Mozilla's own but it's possible. And there are a lot of things to
|
||||
improve. Now I'm going to concentrate on the first goal - to make it
|
||||
work.
|
||||
|
||||
|
||||
1. GETTING IT UP
|
||||
|
||||
First of all you have to get all the tools in mozilla's
|
||||
mozilla/webtools CVS repository. This includes lxr,bonsai,registry
|
||||
and tinderbox. You're likely will not need neither tinderbox nor
|
||||
registry but get them just in case.
|
||||
|
||||
To get the sources you have to follow instructions on
|
||||
http://www.mozilla.org/bonsai.html.
|
||||
|
||||
OK, now you've got the sources but don't rush to try it right
|
||||
away. It's likely that you will not be able to even start most of
|
||||
the scripts. There are more things you will have to get and install.
|
||||
The short list of the things you will need:
|
||||
|
||||
1) MySQL database server.
|
||||
2) Tcl 7.6
|
||||
3) TclX 7.6
|
||||
4) mysqltcl program (hmm.. This was tricky.. Read on)
|
||||
5) Perl 5.004+ with Mysql module (included with MySQL).
|
||||
6) Date::Parse module for Perl
|
||||
7) Some kind of HTTP server so you could use CGI scripts
|
||||
|
||||
1.1 Getting and setting up MySQL database
|
||||
|
||||
Visit MySQL homepage at http://www.tcx.se and grab the latest
|
||||
stable binary release of the server. Sure, you can get sources and
|
||||
compile them yourself, but binaries are the easiest and the fastest
|
||||
way to get it up and running. Follow instructions found in
|
||||
manual. There is a section about installing binary-only
|
||||
distributions.
|
||||
|
||||
You should create database bonsai. It may be a good idea to make it
|
||||
writable by all users on your machine and change access level
|
||||
later. This would save you a lot of time trying to guess whether it's
|
||||
permissions or a mistake in the script that make things fail.
|
||||
|
||||
1.2-3 Getting and building Tcl & TclX 7.6
|
||||
|
||||
Tcl homepage is at http://www.scriptics.com. You may get sources
|
||||
for UNIX from ftp://ftp.scriptics.com/pub/tcl/tcl7_6/tcl7.6p2.tar.gz.
|
||||
TclX is an extension for Tcl that adds a lot of useful functions that
|
||||
are heavily used in Bonsai tool.
|
||||
TclX page is http://www.neosoft.com/tclx. Download sources from
|
||||
ftp://ftp.neosoft.com/pub/tcl/TclX/tclX7.6.0.tar.gz. Watch out for the
|
||||
case of the letters in URL. These guys are going to bring some fun
|
||||
into your life by spelling their program name in various ways.
|
||||
|
||||
Now you've probably got both Tcl and TclX 7.6. You may try to use
|
||||
version 8.X but I'm not sure about results. Unfortunately I'm not an
|
||||
expert in "Tcl&Co.".
|
||||
|
||||
Build and install Tcl first. Then build and install TclX. This
|
||||
should go without serious problems
|
||||
|
||||
1.4 mysqltcl - the tricky part
|
||||
|
||||
Grab msqltcl 1.50 (yes, "msqltcl" without 'y'. That's not a typo) from
|
||||
MySQL site's contributed software area (http://www.tcx.se/Contrib/) or
|
||||
from mSQL site (www.hughes.com.au). I've used version 1.50 and it
|
||||
works for me, though you may try more recent version at your own
|
||||
risk. You're risking anyway.
|
||||
|
||||
Then grab mysqltcl.c-patch from MySQL's contrib area and apply this
|
||||
patch to msqltcl.c file from msqltcl-1.50 distribution.
|
||||
|
||||
Try to make msqltcl binary which is in fact mYsqltcl already. Very
|
||||
likely that you will not be able to compile it without modifications.
|
||||
|
||||
You can use the patch in APPENDIX 1 to see what changes I had to make
|
||||
to compile mysqltcl. Your mileage may vary.
|
||||
|
||||
1.5 Perl + Mysql
|
||||
|
||||
Besides mysqltcl you will need Perl 5.004 with DB and Mysql
|
||||
extensions.
|
||||
|
||||
DB is required to use LXR browser and crossreferencer for storing
|
||||
its database. Mysql is used by Bonsai.
|
||||
|
||||
If you have Perl already installed, try to run genxref program from
|
||||
LXR suite. If it complains that it misses DB terribly then you're
|
||||
probably will have to get and install DB 1.86 distribution from one of the
|
||||
CPAN (www.cpan.org) mirrors in src/misc directory. I personally got it
|
||||
from http://www.cpan.org/src/misc/db.1.86.tar.gz. Having DB compiled
|
||||
and installed you will also have to rebuild and reinstall Perl
|
||||
itself so It would recognize and compile DB module in. This can be
|
||||
tricky if you have DB installed in some strange place as I did.
|
||||
I've got an error during linking phase - there was a function missing
|
||||
in hash/ndbm.c file, so I just commented it out. It may potentially
|
||||
cause troubles, but I think it does not matter in our case as this
|
||||
was intended only for DBM compatibility - the feature we don't really
|
||||
use.
|
||||
|
||||
Now you hopefully have Perl + DB compiled installed and working.
|
||||
Time to set up Mysql module. This one is easy. Just follow
|
||||
instructions in MySQL manual. You have to read manuals sometimes..
|
||||
I think I'm getting older.. 8-)
|
||||
|
||||
Next step is to get TimeDate module from one of the CPAN mirrors.
|
||||
Go to CPAN search page
|
||||
(http://theory.uwinnipeg.ca/search/cpan-search.html) and search for
|
||||
the "TimeDate" module. Then get it and install.
|
||||
|
||||
1.6 HTTP server
|
||||
|
||||
You have a freedom of choice here - Apache, Netscape or any other
|
||||
server on UNIX would do. The only thing - to make configuration easier
|
||||
you'd better run HTTP daemon on the same machine that you run MySQL
|
||||
server on. Make sure that you can access 'bonsai' database with user
|
||||
id you're running the daemon with.
|
||||
|
||||
|
||||
2. TWEAKING THE TOOLS
|
||||
|
||||
Now you should have all necessary tools to be able to run LXR and
|
||||
Bonsai scripts and see why the wouldn't work for you right now.
|
||||
|
||||
First of all you have to change "#!/usr/bonsaitools" to wherever
|
||||
you've installed your binaries in all executable scripts in LXR and
|
||||
Bonsai directories.
|
||||
|
||||
|
||||
2.1 LXR
|
||||
|
||||
The first thing to set up is LXR tool. All it needs is the source
|
||||
tree (not CVS tree). It's relatively easy and works almost right of
|
||||
the box. Follow instructions in LXR README file.
|
||||
|
||||
Having set LXR you will see that regardless what your source tree
|
||||
contains you will see that everything refers to it as Mozilla. Mozilla
|
||||
is a great thing and this tool was primarily tailored to mozilla tree
|
||||
but you'd like to control your own tree. First step is to edit your
|
||||
|
||||
Here is the short list of changes I had to make
|
||||
|
||||
file: ident
|
||||
1) change "&root=/cvsroot" to tour CVSROOT path
|
||||
2) change "file=/mozilla/" to the directory under CVSROOT where
|
||||
your sources are. In my case it is just "/"
|
||||
|
||||
file: index.html
|
||||
Nothing vital here but probably worth changing to reflect your own
|
||||
environment
|
||||
|
||||
file: lxr.conf
|
||||
Changes to this file are described in LXR README file and are
|
||||
quite simple.
|
||||
|
||||
file: source
|
||||
You may find it useful to uncomment "$img = "/icons/..." lines if
|
||||
you yse Explorer as it does not have internal-gopher-* images
|
||||
built in. Actually Bonsai contains a lot of netscapism that will
|
||||
make your IE4 unhappy anyway. You'd better stick with Netscape if
|
||||
you are going to use LXR/Bonsai
|
||||
|
||||
file: template-*
|
||||
Here you will probably want to watch closely at the places whare
|
||||
you see the word 'mozilla' near '.cgi'. There are a lot of
|
||||
mozilla-specific paths hardcoded
|
||||
|
||||
cgange/get rid of banner that loads straight from mozilla.org that
|
||||
may be very dangerous if you're working for micro$oft and your
|
||||
boss comes by.. 8-)
|
||||
|
||||
2.2 Bonsai
|
||||
|
||||
This stuff sometimes gets very specific about your CVS repository
|
||||
setup. You have to make a lot of changes until more portable
|
||||
configuration mechanism is introduced.
|
||||
|
||||
First of all, create data/ directory in your Bonsai dir. Then edit
|
||||
data/configuration file as described in README file. Create
|
||||
appropriate data/XXX directory for each tree XXX you've configured in
|
||||
'configuration'. Compile trapdoor program and place binary in data/
|
||||
dir. run 'trapdoor <admin password here> >data/passwd' it will set up
|
||||
admin's password. At least it should. It worked for me with empty
|
||||
password, but I still am unable to change it from the web.
|
||||
|
||||
file: createlegaldirs.tcl
|
||||
change /tools/ns/bin/cvs to real path to your cvs command
|
||||
|
||||
file: cvsblame.cgi
|
||||
@line 120: you may add your own translation to help find
|
||||
appropriate RCS file for the given source file.
|
||||
TODO: We'd better get this information from CVS/Repository
|
||||
file. It's more generic than hardcoded tweaks.
|
||||
|
||||
file: cvslog.cgi
|
||||
@line 90: the same tweaks to find RCS file for given source file
|
||||
@ line 463: change $lxr_base from mozilla site to your own
|
||||
add translations to $lxr_path to help find source
|
||||
file for given RCS file.
|
||||
TODO: This should be done using information in
|
||||
$CVSROOT/CVSROOT/modules file. Typical example is the
|
||||
following line: 'mymodule -d mydir repositorydir' which
|
||||
causes files for module mymodule from repositorydir to be
|
||||
placed in mydir. This contains enough information about
|
||||
backward translation mydir/file->repositorydir/file,v
|
||||
|
||||
|
||||
file: cvsquery.cgi
|
||||
@line 23: There are some cases when cvsrot is not passed as
|
||||
parameter for cvsquery.cgi. You should better check for
|
||||
empty CVS_ROOT and set it to your CVSROOT path.
|
||||
|
||||
@line 71: Here we should try to make backward translation for
|
||||
directory name similar to one @line 463 in cvslog.cgi.
|
||||
|
||||
|
||||
@line 151: you will probably want to send email somewhere else
|
||||
but people @netscape.com 8-)
|
||||
|
||||
|
||||
file: cvsview2.cgi
|
||||
@line 393: set $rcsdiff to your real rcsdiff program
|
||||
@line 469&658: set $lxr_base appropriately
|
||||
@line 783: change path to "co" command
|
||||
|
||||
file: dolog.pl
|
||||
@line 177: change path to rlog program
|
||||
|
||||
file: multidiff.pl
|
||||
@line 72: change path to rcsdiff program
|
||||
|
||||
file: rebuildcvshistory.cgi
|
||||
@line 59: change path to rlog program
|
||||
@line 211: change path to cvs program
|
||||
|
||||
file: rebuildtaginfo.cgi
|
||||
@line 42: change path to rlog program
|
||||
|
||||
file: toplevel.cgi
|
||||
@line 240: remove links that are not accessible to you anyway
|
||||
|
||||
|
||||
That's basically it. With some luck and persistence you will have 90%
|
||||
working system at this point. A lot of these things are just asking to be
|
||||
fixed in near feature. And I hope they will be.
|
||||
|
||||
3. Setting up database
|
||||
|
||||
This is quite simple but time consuming operation.
|
||||
First create database structure using maketable.sh csript.
|
||||
Then go to Bonsai administration page and press "Rebuild CVS history"
|
||||
button. Then you may go to the theater and watch a movie or two. It
|
||||
will talke a lot of time. It takes several seconds to process one
|
||||
file. The more revisions in file the more time it will take. My SUN
|
||||
workstation with 2x200Mhz UltraSPARC processors run about an hour to
|
||||
process about 4K files with 20K+ revisions. Your mileage may vary.
|
||||
|
||||
4. Things to do
|
||||
|
||||
a) There should be better way to track CVS tree changes. Now it's done
|
||||
by making CVS send e-mail about each checkin. Then some cron job
|
||||
process this mail and updates database. CVS history command provides
|
||||
all necessary information to get list of files recently commited, so
|
||||
there is no need to send/process email. Just set up a cron job that
|
||||
will periodically look for CVS tree changes and update database.
|
||||
|
||||
b) Better configuration. One should not hardcode CVS tree <-> Source
|
||||
tree translations. Also location of CVS/RCS binaries should be
|
||||
configurable. Another thing to configure - banners.
|
||||
|
||||
c) LXR could be improved in a number of ways. Using MySQL database
|
||||
instead of DB would probably be a good idea. It's unclear what impact
|
||||
it will have on performance though. Incremental database updates would
|
||||
be nice. It might be also nice to borrow syntax highliting from LSN.
|
||||
|
||||
|
||||
5. Conclusion.
|
||||
|
||||
OK. This may or may not work for you. But I hope you had a great
|
||||
time trying. Or just reading.
|
||||
|
||||
Any suggestions/additions are welcome.
|
||||
|
||||
|
||||
*******************************************************
|
||||
APPENDIXES
|
||||
*******************************************************
|
||||
|
||||
|
||||
APPENDIX 1. Patch to build mysqltcl.
|
||||
--------------------------------------
|
||||
|
||||
diff -u -r msqltcl-1.50/Makefile mysqltcl-1.50/Makefile
|
||||
--- msqltcl-1.50/Makefile Tue Jun 6 07:25:39 1995
|
||||
+++ mysqltcl-1.50/Makefile Tue Jun 23 18:20:07 1998
|
||||
@@ -38,11 +38,11 @@
|
||||
#
|
||||
#----- Tcl/Tk libraries & such
|
||||
# Path for Tcl include files.
|
||||
-TCLINCL = -I/usr/local/include
|
||||
+TCLINCL = -I../include
|
||||
# Path for Tk include files, if different from the above.
|
||||
TKINCL =
|
||||
# Libraries required to link plain Tcl.
|
||||
-TCLLIBS = -L/usr/local/lib -ltcl -lm
|
||||
+TCLLIBS = -L../lib -ltclx7.6.0 -ltcl7.6 -lm -lnsl -lsocket
|
||||
# Libraries required to link plain Tk.
|
||||
TKLIBS = -L/usr/local/lib -ltk -ltcl -lX11 -lm
|
||||
|
||||
@@ -66,11 +66,11 @@
|
||||
#
|
||||
#----- Tcl/Tk libraries & such
|
||||
# Path for Tcl include files.
|
||||
-NEWTCLINCL = -I/usr/local/new/include
|
||||
+NEWTCLINCL = -I../include
|
||||
# Path for Tk include files, if different from the above.
|
||||
NEWTKINCL =
|
||||
# Libraries required to link plain Tcl.
|
||||
-NEWTCLLIBS = -L/usr/local/new/lib -ltcl -lm
|
||||
+NEWTCLLIBS = -L../lib -ltclx7.6.0 -ltcl7.6 -lm -lnsl -lsocket
|
||||
# Libraries required to link plain Tk.
|
||||
NEWTKLIBS = -L/usr/local/new/lib -ltk -ltcl -lX11 -lm
|
||||
|
||||
@@ -82,7 +82,7 @@
|
||||
# Path for TclX/TkX include files, if different from plain Tcl.
|
||||
NEWTCLXINCL =
|
||||
# Extra libraries required to link TclX.
|
||||
-NEWTCLXLIBS = -L/usr/local/new/lib -ltclx
|
||||
+NEWTCLXLIBS = -L../mysql/lib -ltclx
|
||||
# Extra libraries required to link TkX.
|
||||
NEWTKXLIBS = -L/usr/local/new/lib -ltkx -ltclx
|
||||
# TclX/TkX 'AppInit' files (base names).
|
||||
@@ -94,16 +94,16 @@
|
||||
#
|
||||
#----- mSQL libraries & such
|
||||
# Path for mSQL include files.
|
||||
-MSQLINCL = -I/usr/local2/src/Minerva/include
|
||||
+MSQLINCL = -I../mysql/include
|
||||
# Libraries required to link an mSQL application.
|
||||
-MSQLLIB = -L/usr/local2/src/Minerva/lib -lmsql
|
||||
+MSQLLIB = -L../mysql/lib -lmysqlclient
|
||||
|
||||
#===== END OF CONFIGURATION DEFINITIONS =====
|
||||
|
||||
INCL = -I. ${MSQLINCL} ${TCLINCL} ${TKINCL}
|
||||
CFLAGS = ${OPTIM} -c
|
||||
LDFLAGS = ${OPTIM}
|
||||
-PROGS = msqltcl msqlwish
|
||||
+PROGS = msqltcl # msqlwish
|
||||
TCLLINK = ${MSQLLIB} ${TCLLIBS}
|
||||
TKLINK = ${MSQLLIB} ${TKLIBS}
|
||||
|
||||
diff -u -r msqltcl-1.50/new-tclAppInit.c mysqltcl-1.50/new-tclAppInit.c
|
||||
--- msqltcl-1.50/new-tclAppInit.c Tue Jun 6 07:25:38 1995
|
||||
+++ mysqltcl-1.50/new-tclAppInit.c Tue Jun 23 18:28:14 1998
|
||||
@@ -14,7 +14,7 @@
|
||||
static char sccsid[] = "@(#) tclAppInit.c 1.11 94/12/17 16:14:03";
|
||||
#endif /* not lint */
|
||||
|
||||
-#include "tcl.h"
|
||||
+#include "tclExtend.h"
|
||||
|
||||
/*
|
||||
* The following variable is a special hack that is needed in order for
|
||||
@@ -48,7 +48,7 @@
|
||||
int argc; /* Number of command-line arguments. */
|
||||
char **argv; /* Values of command-line arguments. */
|
||||
{
|
||||
- Tcl_Main(argc, argv);
|
||||
+ TclX_Main(argc, argv, Tcl_AppInit);
|
||||
return 0; /* Needed only to prevent compiler warning. */
|
||||
}
|
||||
|
||||
@@ -79,6 +79,10 @@
|
||||
return TCL_ERROR;
|
||||
}
|
||||
|
||||
+ if (Tclx_Init(interp) == TCL_ERROR) {
|
||||
+ return TCL_ERROR;
|
||||
+ }
|
||||
+
|
||||
/*
|
||||
* Call the init procedures for included packages. Each call should
|
||||
* look like this:
|
||||
@@ -90,7 +94,7 @@
|
||||
* where "Mod" is the name of the module.
|
||||
*/
|
||||
|
||||
- if (Msqltcl_Init(interp) == TCL_ERROR) {
|
||||
+ if (Mysqltcl_Init(interp) == TCL_ERROR) {
|
||||
return TCL_ERROR;
|
||||
}
|
||||
|
||||
@@ -106,6 +110,6 @@
|
||||
* then no user-specific startup file will be run under any conditions.
|
||||
*/
|
||||
|
||||
- tcl_RcFileName = "~/.tclshrc";
|
||||
+/* tcl_RcFileName = "~/.tclshrc"; */
|
||||
return TCL_OK;
|
||||
}
|
||||
@ -14,6 +14,11 @@ and so we decided to let people see it first.
|
||||
Don't believe for a minute that you can use this stuff without first
|
||||
understanding most of the code.
|
||||
|
||||
Check out the INSTALL file for some guidance on getting started.
|
||||
Many, many thanks to Artem Belevich <abelevic@ctron.com> for
|
||||
trailblazing his way through this and writing down all the problems he
|
||||
had.
|
||||
|
||||
|
||||
============================
|
||||
Configuration files you need
|
||||
|
||||
Loading…
Reference in New Issue
Block a user