OSXでNaturalDocsを使ってSystemVerilogのソースコード(RTL)からDocumentationを生成する

SystemVerilogのRTLのDocumentationを作成する場合、Doxygenを使う方法とNaturalDocsがあるらしい。ここでは NaturalDocs を使う方法についてまとめる。Apple Silicon (arm64) ではそのままではうまく動かないので回避策も述べる。おそらくX86マシンの WindpwsやLinuxで使う場合は問題ないはず。

インストール

いくつか方法があるようだが、ここではBrewを使う。必要になる mono (.NET)もインストールされる。

brew install naturaldocs

Brewによるインストール自体は問題ないが、実行時に libSQLite.Mac.x64.so を参照してエラーになる。Intel Macでは問題ないかもしれないが、Apple SiliconのOSXでは libsqlite3.0.dylib を呼ぶように細工しておく

ln -s  /opt/homebrew/Cellar/sqlite/3.43.1/lib/libsqlite3.0.dylib /opt/homebrew/Cellar/naturaldocs/2.3/libexec/libSQLite.Mac.x86.so
ln -s  /opt/homebrew/Cellar/sqlite/3.43.1/lib/libsqlite3.0.dylib /opt/homebrew/Cellar/naturaldocs/2.3/libexec/libSQLite.Mac.x64.so

使い方

設定ファイルを置くフォルダと、出力先のホルダをさくせして実行すると、Doxygen同様に設定のテンプレートが作成される。

mkdir ndconfig
mkdir html
naturaldocs ndconfig

ndconfig/Project.txt を編集して、SVELTEコードの場所と出力先を設定する。相対パスの場合はProject.txtのある場所が起点となる。ちなみに設定ファイルは実行の際に書き換えられる事があるので注意。

Source Folder: ../../../verilog
HTML Output Folder: ../html

SystemVerilogでのコメントの記述例があまりなくて困るが、一般的な例は

/* Module: mux2to1
 *
 * Ports:
 *
 *    a   - Description of a
 *    b   - Description of b
 *    sel - Description of sel
 *    y   - Description of y
 */
module mux2to1 (input wire a, b, sel, output logic y);

Comments.txt でキーワードを追加するとコメントが書きやすくなる。

Comment Type: Register:
Alter Comment Type: Variable
   Plural Display Name: Register and Wire
   Keywords:
      Registers, Register

Comment Type: Wire:
Alter Comment Type: Variable
   Plural Display Name: Register and Wire
   Keywords:
      Wires, Wire

参照

• https://www.naturaldocs.org/
• https://www.naturaldocs.org/getting_started/getting_set_up/
• https://www.naturaldocs.org/polling/2022-05-30/SystemVerilog_Questions_Part_1/
• https://github.com/chiggs/UVM/blob/master/natural_docs/Config/Languages.txt#L288-L299
• https://en.wikipedia.org/wiki/Natural_Docs
• https://github.com/NaturalDocs/NaturalDocs
• https://github.com/NaturalDocs/NaturalDocs/blob/master/Engine/Source/Languages/Parsers/SystemVerilog.cs
• https://tanuki0629.hatenablog.com/entry/2018/12/30/234747
• https://tanuki0629.hatenablog.com/entry/2019/01/09/221618

Monoのデバッグ

下記の環境変数をセットして実行すると、使おうとしている共有ライブラリの詳細を確認できる

export MONO_LOG_LEVEL=debug
export MONO_LOG_MASK=dll

Doxygen

DoxygenはなぜかVHDLはサポートしている。SystemVerilog をサポートする Filter が一応あるのだが、試した範囲ではうまく動かなかった。このFilterは長らく更新もされていないし、利用例もみあたらなかったので深追いはしないことにした。