# NAG Fortranコンパイラ - VS Code用 プロジェクトテンプレート
ご利用マニュアル（for Mac）

※ 本資料の制作は法政大学名誉教授竹内則雄氏及び日本ニューメリカルアルゴリズムズグループ株式会社によって行われています

## ダウンロード

本プロジェクトテンプレートのダウンロードは こちらから行ってください。

ダウンロードしたzipファイルは任意の場所に解凍して下さい。そこに含まれる「NagFortranProjectTemplate」フォルダが、プロジェクトテンプレート本体となります。

## 環境準備

本テンプレートをご利用いただく前にFortranコンパイラ、Visual Studio Code本体、Python等を用意する必要があります。

1. NAG Fortran コンパイラ のインストール
   まず、NAG Fortranコンパイラ（Apple Arm Mac 64-bit版 ）がインストールされていなければインストールして下さい。
2. Visual Studio Codeのインストール
   公式サイトよりVisual Studio Code (macOS Universal) をダウンロードしてください。
   ダウンロードファイルをダブルクリックして開く画面にVisual Studio Code アプリケーションがあるので、それをアプリケーションフォルダにドラグ＆ドロップして下さい。
3. Visual Studio Codeの起動
   アプリケーションフォルダ内にあるVisual Studio Code アプリケーションをダブルクリックしてVisual Studio Codeを起動して下さい。
4. 拡張機能「Modern Fortran」のインストール
   Modern Fortranは、Fortranコードのシンタックスハイライティング等の機能を提供するVS Code用の拡張機能ですが、その導入はVS Code内で以下の手順を参考に行って下さい。
   （尚、Modern Fortran拡張機能は、本テンプレートを使うにあたって必須ではありません）
   導入にはまず、画面左側のExtensionsアイコンをクリックするか、Shift + Command + X を押してください
   次に画面上部の検索窓に Fortran と入力します。
   出てきた一覧の中にある Modern Fortran拡張機能のInstallをクリックします。
5. Visutal Studio Codeの終了
   一旦ここでVS Codeを（画面を閉じるだけではなく）完全に終了します。
6. Python環境の準備
   本テンプレートは、プロジェクト管理とビルド自動化にPython 3.xを使用しています。コマンドライン上でpythonと入力してPython 3.xにアクセスできるようにしてください。もしPython 3.xがまだインストールされていない場合は、インストールが必要です。ここではインストールの一例として、Homebrewを使用した方法を紹介します。
   Terminalを開き、そこで brew install python と入力してインストールを開始します。
   例）

         brew install python

   途中、様々な表示がなされますが、最後の方に python と言う名前でアクセスできるフォルダの情報が以下の用に表示されます。
   次に、の表示されたフォルダを~/.zshrcで環境変数PATHに追加します。
   設定例）

         export PATH=/opt/homebrew/opt/python@3.11/libexec/bin:$PATH

ここまでで、環境準備は完了です。

## ユーザープロジェクトの作成手順

次にユーザープロジェクトの作成方法について説明します。

1. プロジェクトテンプレートのコピーとリネーム
   プロジェクトテンプレート(NagFortranProjectTemplate) は任意の場所にフォルダごとコピーし、任意の名前に変更して下さい。
   ここでフォルダーパスには空白や日本語文字を含めないようにしてください。（一部のシステムで、これらの文字が問題を引き起こす可能性があるため）
2. プロジェクトフォルダを開く
   VS Codeを起動して、File > Open Folder でプロジェクトフォルダを開いてください。
3. プロジェクト名の設定
   プロジェクトフォルダを開いたら、まず Terminal > Run Task > Change Project Name タスクを実行してください。
   画面上に新しいプロジェクト名を入力するための入力窓が表示されますので、そこにプロジェクト名を入力してください。上記と同様、パスに空白や日本語文字を含めないように注意してください。
4. ソースコードの配置
   ユーザーソースコード（*.f90, *.f）を `src` フォルダ以下に新規作成、もしくはコピーしてきます。
   拡張子は `.f90`（自由形式）または `.f`（固定形式）が利用可能です。

以下はソースコードを新規作成する例です。

ソースフォルダの下にファイルを新規作成します。
ファイル名を指定します。
プログラムを入力します。

これで、ユーザプロジェクトができました。

## プロジェクトの各種操作

出来上がったプロジェクトに対しては、以下に示す各種操作が可能です。

- ビルド: Terminal > Run Task > Build Fortran Project もしくは Command + Shift + B
  プログラムのビルドを行います。
  ターミナルから直接 make としても同様のビルド処理が行われます。
- 実行: Terminal > Run Task > Run Fortran Project
  プログラムの実行を行います。ビルドがまだされていない場合は先にビルドを行ってから実行を行います。
  ターミナルから直接 make run としても同様の処理が行われます。
  なお、実行時のカレントフォルダはプロジェクトフォルダトップとなります。
- クリーン: Terminal > Run Task > Clean Fortran Project
  プロジェクトのクリーン処理を行います。具体的には、build_debugもしくはbuild_releaseフォルダ以下のすべてのファイル（*.o, *.mod, dependencies.mk）を削除します。
  ターミナルから直接 make clean としても同様の処理が行われます。
- 依存関係ファイル生成: Terminal > Run Task > Generate Dependencies
  依存関係ファイル（build_debug/dependencies.mkもしくはbuild_release/dependencies.mk）を生成します。
  ターミナルから直接 make depend としても同様の処理が行われます。
