# NAG Fortran Compiler - VS Code Project Template
User Manual (for Mac)

※ This document was produced by Hosei University Honorary Professor Norio Takeuchi and Nihon Numerical Algorithms Group.

## Download

To download this project template, please visit here.

After downloading the zip file, please unzip it to a location of your choice. The "NagFortranProjectTemplate" folder contained therein will be the project template itself.

## Environment Setup

Before using this template, it is necessary to prepare the Fortran compiler, Visual Studio Code itself, Python, etc.

1. NAG Fortran Compiler Installation
   First, if the NAG Fortran Compiler (Apple Arm Mac 64-bit version) is not yet installed, please install it.
2. Visual Studio Code Installation
   Please download Visual Studio Code (macOS Universal) from the official website.
   Double-click the downloaded file and drag & drop the Visual Studio Code application into the Applications folder from the opened screen.
3. Starting Visual Studio Code
   Double-click the Visual Studio Code application in the Applications folder to start Visual Studio Code.
4. Installation of the 'Modern Fortran' Extension
   Modern Fortran is an extension for VS Code that provides syntax highlighting for Fortran code, among other features. Please follow the steps below to install it within VS Code.
   (Note: The Modern Fortran extension is not mandatory for using this template)
   To install, first click the Extensions icon on the left side of the screen or press Shift + Command + X.
   Next, type 'Fortran' into the search box at the top of the screen.
   Click 'Install' for the Modern Fortran extension that appears in the list.
5. Exiting Visutal Studio Code
   Once done, completely exit VS Code (not just closing the screen).
6. Preparing the Python Environment
   This template uses Python 3.x for project management and build automation. Please ensure you can access Python 3.x from the command line. If Python 3.x is not yet installed, you will need to install it. Here, we introduce an example using Homebrew for installation.
   Open Terminal and start the installation by typing 'brew install python'.
   Example:

         brew install python

   Various messages will appear during the process, but towards the end, the folder where you can access Python will be displayed as follows.
   Next, add the displayed folder to the environment variable PATH in ~/.zshrc.
   Example setting:

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

With this, the environment setup is complete.

## Creating a User Project

Next, we will explain how to create a user project.

1. Copying and Renaming the Project Template
   Copy the project template (NagFortranProjectTemplate) to a location of your choice and rename it as desired.
   Please ensure that the folder path does not contain any spaces or Japanese characters. (Some systems may experience issues with these characters)
2. Opening the Project Folder
   Launch VS Code and open the project folder by selecting File > Open Folder.
3. Setting the Project Name
   After opening the project folder, execute the Terminal > Run Task > Change Project Name task.
   An input window will appear on the screen for entering a new project name. Please enter the project name, ensuring not to include spaces or Japanese characters in the path.
4. Placing the Source Code
   Create new or copy your user source code files (*.f90, *.f) into the `src` folder.
   Both `.f90` (free format) and `.f` (fixed format) extensions are acceptable.

Here is an example of creating a new source code file.

Create a new file under the source folder.
Specify the file name.
Enter your program.

With this, your user project is ready.

## Various Project Operations

For the completed project, the following operations are possible:

- Build: Terminal > Run Task > Build Fortran Project or Command + Shift + B
  Performs the build of the program.
  You can also build directly from the terminal by typing make.
- Run: Terminal > Run Task > Run Fortran Project
  Executes the program. If the build has not been done yet, the build will be done first.
  You can also execute the same process directly from the terminal by typing make run.
  Note that the current directory during execution will be the top of the project folder.
- Clean: Terminal > Run Task > Clean Fortran Project
  Performs the cleaning process of the project, specifically deleting all files (*.o, *.mod, dependencies.mk) in the build_debug or build_release folder.
  You can also perform the same process directly from the terminal by typing make clean.
- Switch Build Mode: Terminal > Run Task > Switch to Debug Mode or Switch to Release Mode
  Switches the build mode. The build mode is either Release or Debug. It is recommended to use Debug mode for program development and Release mode for release builds. The default build mode is set to Debug.
  You can also perform the same process directly from the terminal by typing make set_debug_mode or make set_release_mode.
