                デバッグについて

------------------------------------------------------------
1	概要

2	デバッグモードとデバッグレベル
2.1	デバッグモード
2.2	デバッグモード レベル２

3	デバッグの HOW-TO 
3.1	How to debug (1)
3.2	How to debug (2)［デバッグのポイント］
3.3	古典の printf debug の例

4	コマンドライン オプション
4.1	コマンドラインのシンタックス
4.2	ロングラインオプション --\S+=\S+
4.3	設定ファイルとコマンドラインオプション
4.4	簡易モード設定 (ロングラインオプション) --\S+
4.5	--ctladdr 指定について (コマンド用のアドレス)
------------------------------------------------------------


1	概要

ＭＬサーバ/ドライバ はユーザが直接使うコマンドではありません。
通常それはメールサーバ（デーモン）が起動するプログラムです。

デバッグするためにはメールサーバがしていることをエミュレーションする必
要があります。

デバッグといっても多くの場合fmlよりメールサーバの設定でつまづくことが
多いです。

◯ メールサーバの典型的なエラーについては => 

 メールサーバ → fml へ渡る時/前の話です。

◯ SMTPのやりとりのログ => smtp 3.1

 fml -> メールサーバ へメールを渡す時のログが見られます。

◯ エラー事例集は => troubleshoot 1

2	デバッグモードとデバッグレベル

2.1	デバッグモード

	$debug        = 1; (default 0)

デバッグモードのフラッグ。１がデバッグモード。配送以外の設定、コマンド
操作はすべて有効です。テストに使って下さい。０に設定しないと配送してく
れません。デバッグの内容をSTDERRに吐きます。

2.2	デバッグモード レベル２

$debug を2以上にすると、にデバッグ出力を

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

ファイルに吐きます。

3	デバッグの HOW-TO 

3.1	How to debug (1)

