# INSTALL GUIDE                                                      {#INSTALL}

<!-- English bellow -->

@ja
## 必要要件

spmodel fortran library を利用するには以下のソフトウェアが必要です.

* Fortran Compiler: support >= fortran 2003 standard.
* [Ruby](https://www.ruby-lang.org/ja/): ソースコードの動的生成に [erb](ERBja) を利用しています. 
* [Unidata | NetCDF C Library](http://www.unidata.ucar.edu/software/netcdf/)
* [Unidata | NetCDF Fortran Library](http://www.unidata.ucar.edu/downloads/netcdf/index.jsp)
* [gtool5 | Gtool5 Fortran Library](http://www.gfd-dennou.org/library/gtool/gtool5.htm.ja)
* Optional: ドキュメントの再生成には [Doxygen](http://www.stack.nl/~dimitri/doxygen/) が必要となります. 

## インストールの手引き

### はじめに. 

spmodel fortran library は autotools ([autoconf],[automake],[libtool]) を利用しています.
autotools を利用する典型的なソフトウェアと同様に

    ./configure & make & make install

でインストールすることができるでしょう. 

### 環境変数の設定

先ずは環境変数 `FC` に使用する Fortran コンパイラを, 
環境変数 `FCFLAGS` に最適化やデバッグのためのオプションを指定して下さい. 
例えば

    % FC=gfortran
    % FCFLAGS="-g -O2 -fopenmp"

などです.

MPI 並列計算を行いたい場合には

    % FC=mpif90

といった MPI 並列対応の Fortran compiler を指定してください.

NOTE: MPI library として mpich での動作は確認してます.
      openmpi では不具合があります.


### ソースの展開と `configure` の実行

次に適当な作業ディレクトリでソースアーカイブを展開します.
ソースは gtool5-`バージョン` というディレクトリに展開されます.

	$ tar xvf gtool5_current.tar.gz

展開されたディレクトリに移動し, `./configure`を実行します.

    % ./configure

out ot tree build にも対応していますので, 例えば `build` 以下でコンパイルをしたい場合には

    % mkdir build
    % cd build
    % ../configure

といったことも可能です. 

インストール先などを変更したい場合などは, `configure` に `--help` オプ
ションをつけて, 指定可能なオプションリストをご確認下さい. 

	% ./configure --help

主なオプションは以下の通りです.

* `--with-gt5config=ARG`
  * Defatult: `PATH` から探索.
  * `ARG` に `gt5config` を明示的に指定することもできます.
    これによって NetCDF C Library および NetCDF Fortran Library,
    gtool5 fortran library に関する設定が行なわれます.

* `--with-ispack'
  * ISPACK3 Library の場所を指定します.

* `--with-lapack'
  * LAPACK Library の場所を指定します.

* `--with-blas'
  * BLAS Library の場所を指定します.

* `--with-mint`
  * セクター対称性を仮定した球面計算を可能にします

* '--with-lumatrix=ARG' 
  * 連立 1 次方程式を解くルーチンを指定します.
    VEC : ベクトル並列計算向きオリジナルルーチンを使用します.
    OMP : OpenMP 計算向きオリジナルルーチンを使用します.
    LAPACK : LAPACK のサブルーチンを使用します.

* `--prefix=ARG`
  * Defatult: `/usr/local/spmodel`
  * `ARG` にライブラリやモジュール, 実行ファイルのインストール先の
    ディレクトリのプレフィックスを指定します.

* `--host=ARG`
  * クロスコンパイルを行う場合には,
    パッケージが実行されるシステムタイプ名を `ARG` に指定します.

* `--enable-mpi`
  * Defatult: enabled
  * MPI を有効にします. `FC` に
    MPI 用のコンパイラ(例えば mpif90 等)を指定して下さい.

n* `--with-mpiexec`
  * Defatult: none
  * テスト時に使用する MPI 実行プログラムを指定します.

* `--with-mpiexec-opts`
  * Default: none
  * テスト時に使用する MPI 実行プログラムのオプションを指定します.

* `--with-mpiexec-procnum`
  * Default: 4
  * テスト時に使用する MPI 実行プログラムの並列数を指定します.


### ビルド

`configure` が正常に終了したならば,
例えば以下の様に結果のサマリが表示されますので, 内容を確認して下さい. 

```
% export FCFLAGS="-fbacktrace"
% export FC=mpif90.mpich
% ./configure --prefix=$home/gnu2.mpich --with-gt5config=$home/gnu2.mpich/bin/gt5config --with-ispack=$home/gnu2.mpich/lib/libispack3.a --with-lumatrix=OMP --with-lapack=/usr/lib/x86_64-linux-gnu/lapack/liblapack.a --enable-mpi --disable-shared --with-mpiexec=mpirun.mpich --with-mpiexec-opts=-n --with-mint

-----------------------------------------------------------------------
Summary of build options:

version:               1.0.0
Host type:             x86_64-pc-linux-gnu
Install prefix:        /home/takepiro/gnu2.mpich
C Compiler:            gcc
C Flags:               -g -O2
C Preprocessor:        gcc -E
CPP Flags:              -DF03_FEATURE -DLIB_MPI -DEIG_LAPACK -DLUMATRIX_OMP
Fortran Compiler:      /usr/bin/mpif90.mpich
Fortran Flags:         -I/home/takepiro/gnu2.mpich/include -I/usr/include -I/usr/include -O0 -march=native -fopenmp -fno-range-check -fbacktrace
MINT enable:           yes
MPI Support:           yes
MPI Executer:          mpirun.mpich
MPI Executer option:   -n
Linker:                /usr/bin/ld
Linker Flags:          -L/home/takepiro/gnu2.mpich/lib  -L/home/takepiro/gnu2.mpich/lib -L/usr/lib/x86_64-linux-gnu/lapack
Linking Libraries:     -lgtool -L/usr/lib/x86_64-linux-gnu -lnetcdff -Wl,-z,relro -Wl,-z,now -lnetcdf -lnetcdf -lm  -lispack3 -llapack
Eigen Value Solver:    LAPACK
LU Solver:             OMP
SPML Library name:     spml-lapack-omp
-----------------------------------------------------------------------
```

表示された結果が期待通りである場合には

    % make

でビルドが始まります.

### テストプログラム実行

カレントディレクトリにおいて, 以下のコマンドを実行してください.

	$ make check

### インストール

カレントディレクトリで以下のコマンドを実行してください.
システム領域にインストールする場合には管理者権限が
必要です(デフォルトの場合は `/usr/local/spmodel` にインストールします).

	# make install

### spmfrt へのパスの設定

上記のように正しくインストールが行われたら,
`spmconfig`, `spmfrt` というシェルスクリプトが
`--prefix=ARG` で指定されたディレクトリ以下の `bin` ディレクトリ
(`ARG/bin`)に作成されているはずです.
( `--prefix=` を指定しなかった場合は `/usr/local/spmodel/bin/` 以下).
このディレクトリへ `PATH` を通してください.

`spmconfig` は spmodel ライブラリのビルドに利用したコンパイラ等の情報が含まれています. 
これを用いることで, spmodel ライブラリを基盤としたソフトウェアのインストールが簡便になることが期待されています. 

```
This spml 1.0.0 has been built with the following features:

  --fc         -> /usr/bin/mpif90.mpich
  --fcflags    -> -I/home/takepiro/gnu2.mpich/include -I/home/takepiro/gnu2.mpich/include -I/usr/include -I/usr/include -O0 -march=native -fopenmp -fno-range-check
  --ldflags    -> -L/home/takepiro/gnu2.mpich/lib  -L/home/takepiro/gnu2.mpich/lib -L/usr/lib/x86_64-linux-gnu/lapack -L/home/takepiro/gnu2.mpich/lib
  --ldlibs     -> -lspml-lapack-omp -lgtool -L/usr/lib/x86_64-linux-gnu -lnetcdff -Wl,-z,relro -Wl,-z,now -lnetcdf -lnetcdf -lm  -lispack3 -llapack

  --prefix     -> /home/takepiro/gnu2.mpich
  --includedir -> /home/takepiro/gnu2.mpich/include
  --version    -> spml 1.0.0
```

`spmfrt` は `spmcofnig` の情報をベースに, 
spmodel ライブラリを利用した Fortran プログラムを簡単にコンパイル・リンクを行なうためにシェルスクリプトです.
`spmfrt` を用いることで, 自動的に spmodel ライブラリへのリンクとモジュール群へのディレクトリ指定を行ってくれます.

``` 4d
	% spmfrt test.f90
	/usr/bin/mpif90.mpich -I/home/takepiro/gnu2.mpich/include -I/home/takepiro/gnu2.mpich/include -I/usr/include -I/usr/include -O0 -march=native -fopenmp -fno-range-check test.f90 -L/home/takepiro/gnu2.mpich/lib -L/home/takepiro/gnu2.mpich/lib -L/usr/lib/x86_64-linux-gnu/lapack -L/home/takepiro/gnu2.mpich/lib -lspml-lapack-omp -lgtool -L/usr/lib/x86_64-linux-gnu -lnetcdff -Wl,-z,relro -Wl,-z,now -lnetcdf -lnetcdf -lm -lispack3 -llapack

```

@endja
@en
## Set PATH to gt5frt

If the installation is correctly done as stated above,
shell script ((*gt5frt*)) is made under the directory
`--prefix=ARG`/bin
(By default, `/usr/local/gtool5/bin/` ).

Please specify PATH to this directory.
It is an example as follows when ((*gt5frt*)) is installed in
`/usr/local/gtool5/bin/` .

((*gt5frt*)) is a shell script in order to easily compile and link
Fortran programs which utilizes the gtool5 library.
Link to the gtool5 library and directory appointment to the modules
are done automatically by using gt5frt in place of command of the
Fortran compiler.

	$ gt5frt test.f90
    /usr/bin/gfortran -I/usr/local/gtool5/include -I/usr/include -g -O2 test.f90 \
      -L/usr/local/stow/gtool5/lib -lgtool -L/usr/lib -lnetcdff -lnetcdf


@enden
@en
## Prerequisite

To use the gtool5 fortran library, the following software is required.

* Fortran Compiler: support >= fortran 2003 standard.
* [Unidata | NetCDF C Library](http://www.unidata.ucar.edu/software/netcdf/)
* [Unidata | NetCDF Fortran Library](http://www.unidata.ucar.edu/downloads/netcdf/index.jsp)
* Optional: [Doxygen](http://www.stack.nl/~dimitri/doxygen/) : For regeneration of doucments. 

## How to install

### Extract tar.gz

Make an empty directory, and extract archive.
A directory `gtool5-`version`'
created at the current working directory.

	$ tar xvf gtool5_current.tar.gz

### Specify Fortran Compiler

Specify Fortran compiler to environment variable ((* FC *)), e.g.

    % FC=gfortran

Specify Fortran compiler options for optimization and debug to
environment variable `FCFLAGS`, e.g.,

    % FCFLAGS="-g -O2 -fopenmp"

Move created directroy, and excute `./configure`'.

    % ./configure

If you want to change directory to which the library and the module, etc.
are installed, please set `--help` option as follow. Available
options are showed.

	% ./configure --help

Descriptions about principal options are listed below.

* `--with-nf-config=ARG`
  * Default: search `nf-config` from ((:PATH:)).
  * If you want to use another `nf-config`,
    set the location of `nf-config` to `ARG` explicitly.

* `--with-netcdf=ARG`
  * When you can't execute `nf-config`,
    set the location of NetCDF C Library to `ARG` explicitly.

* `--with-netcdff=ARG`
  * When you can't execute `nf-config`,
    set the location of NetCDF Fortran library to `ARG` explicitly.

* `--with-netcdff-include=ARG`
  * When you can't execute `nf-config`,
    set the location of module file `netcdf.mod` to `ARG` explicitly.

* `--prefix=ARG`
  * Default: `/usr/local/gtool5`.
    set prefix to `ARG`.

* `--host=ARG`
  * When cross-compiling,
    set the type of system on which the package will run to `ARG`.

* `--enable-mpi`
  * Default: enable
  * Enable MPI support.
    Set MPI Fortran Compiler to ((:FC:)), e.g. mpif90.

* `--with-mpiexec`
  * Default: none
  * Set MPI execute program for test.

* `--with-ncdump`
  * Default: search ((:ncdump:)) from ((:PATH:)).
  * Set ((:ncdump:)) for test.

@enden


[autoconf]: https://www.gnu.org/software/autoconf/autoconf.html
[automake]: https://www.gnu.org/software/automake/
[libtool]: https://www.gnu.org/software/automake/
[ERBja]: https://docs.ruby-lang.org/ja/3.1/library/erb.html
[ERBen]: https://docs.ruby-lang.org/en/3.1/library/erb.html