- Show Project Information: Terminal > Run Task > Show Info
  Displays various information such as project name, current build mode, executable file name, etc.
  You can also perform the same process directly from the terminal by typing make show_info.
- Change Project Name: Terminal > Run Task > Change Project Name
  Changes the name of the project.
  You can also perform the same process directly from the terminal by typing make change_project_name.

Below is an example of running the hello.f90 created earlier, using the Terminal > Run Task > Run Fortran Project menu.
You can confirm that the program has run successfully.

## Changing Build Options

If you want to change the compile and link options, please modify the following parts in the Makefile as appropriate.

    Red: Options for debug mode
    Green: Options for release mode

    # 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

The provided Makefile is designed to work with Unix-like OSes (Unix, Linux, macOS) as well as Windows. The main targets defined in this file are as follows:

dep-all
  The default target when running the make command without arguments. It generates the dependency file (build_release/dependencies.mk or build_debug/dependencies.mk) if it does not exist, and then executes the all target. The dependency file is generated using the NAG Fortran Compiler's dependency analysis tool (nagfor =depend), which considers dependencies of Fortran modules.
all
  Compiles all necessary source files to create the executable file.
run
  Executes the program. The all target must be run first.
clean
  Removes all files generated during the build process, including the dependencies.mk file.
show_info
  Displays the current settings of the project (such as project name, build mode, etc.). The settings are read from "buildMode" in prjsettings.json.
set_debug_mode
  Switches the build mode to debug. It updates "buildMode" in prjsettings.json using the write_settings.py script.
set_release_mode
  Switches the build mode to release. It updates "buildMode" in prjsettings.json using the write_settings.py script.
change_project_name
  Changes the project name. The change_project_name.py script is used to update "projectName" in prjsettings.json and also to set the path of the executable file name in .vscode/launcher.json, which changes according to the project name (for example, /home/nag/.../build_debug/myProjectDebug.exe).
depend
  Generates the dependency file. It uses nagfor =depend to obtain dependencies. The information obtained is then transformed considering the build directory using transform_dependencies.py and finally output to dependencies.mk.

## About the scripts/*.py Files

This template utilizes the following Python scripts:

1. read_settings.py
   - Purpose: To read the value of a specified key from prjsettings.json.
   - Arguments: Key name (required), default value (optional)
   - Usage: Used in the Makefile to read the BUILD_MODE and PROJECT_NAME.
2. write_settings.py
   - Purpose: To write a value to a specified key in prjsettings.json.
   - Arguments: Key name (required), value (required)
   - Usage: Used in the tasks.json for the 'Switch to Debug Mode' and 'Switch to Release Mode' tasks.
3. change_project_name.py
   - Purpose: To set a new project name in prjsettings.json and update the path of the executable file name in .vscode/launcher.json accordingly.
   - Arguments: New project name (required)
   - Usage: Used in the tasks.json for the 'Change Project Name' task.
4. transform_dependencies.py
   - Purpose: To transform the dependencies output by nagfor=depend, assuming that files other than source files (*.o, *.mod) are in the build directory.
   - Arguments: Build directory name (required)
   - Usage: Used in the Makefile's `depend` target.

## About .prjsettings.json

This file is located in the root folder of the project and is used to manage the project name and the current build mode. It is in JSON format.

Example of .prjsettings.json:

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

- buildMode: The build mode of the project ('debug' or 'release'). The default is debug.
- projectName: The name of the project. The default is 'MyProject'.

Usage:

- Makefile: Reads BUILD_MODE and PROJECT_NAME using read_settings.py from this file.
- tasks.json: Updates buildMode using `write_settings.py` in the tasks for switching build modes ('Switch to Debug Mode' and 'Switch to Release Mode').
- change_project_name.py: Sets the specified project name to projectName.