Changes between Initial Version and Version 1 of tecsmerge

Timestamp:

Jan 16, 2016, 10:23:52 PM (8 years ago)

Author:

okuma-top

Comment:

--

tecsmerge

@@ +1 @@
+
+= tecserege コマンドリファレンス =
+
+== 名前 ==
+
+tecsmerge -- TECS テンプレートマージャー
+
+== 使用方法 ==
+
+% tecsmerge [OPTION] gen_dir src_dir
+
+% tecsmerge [OPTION] template_templ.c [template2_templ.c ---] src_dir
+
+== 説明 ==
+
+TECS テンプレートマージャー tecsmerge は、TECS ジェネレータ tecsgen の生成したテンプレートファイルから初版のセルタイプコードを生成するか、テンプレートファイルを修正した版のセルタイプコードにマージします．
+マージの対象は、セルタイプコードおよびインラインヘッダです．
+
+一番目の形式で tecsmerge を呼出した場合 gen_dir にある、ファイル名末尾が _templ.c, _templ.h で終わっているものを見つけて、src_dir にあるファイルとマージします．
+もし src_dir に対応するファイルが無ければ、ファイル名から _templ を取り除いたものをファイル名として、src_dir にファイルをコピーします．
+
+二番目の形式では、個々のファイルを指定します．
+src_dir にあるファイルとマージします．
+src_dir は、ディレクトリでなければなりません．
+もし src_dir に対応するファイルが無ければ、ファイル名から _templ を取り除いたものをファイル名として、src_dir にファイルをコピーします．
+
+以下のオプションを指定できます．
+
+  -e  --exist-only
+      src_dir にマージ後のファイルが存在する場合にのみ、マージを実行し
+      ます．他のディレクトリに一部のセルタイプコードが存在する場合に、
+      誤って src_dir にテンプレートファイルがコピーされてしまうのを抑
+      止します．
+  
+  -p --port=port_name
+  -p --port=old_port_name:new_port_name
+      ポート名を指定します．ポート名を置換する場合には ':' で古い名前と
+      新しい名前を連結して指定します．
+  
+  -f --func=old_func_name:new_func_name
+      関数名の置換を指定します． ':' で古い名前と新しい名前を連結して
+      指定します．-p によりポート名を先行して指定する必要があります．
+  
+  -s --show_change_set
+      名前変更の結果を表示します．
+  
+  -o --old-mode
+      関数の後区切りを "{" ではなく、" * #[</ENTRY_FUNC>]#" とします．
+      関数ヘッダの置換が行われません (従来互換性のため．使うことはない
+      でしょう)．
+
+tecsmerege は "#[<...>]#" と "#[</...>]#" で囲まれるコメントのキーワードを頼りにマージを行います．
+これらで囲まれたコメントを変更してはなりません．
+マージの際に、このコメントはマージするテンプレートファイルのものが採用されます．
+コメントや文字列定数を誤認識しないため、実際には行頭から一致する文字列を探します．
+具体的なキーワードを以下に記します．
+行頭部分も含めて記します．
+
+ {{{
+  "/* #[<PREAMBLE>]#"
+  " * #[</PREAMBLE>]#"
+  
+  "/* #[<ENTRY_PORT>]# entry_port_name"
+  "   #[</ENTRY_PORT>]#"
+  
+  "/* #[<ENTRY_FUNC>]# entry_function_name"
+  "{"
+  
+  "/* #[<POSTAMBLE>]#"
+  " * #[</POSTAMBLE>]#"
+
+ }}}
+
+キーワードの出現順は検査されます．例えば #[<ENTRY_PORT>]# は #[</PREAMBLE>]#" または #[</ENTRY_FUNC>]# の直後にのみ出現できます．
+関数の  #[<ENTRY_FUNC>]# に対応するキーワードは " * #[</ENTRY_FUNC>]#" ではなく '{' となります．
+これにより、関数の引数に変更があった場合、tecsmerge は関数ヘッダを置換します．
+
+非受け口関数は、" #[</POSTAMBLE>]#" より後ろに書くようにしてください．
+あるいは "#[</PREAMBLE>]#" と最初の "#[<ENTRY_PORT>]#" の間に記述してください．
+
+== 制限 ==
+
+ * tecsmerge は、セルタイプに受け口を追加した場合や、シグニチャに関数が追加された場合に用いることが想定されています．tecsgen を実行するごとに tecsmerge を実行することは想定されていません．tecsmerge が意図しない変換を行い、必要な記述を喪失する事態に備えて、バックアップファイルを残しています．
+ * セルタイプコードの一部が、他のディレクトリに保管されている場合には、注意が必要です．tecsgen は、すべてのセルタイプのテンプレートを生成するため、他のディレクトリに保管されているセルタイプコードのファイルが、tecsmerge によってマージ先のディレクトリに作られてしまう可能性があります．Makefile で vpath 指定していると、マージ先ディレクトリのファイルが優先されて、本来取込まれるべきファイルが取込まれない事態が起こりえます．コンパイル、リンクは正常に終了しますが、セルタイプコードが空であるために機能しません． -e を指定することで、この誤りを防ぐことができます．
+ * tecsmerge のリネーム機能は、コメント部の変更にのみ対応しています．関数頭部を含め、コメント外の名前を変更しません．
+ * tecsmerge は、すべての文字が 1バイト文字であると仮定します．tecsmerge は、ASCII 文字のみからなるキーワード以外を評価しないため、本文が EUC, SJIS, UTF-8 の、いずれの文字コードでも正常に動作します．ただし、マージ元、マージ先の文字コードが一致している必要があります．
+ * Makefile.templ は tecsmerge の対象外です．
+ * "#[<POSTAMBLE>]#", "#[</POSTAMBLE>]#" は tecsgen V1.0.0.7 から出力されるようになりました．tecsgen V1.0.0.6 までで生成したテンプレートファイルには、このキーワードが含まれていません．V1.0.0.7 以降で生成したテンプレートファイルを tecsmerge することで追加されますが、最後尾に付加されるため、キーワードの位置を調整する必要があります．
+ * tecsgen V1.0.0.6 までの不具合に対応するため、以下もキーワードとして扱います．
+  "#[/ENTRY_FUNC>]#"
+
+== 終了ステータス ==
+
+ *  0 … 正常終了
+ *  1 … エラー
+
+エラーには、キーワードの不整合の場合や、入力ファイルの読み込みや出力ファイルの作成に失敗した場合があります．
+
+------
+[TECS リファレンスマニュアル [wiki:  トップページ]]・