Bric::Hacker - A guide for Bricolage hackers.
$Revision: 1.21 $
$Date: 2002/08/18 23:50:24 $
This document is designed to provide information useful to Bricolage developers. If you've got questions about hacking Bricolage that aren't answered here please post to the Bricolage developer's mailing-list (see below) and tell us about it.
Bricolage has a number of mailing-lists that are relevant to developers:
This is the mailing-list for normal Bricolage users. This is a good place to go with questions about how the application works and should work. To subscribe go to:
http://lists.sourceforge.net/lists/listinfo/bricolage-general
This is the place to discuss Bricolage development, propose changes, post patches and penetrate markets. To subscribe go to:
http://lists.sourceforge.net/lists/listinfo/bricolage-devel
This list gets an email for every commit to the CVS tree (see below for more about CVS). DO NOT POST TO THIS LIST! To subscribe:
http://lists.sourceforge.net/lists/listinfo/bricolage-commits
This list gets an email for every bug-report submitted to Bugzilla (see below for Bugzilla details). DO NOT POST TO THIS LIST! To subscribe:
http://lists.sourceforge.net/lists/listinfo/bricolage-bugs
If you're developing Bricolage then you should be working with the latest code from CVS. You can browse the CVS tree at:
http://sourceforge.net/cvs/?group_id=34789You'll also find information there on connecting to the repository to checkout a working copy.
Bricolage has a Bugzilla server dedicated to it:
http://bricolage-bugzilla.about.comYou should use this system to report bugs in Bricolage. If you're looking for something to do you can also use the system to find open bug and fix them. For more things to do see Bric::ToDo.
Patches should be generated using a cvs diff -u command on each of the files modified, from the root directory. For example, if you made changes to lib/Bric/Changes.pod and comp/foo.mc, you would generate a diff by running this command from the root of your CVS checkout:
cvs diff -u lib/Bric/Changes.pod comp/foo.mc > patch.txtIf you created one or more new files in your changes then you'll have to add them to the patch separately using normal diff against /dev/null. For example, if you created the file inst/upgrade/1.9.1/solve_fermat.pl then you would add this to patch.txt with:
diff -u /dev/null inst/upgrade/1.9.1/solve_fermat.pl >> patch.txtAlways create patches using the most recent CVS version if possible. Send your patches to the bricolage-devel list mentioned above.
Patches created using the method above can be applied using patch with the -p0 option from the root of your CVS checkout:
patch -p0 < patch.txtMake sure you check the results with cvs diff before committing.
Try to follow the style of the existing Bricolage code.
Although historically the Bricolage code has not enforced whitespace rules, in general, we try to encourage 4-space indents (2 spaces for continued lines) and discourage the use of tabs. The following settings for some of the more popular editors are thus recommended while editing Bricolage source code.
We strongly recommend that you use cperl-mode while editing Bricolage sources in Emacs. Grab the latest version from the CPAN, install it, and then place the following in your ~/.emacs file:
(custom-set-variables
'(case-fold-search t)
'(cperl-indent-level 4)
'(cperl-continued-statement-offset 2)
'(cperl-tab-always-indent t)
'(indent-tabs-mode nil))Also, if you'd like to take advantage of the full functionality of cperl-mode and have it automatically parse all Perl source files, add these settings, as well:
(defalias 'perl-mode 'cperl-mode)
(setq auto-mode-alist
(append
'(("\\.\\([pP]\\([Llm]\\|erl\\)\\|al\\|pod\\)\\'" . cperl-mode))
auto-mode-alist))
(setq cperl-hairy t)
(setq interpreter-mode-alist (append interpreter-mode-alist
'(("miniperl" . cperl-mode))))When editing Bricolage Mason components, mmm-mode can help. It's Mason mode will parse Mason component files and use sgml-mode in HTML spaces and cperl-mode in Mason blocks. Grab it from http://mmm-mode.sourceforge.net/, install it, and then add the following to your ~/.emacs file to have it automatically parse your Bricolage Mason component files:
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp")
(require 'mmm-mode)
(require 'mmm-mason)
(setq mmm-global-mode 'maybe)
(add-to-list 'auto-mode-alist '("/usr/local/bricolage/comp" . sgml-mode))
(mmm-add-mode-ext-class 'sgml-mode "/usr/local/bricolage/comp" 'mason)And if you need to examine the Mason object files created by Bricolage in order to chase down bugs and such, you can use the cperl-mode in those files by adding this to your ~/.emacs file:
(add-to-list 'auto-mode-alist '("/usr/local/bricolage/data/obj" . cperl-mode))Rafael Garcia-Suarez has written a Vim indent macro which (for the most part) duplicates the behavior of Emacs perl-mode. It is now, as of Vim 6.0, included in the Vim distribution and should be found in $VIMRUNTIME/indent/perl. The easiest way to use it though is to place the following line in your .vimrc:
source $VIMRUNTIME/indent.vimYou'll also need to add these lines.
set tabstop=8
set softtabstop=4
set shiftwidth=4
set expandtabThe first three lines make Vim duplicate the behavior of Emacs in creating the appearance of 4 space tabs with a mix of tabs and spaces. This is necessary for reading older Bricolage files which were written this way, and haven't yet been re-tabbed.
The expandtab setting does the Right Thing under the new rules, in that it doesn't use tabs at all, only spaces.
Bricolage is a complex application and debugging can be difficult. Here are some tips to help you find bugs faster:
Turn on QA_MODE in your bricolage.conf. This will cause the UI to display a bunch of useful data at the bottom of every page including session state, cache state, cookies and CGI args. QA_MODE turns on PerlWarn (use warnings) and causes error messages to include more information. QA_MODE also enables Apache::Status at the URL /perl-status which you can use to examine the state of the Perl interpreter inside Apache.
Set the NO_TOOLBAR directive to "0" or "Off" in bricolage.conf to keep Bricolage from popping up a new browser window without a toolbar.
Run Bricolage under the Perl debugger using the debug command with bric_apachectl:
bric_apachectl debugThis will start Apache in single-process mode ("httpd -X") and setup Apache::DB to start the debugger on the each hit to the server. You'll need to install the Apache::DB Perl module to use this command.
To run Bricolage under DDD (http://www.gnu.org/software/ddd) start ddd as root and load bin/bric_apachectl. Give it the argument "debug" and run it. When you issue a hit to the server the debugger will stop on the first line of Bric::App::Handler::handler(). From there you can set breakpoints inside Bricolage and debug normally.
If you prefer to run without the debugger using only the Apache single-process mode, then run Bricolage using the command
bric_apachectl singleSet DBI_DEBUG and DBI_CALL_TRACE to 1 in your bricolage.conf. DBI_DEBUG records every database call in the logs complete with SQL and arguments. DBI_CALL_TRACE adds a a subroutine call trace for each statement showing where the database call originated. This generates a lot of data but it can be very helpful.
Look at the database directly using psql. Many bugs in Bricolage can only be successful diagnosed by examining records being created in the database.
Bricolage has two separate profiling systems that you can use to extract performance data:
To run Bricolage under the Devel::Profiler module set the PROFILE variable on in your bricolage.conf file and restart your server. This will create a profiler/$$/tmon.out file in your Apache log directory for each server process. You can use dprofpp to analyze these files after the server has been stopped with "bric_apachectl stop". See the Devel::Profiler documentation for more details.
The database profiler is activated by setting the DBI_PROFILE option on in bricolage.conf. This causes database profiling traces to be written to the Aapche error_log during requests. You can then use bric_dbprof to analyze these trace. See the bric_dbprof manpage for details.
CAUTION: Neither of these options is appropriate for a production system.
A relatively simple way to contribute to Bricolage is to provide actions and movers. These are plugin modules that can add new functionality to Bricolage without needing to make changes to the existing API.
An "action" is an act that is performed on files before they are distributed. Say you want to clean the HTML of all of your HTML files before they're distributed. You'll need to create an action to do this. Consult Bric::Dist::Action for information on how to create actions.
Say you need to distribute files via a protocol that Bricolage doesn't currently support -- say, an new variant of FTP called "FooTP." You'll need to create a new mover. Consult Bric::Dist::Action::Mover for details on how to do that.
Sam Tregar <stregar@about-inc.com>