	
		how to debug

------------------------------------------------------------
1	Overview

2	debug mode and debug level
2.1	Debug mode
2.2	Debug mode level 2 

3	How to debug
3.1	How to debug (1)
3.2	How to debug (2)
3.3	printf debug

4	Command Line Options
4.1	syntaxes of command line options
4.2	Long line option style --\S+=\S+
4.3	configuration files and command line options
4.4	simple mode setting option --\S+
4.5	--ctladdr 
------------------------------------------------------------


1	Overview

MLM (mailing list manager) is not a user command. Usually mail server
runs fml. To debug fml, you need to emulate this relation.

See  sectoin for typical errors.

See smtp 3.1 sectoin for SMTP log between fml and MTA.

Also see troubleshoot 1 section for error messages and trouble shooting.

2	debug mode and debug level

2.1	Debug mode

	$debug        = 1; (default 0)

In debug mode, fml.pl does not distribute (for test).

2.2	Debug mode level 2 

If $debug >= 2, fml writes debug info the file

	$DEBUG_LOGFILE (default "$DIR/log.debug")

3	How to debug

3.1	How to debug (1)

in fml-support: 5282
    1. check OS's maillog.
       following the check list in INSTALL file Appendix A.
    
    2. check fml log, $DIR/log.
    
    3. check the connection between fml and MTA, $DIR/var/log/_smtplog.
    
    4. "makefml test ML" helps you to test fml.
    
3.2	How to debug (2)

From: fml-support: 01411

* Printf debug is fundamental technique. FML has $debug variable. If
you know the details of processing, set $debug = 1, which helps your
debug. If $debug is 1, FML shows all debug information.

* perl -d enables perl debugger. See perl manual for how to use it.

Example:

	% ($FML/bin/emumail.pl; echo something )|perl -d $FML/fml.pl $PWD
	....debugger starts ...
	<1> t
	<2> c
	.... debug information flood! ....

* Which file is libraries for an object?
  A lib"NAME".pl library corresponds to functions on "NAME".
  e.g. libsmtp.pl is SMTP (Simple Mail Transfer Protocol) routines.

	SMTP		libsmtp.pl

	[Naming Convention Example]
	ra  = remote administration
	fop = file operation
	...

3.3	printf debug

    From: fukachan@phys.titech.ac.jp
    X-Mail-Count: 00702 
    
    For example, insert the following string.
    
    	print STDERR "REQ:GUIDE $Envelope{'req:guide'}";
    
    &InitConfig;			# initialize date etc..
    &Parsing;			# Phase 1(1st pass), pre-parsing here
    &GetFieldsFromHeader;		# Phase 2(2nd pass), extract headers
    
    	print STDERR "REQ:GUIDE $Envelope{'req:guide'}";
    &InitConfig;			# initialize date etc..
    	print STDERR "REQ:GUIDE $Envelope{'req:guide'}";
    &Parsing;			# Phase 1(1st pass), pre-parsing here
    	print STDERR "REQ:GUIDE $Envelope{'req:guide'}";
    &GetFieldsFromHeader;		# Phase 2(2nd pass), extract headers
    	print STDERR "REQ:GUIDE $Envelope{'req:guide'}";
    
    % perl sbin/localtest.pl |sed 's/test/#guide/' | perl fml.pl $PWD -d 
    
4	Command Line Options

"Command Line Options" here is that of fml.pl which is used in include
file such as

	"|/usr/libexec/fml/fml.pl $DIR $LIBDIR -option" 

Command line options enable you to debug fml.pl on your shell. For
unified maintenance you should configure $DIR/cf (for makefml) or
$DIR/config.ph (not use makefml) since "makefml" reconfigures "cf" and
recreate "config.ph" from "cf". Command line options are useful to
debug FML.

I will recommend not to configure fml.pl with command line options but
to use them only for debug. 

	*** Attention! ***

In the file "include-ctl", FML calls "fml.pl --ctladdr" style. PLEASE
DO NOT REMOVE --ctladdr option. This options tells fml.pl to be a
command server which is not written in config.ph since config.ph is
common for all programs.

4.1	syntaxes of command line options

SYNOPSIS:
   fml.pl   [ options ] $DIR [ options ]  [ $LIBDIR [ options ] ]

fml.pl and msend.pl option styles are the same but fml_local.pl is
different from them since fml_local.pl is similar to MH.
If options and arguments co-exist, we regard a string beginning with
"-" as an option, others as arguments.

[DESCRIPTION]

	-d2		debug mode level 2
			debug message is logged to $DEBUG_LOGFILE
			(== $DIR/log.debug in default).

	-d		debug mode (FML does not distribute)
	-d2		debug mode level 2
			debug message is logged to $DEBUG_LOGFILE
			(== $DIR/log.debug in default).

	-bt		debug mode (address test mode)
			now the same as -d :)

	-bd		become daemon, detach the control tty.

	-sOPT 		set "$OPT = 1;"
	-uOPT 		set "$OPT = 0;"
	-lfile		set "$LOAD_LIBRARY = file;"
	e.g.
	-sdebug		the same as $debug = 1;
	-sUSE_MIME	the same as $USE_MIME = 1;
	-uUSE_MIME	the same as $USE_MIME = 0;
	-llibftpmail.pl	$LOAD_LIBRARY = libftpmail.pl

*** Attention!: -bt follows an option string without spaces
***             since the code is easier :D

	-sdebug		debug mode

Example: enable a debug mode and $USE_MIME, in addition dumps
variables.

"|/usr/local/fml/fml.pl /Baycity /Baycity/lib -d -sUSE_MIME --DUMPVAR"

4.2	Long line option style --\S+=\S+

Example: eval( $MAINTAINER = "fukachan@sapporo.iij.ad.jp" ); essentially

	--MAINTAINER=fukachan@sapporo.iij.ad.jp

4.3	configuration files and command line options

The evaluation order of configurations are

	set defaults in fml.pl (function InitConfig)
	load $DIR/site_init.ph
   	load $DIR/config.ph
   	load $DIR/sitedef.ph
	evaluate command line options

The latter overwrites former configurations.

4.4	simple mode setting option --\S+

		--mode

is to set the current mode as "mode". This is the same as
&DEFINE_MODE('mode'); in config.ph. For unified maintenance, we do not
recommend this style. It may be useful when debug.

		--mode
		&DEFINE_MODE('mode');

		fml.pl --ctladdr

4.5	--ctladdr 

Today you can configure FML by "makefml" interface. Makefml configures
$DIR/cf for each ML and re-generates config.ph from cf.  makefml does
not control command line options e.g. in $DIR/include and
$DIR/include-ctl. For unified maintenance, you should not edit
$DIR/include* directly and command line options. $DIR/include-ctl is
exceptional. In it, we use --ctladdr to declare fml.pl runs as a
command server mode since config.ph is common over programs. Please do
not remove --ctladdr in include-ctl.

		--ctladdr

To use --ctladddr is same as to use a distributor program and another
command server program.  For source maintenance and compatibility my
choice is not to make plural programs but maintain only fml.pl as a
kernel library for FML and options change fml.pl behavior.


		INDEX

--ctladdr                                  ...   4.5 
$debug                                     ...   2.1 
debug                                      ...   3.2 
debug: printf                              ...   3.3 
&DEFINE_MODE('mode')                       ...   4.4 
&DEFINE_SUBJECT_TAG                        ...   4.4 
--mode                                     ...   4.4 
