More than 1 year has passed since last update.
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は長らく更新もされていないし、利用例もみあたらなかったので深追いはしないことにした。
Register as a new user and use Qiita more conveniently
- You get articles that match your needs
- You can efficiently read back useful information
- You can use dark theme