in fml-support: 5282
    1. OSのメールのログを調べる。
    
    INSTALL file の Appendix A をみてみてください。
    
    2. fml のログを調べる。$DIR/log (ML's HOME ログファイル)
    
    3. fml からMTAへちゃんと渡せているかのログを調べる。
       ($DIR/var/log/_smtplog)
    
    4. "makefml test ML" で fml 自体が動いているかを調べる。
       このテストはMTAとは完全に無関係に動くのでこれが動くならMTAの問題
    
    	makefml test ML
    
    と打つとデバッグモードでの動作テストができます。画面に debug 情報が一
    杯出るので emacs の shell mode なり /usr/bin/script などでログをとるな
    りして見て下さい。makefml test ML を起動すると配送のテストかコマンドの
    テストか？選択をしろといわれます。

3.2	How to debug (2)［デバッグのポイント］

From: fml-support: 01411

…略…

○ 私 printf デバッグがすきなので $debug = 1; にした時の画面に出るエラー
情報から推測するのが多いです。

もしくは

○ perl -d オプションで perl debugger を使う

Example:

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

○ どのファイルか？は目的別なのでそれっぽい名前のことが多いですが…

	基本関数	fml.pl
	SMTP		libsmtp.pl
	その他		lib(それっぽい名前).pl

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

とか省略系もあるけど… 

3.3	古典の printf debug の例

    From: fukachan@phys.titech.ac.jp
    X-Mail-Count: 00702 
    
    例えば次のような適当な printf 構文をつっこむ
    
    	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 
    
    とかして、この REQ:GUIDE の値の変化をみるというのはどうでしょう？
    
    ただしいばあいは &Parsing のあと １になって そのままのはずですよね
    
4	コマンドライン オプション

コマンドラインオプションは /etc/aliases から呼ばれる include file の

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

のオプション部分(上の -option)の話のことです。主にデバッグ時に使うこと
を想定しています。保守の都合を考えたら $DIR/cf (config.ph) で設定する
べきです。

makefml config は $DIR/cf の中の変数を書き換えます。通常設定をいじる時
は $DIR/cf の中にデフォールトとは異なる設定を書くようにして下さい
(config.phをcfから生成することを忘れずに)。コマンドラインオプションは
デバッグ以外の目的では使わないことを推奨します。

コマンドラインは使い方(e.g. デバッグ)によってはとっても便利ですが、ど
ういうものかよくわからない人は使わないで下さい。

	＊＊＊注意＊＊＊

なお makefml で作る include-ctl というファイル中には --ctladdr という
オプションがついていますが、これは外さないで下さい。 このオプションだ
けは全プログラムに共通の config.ph に書けない項目だからです。

4.1	コマンドラインのシンタックス

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

	fml.pl msend.pl は同じ引数のとりかたをします。
	注意：fml_local.pl は MH を意識してるので異なります。

オプションと引数が共存する時は

	引数が -ではじまるならオプション
	それ以外は directory などの変数

だと仮定します。順番は関係ありません。directory に関しては その 
directory が存在すれば引数の順に $DIR、$LIBDIR にセットされます。

[DESCRIPTION]

	-d		デバッグモード
			（ＭＬへの配送以外すべてを実行可能）
	-d2		debug mode level 2
			debug message is logged to $DEBUG_LOGFILE
			(== $DIR/log.debug in default).

	-bt   		アドレステストモード	(Become Test)
			メンバーチェックのところまで実行する。
			ＭＬへの配送やコマンドは実行しない。
			いまのところ debug mode とかわらへんねん:-)

	-bd		デーモンモード	(Become Daemon)

	-sOPT 		$OPT をセットする(e.g. -sdebug == -d)
	-uOPT 		$OPT をオフする(e.g. -udebug は $debug = 0; と同じ）
	-lfile		file を $LOAD_LIBRARY 変数に代入する 
			e.g. -llibfml.pl 下↓参照

**注意:-btのように『空白は無し』です。(だってその方がコードが簡単:-)**

例:
	-llibfml.pl とすると、コマンド専用アドレスのできあがりです
	＃ CONTROL_ADDRESS とおなじ意味ですね

	-llibftpmail.pl ftpmail 専用アドレス
	-sdebug		debug mode
	-sUSE_MIME	$USE_MIME = 1; と同じ

とかできるわけです

例：

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

デバッグモード かつ $USE_MIME =1; で 変数のダンプも行なう。

4.2	ロングラインオプション --\S+=\S+

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

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

$MAINTAINER の値を fukachan@sapporo.iij.ad.jp で Overwrite します。
config.ph の後評価されるので、ロングラインオプションを使ってある値だけ
を変更することが可能です。

4.3	設定ファイルとコマンドラインオプション

各ＭＬの場所に config.ph を置く代わりに FML のライブラリが置いてある場
所に config.ph もしくは sitedef.ph をひとつだけ置いてそれだけを保守す
るのも便利です。この場合評価される順番は次のようになります。
普通の program と同じようにコマンドラインが一番最後に評価されます。

   0     デフォールト設定(program 内にハードコード)
   1    (もしあれば) 共用directory の site_init.ph を loading
   2	$DIR/config.ph (このファイルは必須)
   3	(もしあれば) 共用directory の sitedef.ph を loading
   4	その後コマンドラインオプションを評価

4.4	簡易モード設定 (ロングラインオプション) --\S+

		--mode

の形で 簡単に作動モードを変更することが出来ます。同じことを config.ph 
でする時は

		--mode
は
		&DEFINE_MODE('mode');

になります。なお、コマンドラインの --mode は config.ph で指定する 
$Envelope{"mode:$mode"} と同じ意味になります。デバッグ以外では使わない
方がいいでしょう(developer 向け)。

例:
		fml.pl --ctladdr

4.5	--ctladdr 指定について (コマンド用のアドレス)

現在の makefml ではすべての設定を config.ph の値を書き直すことで行ない
ます。そのためコマンドラインオプションはいじりません。

ひとつだけ例外があります。コマンド用のアドレス listname-ctl は 
include-ctl を呼びますが、この include-ctl の中には

		--ctladdr

という『コマンド用のアドレス宛のメールを処理するという意味をfml.pl へ
伝えるためのコマンドラインオプション』があります。これは全プログラムに
共通の config.ph には記述できません。
この --ctladdr は消さないで下さい。

コマンド用のコマンド fmlcommand.pl を呼び出すようにしても同じことです
が複数のファイルを保守するのは嫌なので、FML 2.1 以降では fml.pl を用い 
--ctladdr で挙動を変える実装にしています。
＃これにより、backward も可能になるという理由もあります。


		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 
コマンドラインのシンタックス               ...   4.1 
コマンドライン オプション                  ...   4 
デバッグモード                             ...   2.1 
