OpenFOAMのコード追跡入門（はじめてのgdbなど）

オープンCAE勉強会＠富山　20180324

## ソースコード ドキュメンテーション (source code documentation)

### The OpenFOAM Foundation
C++ Sourc Code Guide
The C++ Source Guide, generated by Doxygen has links to source code, inheritance and collaboration diagrams, and more.
https://cpp.openfoam.org/v5/

OpenFOAMインストールディレクトリに生成することができる。
The same guide will be generated by Doxygen in the OpenFOAM install directory.

How to generate the guide: Do not execute this because it takes a long time.

```shell-session
cd $WM_PROJECT_DIR/doc/Doxygen/
./Allwmake
```

### ESI
OpenFOAM®  Documentation
https://www.openfoam.com/documentation/

Extended Code Guide
https://www.openfoam.com/documentation/cpp-guide/html/


### GNU GLOBAL

https://www.gnu.org/software/global/

GNU GLOBAL is a source code tagging system that works the same way across diverse environments, such as Emacs editor, Vi editor, Less viewer, Bash shell, various web browsers, etc.

ソースコードにタグ付けし，関係性を調べやすくする。html形式で出力することもできる。

The web pages is generated 

```sh
cd /home/user/OpenFOAM/OpenFOAM-5.x/
gtags
htags --suggest
```

GNU GLOBALの設定ファイル　~/.globalrc

このファイルは，/usr/share/doc/global/examples/gtags.conf.gzをコピーして作成した。そのファイル内で，除外するディレクトリ/ファイルを下記のように設定する。lnIncludeを除外しておかないと，同じファイルが2重に表示される。

common:\
    :skip=GPATH,GTAGS,GRTAGS,GSYMS,bin/,doc/,etc/,nbproject/,platforms/,tutorials/,wmake/,Allwmake,lnInclude/,COPYING,log.make,Makefile,README.org,HTML/,HTML.pub/,tags,TAGS,ID,y.tab.c,y.tab.h,gtags.files,cscope.files,cscope.out,cscope.po.out,cscope.in.out,SCCS/,RCS/,CVS/,CVSROOT/,{arch}/,autom4te.cache/,*.orig,*.rej,*.bak,*~,#*#,*.swp,*.tmp,*_flymake.*,*_flymake,*.o,*.a,*.so,*.lo,*.zip,*.gz,*.bz2,*.xz,*.lzh,*.Z,*.tgz,*.min.js,*min.css:


## debug オプションでの OpenFOAM コンパイル

今回の講習では，gnu gdb を使って，計算実行時のOpenFOAMの状態を追跡する。このためには，OpenFOAMをdebugオプションでコンパイルする必要がある。通常のインストールでは，OpenFOAMはdegubではなく最適化オプションを有効にしてコンパイルされている。

OpenFOAM 5.x is compiled with Full Debug option.

### 講習マシンの設定について（解説）

講習マシンでは，下記の解説に基づいてOpenFOAM 5.x をインストールした。

OpenFOAM 5.x is installed from source.

https://openfoamwiki.net/index.php/Installation/Linux/OpenFOAM-5.x/Ubuntu#Ubuntu_16.04

OpenFOAM-5.xディレクトリ内のetc/bashrcファイルを下記のとおり修正した。
Modified etc/bashrc file

BEFORE: export WM_PROJECT_VERSION=5.x
AFTER:  export WM_PROJECT_VERSION=5.x-Debug

BEFORE:export WM_COMPILE_OPTION=Opt
AFTER: export WM_COMPILE_OPTION=Debug

上記設定に合わせて，ディレクトリ名を OpenFOAM-5.x-Debug および ThirdParty-5.x-Debug に変更した。
Rename directory names to OpenFOAM-5.x-Debug and ThirdParty-5.x-Debug.


## gdbを使って見る

### 大きな流れ

OpenFOAM実行環境の読み込み。Read OpenFOAM settings.
$ of5x-debug

ケースディレクトリに移動する。Move to a case directory.
$ cd OpenFOAM/user-5.x-Debug/run/pitzDaily/

ソルバ名の前に gdb を付けて実行する。Run the solver with gdb.
$ gdb simpleFoam

gdb実行状態では，(gdb)から始まる行が表示され，コマンド入力を待つ状態となる。simpleFoamは，まだ実行されていない。
Under gdb execution, a line staring with (gdb) is waiting commands. simpleFoam has not yet started.