- ビルドモードの切り替え: Terminal > Run Task > Switch to Debug Mode または Switch to Release Mode
  ビルドモードを切り替えます。ビルドモードはリリースもしくはデバッグのどちらかです。プログラム開発時はデバッグモード、リリース用のビルドはリリースモードで行う事をお勧めします。尚、デフォルトのビルドモードはデバッグとなっています。
  ターミナルから直接 make set_debug_mode もしくは make set_release_mode としても同様の処理が行われます。
- プロジェクト情報の表示: Terminal > Run Task > Show Info
  プロジェクト名、現在のビルドモード、実行形式ファイル名等の各種情報を表示します。
  ターミナルから直接 make show_info としても同様の処理が行われます。
- プロジェクト名の変更: Terminal > Run Task > Change Project Name
  プロジェクト名の変更を行います。
  ターミナルから直接 make change_project_name としても同様の処理が行われます。

以下は、上記で作成したhello.f90を実行する例ですが、メニューの Terminal > Run Task > Run Fortran Projectでそれを行っています。
プログラムが無事実行されている事を確認できます。

## ビルドオプションの変更について

コンパイル及びリンクオプションを変更したい場合は、Makefileの上の方にある、以下の部分を適宜書き換えて下さい。

    赤：デバッグモードのオプション
    緑：リリースモードのオプション

    # Compiler Options
    FFLAGS_DEBUG := -g -gline -C
    FFLAGS_RELEASE := -O2

    # Linker Options
    # examples
    # LDFLAGS_DEBUG := -L/path/to/debug/libs -lmylibd
    # LDFLAGS_RELEASE := -L/path/to/release/libs -lmylib
    LDFLAGS_DEBUG :=
    LDFLAGS_RELEASE :=

## Makefileについて

提供されているMakefileはUnix系OS（Unix, Linux, macOS）及び Windowsでも動く設計となっています。このファイルに定義されている主なターゲットは以下の通りです。

dep-all
  make コマンドを引数なしで実行した場合のデフォルトターゲット。依存関係ファイル（ build_release/dependencies.mk もしくは build_debug/dependencies.mk ）が存在しない場合に生成し、その後 all を実行。尚、依存関係ファイルはNAG Fortran コンパイラの依存関係解析ツール（nagfor =depend）で行っている。このツールはFortranモジュールの依存関係も考慮した解析を行う。
all
  必要なすべてのソースファイルをコンパイルして実行可能ファイルを生成する。
run
  プログラムを実行する。allターゲットが先に実行されている必要あり
clean
  ビルドプロセスで生成されたすべてのファイルを削除する。これには依存関係ファイルdependencies.mkも含まれる。
show_info
  プロジェクトの現在の設定（プロジェクト名、ビルドモードなど）を表示する。設定値は prjsettings.json の "buildMode" から読み込まれる
set_debug_mode
  ビルドモードを debug に切り替える。write_settings.py スクリプトを使用して prjsettings.json の "buildMode" を更新している。
set_release_mode
  ビルドモードを release に切り替える。write_settings.py スクリプトを使用して prjsettings.json の "buildMode" を更新している。
change_project_name
  プロジェクト名を変更する。change_project_name.py スクリプトを使用して prjsettings.json内の"projectName"を更新し、更に .vscode/launcher.json の "program" に、プロジェクト名に連動して変わる実行形式ファイル名のフルパス（例えば/home/nag/.../build_debug/myProjectDebug.exe）を設定する。
depend
  依存関係ファイルを生成。nagfor =depend を使用して依存関係を得る。得られた情報は transform_dependencies.py でビルドディレクトリを考慮に入れた変換を適用し、最終的にdependencies.mkに出力する。

## scripts/*.pyファイルについて

本テンプレートでは以下のパイソンスクリプトを利用しています。

1. read_settings.py
   - 目的: prjsettings.json から指定されたキーの値を読む。
   - 引数: キー名（必須）、デフォルト値（オプショナル）
   - 使用箇所: Makefile で BUILD_MODE と PROJECT_NAME を読み込む際に使用。
2. write_settings.py
   - 目的: prjsettings.json に指定されたキーに値を書き込む。
   - 引数: キー名（必須）、値（必須）
   - 使用箇所: tasks.json の「Switch to Debug Mode」と「Switch to Release Mode」タスクで使用。
3. change_project_name.py
   - 目的: 新しいプロジェクト名を prjsettings.json に設定し、.vscode/launch.json のprogramのパスを適切なexe名で更新する。
   - 引数: 新しいプロジェクト名（必須）
   - 使用箇所: tasks.json の「Change Project Name」タスクで使用。
4. transform_dependencies.py
   - 目的: nagfor=dependの出力をソースファイル以外のファイル（*.oや*.mod）がビルドディレクトリにあるという前提で、依存関係を変換する。
   - 引数: ビルドディレクトリ名（必須）
   - 使用箇所: Makefile の `depend` ターゲットで使用。

## .prjsettings.jsonについて

このファイルはプロジェクトのルートフォルダに存在し、プロジェクト名及び現在のビルドモードを管理するために使われています。（JSON形式）

.prjsettings.jsonの例：

    {
        "buildMode": "debug",
        "projectName": "MyFortranProject"
    }

- buildMode: プロジェクトのビルドモード（'debug' か 'release'）。デフォルトはdebug
- projectName: プロジェクト名。デフォルトは'MyProject'

利用箇所：

- Makefile: BUILD_MODE と PROJECT_NAME を read_settings.py を用いて、このファイルから読み込んでいる
- tasks.json: ビルドモードを切り替えるタスク（'Switch to Debug Mode' および 'Switch to Release Mode'）で `write_settings.py` を用いて、buildModeが更新される
- change_project_name.py: 指定されたプロジェクト名を projectName に設定している