Sourcetrailでソースの解析 - 導入から
この記事は導入について書かれています。不明な点や間違っている点などありましたらコメントなどでご連絡くれると助かります。
ソースコードを可視化できるソフトウェア「Sourcetrail」を使ってみたいと思います。
もともとはライセンスタイプでしたが OSSになりました。ありがたいことです。
前提として Windowsに VisualStudioがインストールされている環境を想定しています。
・macOSや Linuxにも対応しています
・対応エディタでしたら問題なく同じように使用できます(Atom, bracket, SublimeText, VS Codeなど)
・「C」「C++」「Java」「Python」に対応しています
1. Sourcetrailを準備する
アプリケーションは以下からダウンロードできます。
（特に気にしていないのでしたらポータブル版でいいかと思います）
ダウンロードしましたら適当な場所へインストールまたは展開しておきましょう。
2. VisualStudioに拡張機能をインストールする
さて、まずはインストールしてある VisualStudioを開いてください。Sourcetrailと連携させるために拡張機能をインストールする必要があります。
ツールメニューから「拡張機能と更新プログラム」を選択します。
すると次のようなダイアログが開きますのでオンラインを選び右上の検索ボックスに sourcetrail と入力してください。
拡張機能が表示されます。出てきましたら迷わずダウンロードしてください。
ダウンロードが完了するとスケジューリングされますので、いったん VisualStudioを終了してください。
閉じて！
VisualStudioを起動するとインストールするか問われますので「変更」を選択することでインストールすることができます。
ちょっとだけ時間がかかりますよ。
変更が完了しました。閉じると VisualStudioが起動します。
するとメニューバーには
Sourcetrailが追加されてます！。これで VisualStudioと Sourcetrailを連携させることができました。
3. Sourcetrailのデータベースを生成する
いろいろはしょりますが、ソースの可視化をしたいソリューション（.sln）を開いてください（可視化したいって思ってるくらいですからなにかしらのソリューションはありますよね？汗）。
今回はサクラエディタのソリューション（ソース）で試しました。
（https://sourceforge.net/projects/sakura-editor/）
特にビルドはする必要ありません。メニューバーの Sourcetrailから Create Compilation Databaseを選択してください。
ソースファイルをリストアップして Sourcetrailで使用するためのコマンドデータベースを作成します。
上記のようなダイアログが開きましたら必要な情報を入力していきます。
設定するのは下記くらいで十分でしょう。
もっと細かく条件づけしたい場合は Clangのオプションを参考にしてください。
・Select Projects → データベースを作成するプロジェクト
・Directory → ソリューションファイルのあるディレクトリ
・C Standard → Cの規格の選択
ひとまず、これだけ設定してあればそこそこのものは出来上がります。
では Createを押してください。
ちょっとだけ時間がかかるので今のうちにコーヒーでも淹れてくるといいですよ。
このダイアログがでたら終わりです。英語が苦手な人はせめてこれくらいは読めるようになりましょう。
コンパイルしたデータベース「compile_commands」は、ディレクトリ「D:\github.niki\sakura\sakura」に作成されました。
それを Sourcetrailにインポートしますか？
今回は流れに沿って行うため Finishを選択してください。
・・・
4. Sourcetrailでインデックスファイルを生成する
それではお待ちかね Sourcetrail (sourcetrail.exe) を実行してください。
はじめに下のようなパネルが表示されます。
何ができるかは見ての通りです。一度開いたプロジェクトは Recent Projects に追加されるので開くのが楽になります。
では、新規プロジェクトを作成してみましょう New Project を選択してください。
開いたダイアログボックスに必要な情報を入力していきます。今回は Project Name は「Sakura」にしました。
あとはプロジェクトの場所を指定する必要があります。トップあたりでいいでしょう。
入力が終わりましたら右下の Add Source Group を選択します。
ここでは種類を選択します。C++なのでタブは C++ グループタイプは Visual Studio を選択してください。そして Next で次へ進みます。
いよいよインデックスファイルを生成することになりますが、はじめに VisualStudioでデータベースを生成済みなので、ここで改めて作る必要はありません。Next で次へ進みます。
いよいよです。Compilation Database に VisualStudioで生成したデータベースファイル（.json）を選択します。
選択後、Header Files & Directores to Index にソースファイルがあるディレクトリがリストに追加されれば準備完了です。
さあ、Create ボタンを選択してください。
初回はインデックスファイルを生成する必要があります。ファイル数が多ければ多いほど時間がかかるのが悩みどころですね。
とりあえず初回なので All files で Start してください。
ご飯作ってきていいですよ。
・・・終わるまでひたすら待ちましょう・・・
終わりました！
設定が適当なので失敗しているファイルもあるようですが特に気にしなくていいと思います。
おや？「🔴 211 Errors」と出ています。何気に「C Standard」で設定した規格でエラーチェックもしてくれます。便利ですね。
OKを押すと Sourcetrailに移ります。
5. 解析結果の表示と操作
解析結果が表示されます。
では早速手始めに Files を選んでみます。
エラーを表示しているウィンドウは邪魔なので閉じてしまって構いません。
ファイルの一覧が表示されたようです。
今回は CDlgAbout.cpp を対象に見てみたいと思います。でも、たくさんのファイルから探すのが面倒なので画面上部にある overview（初めてのときはないかもしれません） と書かれている入力ボックスから探すことにします。
ここにファイル名を入力していきます。
すると該当するファイルやメソッドなど、シンボルの絞り込みを行えるので目的のものが見つかるまで入力してください。
見つかったら選択してみましょう。
では、下の方にある CDlgAbout を選択してみましょう。
すると中身が可視化されて表示されます。メソッドとかメンバとか色分けされててわかりやすいですね。
OnInitDialog を選択してみましょう。
見にくいときは Ctrl+マウスホイールで拡縮ができるのでやってみてください。
左側のビューには CDlgAbout クラスの親子関係や呼び出し順序なども確認できますね。OnInitDialog がどんな処理をしているか一目でわかります。
6. ソースウィンドウからIDEを参照する
右側のビューには選択したメソッドのソースが表示されます。
ソース側の GetModuleFileName にカーソルを合わせて右クリックをしてみてください。
ポップアップメニューが表示されます。
このメニューの一番下の Show in IDE を選択してみてください。
VisualStudioで対象のファイルが開かれ、カーソル位置も再現されます。
これはとても便利ですね。ただ、今は自動でアクティブにしてくれないのが不満です。
これは、はじめてのトンデモプログラムでも解析できそうな気がしてきました。
7. 気づいたことは issueをだそう
https://github.com/CoatiSoftware/Sourcetrail/issues
不満や要望、バグがあればどんどん知らせましょう。意外と汲み取ってくれます。
issueはちょっと・・・という方は直接メール飛ばしても OKです。僕はそのやり方でやってました。あちらが納得してくれたら issueを立ててくれます。
8. まとめ
細かく書いてませんが、これが Sourcetrailの簡単な使い方です。
Doxygen + Graphviz + Cppcheckの組み合わせとどちらが便利か比べてみたいところですが、それはいずれ時間のあるときにでも。
（ただ、ちゃんとドキュメント作るなら Doxygenとかも使いこなせるようにしておきましょう）
使ってみて良かったと思ったらぜひ OSSの支援者になってみてください。そして要望投げまくってください。
ではー。
悉く書を信ずれば則ち書無きに如かず