#### 主なコマンドの一部

	* run    gdbに渡したプログラムの実行を開始する    run the program
	* Ctrl + c    動作中のgdbコマンドを停止する。　intrupt gdb command
	* break simpleFoam.C:57    simpleFoam.Cの57行目にブレークポイントを設置する
	* continue    次のブレークポイントまでプログラムを実行する
	* next    現在のコード内で，次の命令まで実行する。関数の内部には入らない。
	* step    呼びだし先の内部まで追いかけて命令を実行する。
	* list    現在の位置前後のソースコードを表示する。標準では10行分。
	* finish    関数を抜けるまで実行する。
	* print something    変数somethingの内容を表示する
	* info    いろいろな情報を表示する
	* where    現在の場所がどこから呼び出されているかを表示する。backtraceの別名。

コマンドは短縮形で使用可能。next は n，step は s など。タブ補完も可能。

#### 試してみる(1) 

とりあえず，プログラムを実行して止める。どこで止まったか確認する。何が見られるかを試す。

プログラムを走らせて，
> (gdb) run

プログラムを一旦停止し，どこにいるのか確認する。
> (gdb) Ctrl+c
> (gdb) where

ステップ実行してみる。nextとstepin。
> (gdb) n
> (gdb) s

現在位置周辺のコードを表示する。
> (gdb) list

何らかの変数SOMETHING(実際には，コード中の何らかの変数に置き換える)の内容を表示する。
> (gdb) p SOMETHING

終了する。
> (gdb) quit


#### 試してみる(2) 

ブレークポイントを設定して，その辺りを調査する。

ブレークポイントを設定して，プログラムを実行する。
> (gdb) break main
> (gdb) break fvmDiv.C:1
> (gdb) run

ブレークポイントで停止させた状態で，backtraceする。近隣リストを表示する。
> (gdb) where
> (gdb) list

何らかの変数name(実際には，コード中の何らかの変数名に置き換える)の内容を表示する。continueして，次のブレークポイントまで実行する。
> (gdb) p name
> (gdb) c

変数nameの内容を表示する。先ほどとは異なるはず。continueして，次のブレークポイントまで実行する。
> (gdb) p name
> (gdb) c

くり返す。
> (gdb) p name
> (gdb) c

リストを表示する。ステップ実行してみる。nを7回，コードを表示，次のブレークポイントまで実行する。
> (gdb) list
> (gdb) n
> (gdb) n
> (gdb) n
> (gdb) n
> (gdb) n
> (gdb) n
> (gdb) n
> (gdb) list
> (gdb) c

今度は，step命令で，関数の内部も調査する。これをくり返す。
> (gdb) list
> (gdb) s

#### 補足：list

listで表示される行数は，listsizeとして設定されている。
確認方法
    show listsize
変更方法（numには数字を入れる）
    set listsize num

#### 補足：backtrace，frame など
    
backtrace を実行すると，frame番号が表示される。frame 2 のコマンドで，2番目のframeに移動して，そこでの状態（変数など）を調べることができる。up や down でも移動できる。

#### 補足：変数のprint

OpenFOAMの変数をprint すると，多くの内容が表示される。主に知りたい情報は先頭部分にあることが多い？


## gdbのGUIフロントエンドについて

### ddd

https://www.gnu.org/software/ddd/

シンプル。古めかしい。安定している。

OpenFOAM実行環境を読み込んだ端末で，ケースディレクトリに移動したあと，下記を実行する。

$ ddd simpleFoam

### gdbgui

https://www.gdbgui.com/

新しい。ウェブベース。不安定？遅い？

OpenFOAM実行環境を読み込んだ端末で，ケースディレクトリに移動したあと，下記を実行する。

$ gdbgui simpleFoam


### IDE

いろいろなIDEが使用可能。不安定？


## netBeans

https://netbeans.apache.org//

オープンソースのIDE。講習用マシンでは，C++対応モジュール付でインストール済み。

OpenFOAMとnetBeans との組みあわせ方については，ウェブにいろいろな情報がある。オープンCAE勉強会＠富山でも使用歴あり。(第16回 オープンCAE勉強会＠富山 2013/11/17)

https://eddy.pu-toyama.ac.jp/OpenFOAM/

コードの閲覧などには便利。

gdbの追跡にも利用できるが，途中で停止して無反応となることが頻発する。

OpenFOAM実行環境を読み込んだ端末からnetBeansを実行する。

$ netbeans