SATySFi インストール手引き 2021年5月版

さて、[SATySFi](https://github.com/gfngfn/SATySFi) インストールバトルは未だに決定版の攻略法が世に広まっていない。そこで、自作パッケージマネージャー（マネージするとは言っていない）である [Satyrographos](https://github.com/na4zagin3/satyrographos) を用いた SATySFi インストール法を解説したい。

本稿で対象とする環境は、POSIX 系で OCaml が動く環境、例えば、Windows (Cygwin) や macOS (又称 Mac OS X) や Ubuntu 等である。Windows Subsystem for Linux (WSL) でも同様になるとは思うが、動作環境を持っていないため、定かでは無い。求情報。

本稿では、まず、使用者が参考とすべき公式文献を挙げ、次に、他のインストール方法解説、その次の節より、2021年4月23日現在における、一般の POSIX デスクトップ環境へのインストール方法を詳説する。

**上手く行かなかった場合は、コメント欄にその旨報告してほしい。**

## 改訂履歴
- 2019-01-14T06:06+09:00 初稿
- 2019-01-14T13:46+09:00 WSL で bwrap が動かないことを macOS 上の問題と誤認していた記述を修正
- 2019-02-16T00:37+09:00 2019-02-10 にインストール方法が変更されたものについての加筆
- 2019-12-07T00:54+09:00 satysfi-lib-dist から satysfi-dist への改名を適用
- 2020-08-11T00:48+09:00 SATySFi 0.0.5 が OCaml 4.10.0 以降を要求することに伴う変更
- 2020-08-11T01:06+09:00 Cygwin に関する記述を追加
- 2020-10-11T01:16+09:00 Windows 環境で Windows Subsystem for Linux 2 (WSL 2) を推奨するように
- 2020-11-22T20:00+09:00 Windows 環境で Windows Subsystem for Linux 2 (WSL 2) を推奨するように
- 2021-02-20T01:00+09:00 表題の変更並びに流れを追い易くする改善
- 2021-04-23T11:10+09:00 `opam depext` を追加
- 2021-05-22T18:12+09:00 `opam init` で switch が作成されない場合への対処を追加

## 公式文献
☃☃☃**[SATySFi Wiki](https://github.com/gfngfn/SATySFi/wiki)**☃☃☃

### インストール関連
- [SATySFi Wiki](https://github.com/gfngfn/SATySFi/wiki) に[インストール方法](https://github.com/gfngfn/SATySFi/wiki/%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)が解説されている
- [/README-ja.md](https://github.com/gfngfn/SATySFi/blob/master/README-ja.md) 日本語README
- [/memo-ja-how-to-use.md](https://github.com/gfngfn/SATySFi/blob/master/memo-ja-how-to-use.md)ライブラリルート解説文書

### 言語機能
- [The SATySFi​book Web公開版 第1版](https://github.com/gfngfn/SATySFi/wiki/The-SATySFi%E2%80%8Bbook-Web%E5%85%AC%E9%96%8B%E7%89%88-%E7%AC%AC1%E7%89%88)
- [doc/doc-primitives.saty](https://github.com/gfngfn/SATySFi/blob/master/doc/doc-primitives.saty) プリミティブの解説
- [doc/doc-lang.saty](https://github.com/gfngfn/SATySFi/blob/master/doc/doc-lang.saty) 言語の解説

## 偉大なる先駆者
- @puripuri2100 [Ubuntu on WSL にSATySFi v0.0.3 を導入する](https://qiita.com/puripuri2100/items/70f368d62d41b982017a)
- @shiba44 [windowsでSATySFiの環境構築](https://qiita.com/shiba44/items/a9d33ea058016eaa5565)
- @ogata-k [Ubuntu 18.04.1 LTSでSATySFi 0.0.3をインストールしてみる](https://qiita.com/ogata-k/items/8238ea10903c8bc62532)
- @pochiMasahiro [SATySFIはじめてみる](https://qiita.com/pochiMasahiro/items/91f2eecbffaf85c3f2a3)
- @aomidro [macでSATySFiのデモファイルからPDFファイルを生成するところまで](https://qiita.com/aomidro/items/9b8d66a51e81931f1c98)

## OPAM のインストール
SATySFi は OCaml にて記述されており、OCaml 環境が必要となる。そこで、OCaml 用のパッケージマネージャー＋α（Python で言う所の pip + pyenv や Haskell で言う所の stack + cabal に当たる）である所の [OPAM](https://opam.ocaml.org/) を、先ずインストールしてやる必要がある。

OPAM のインストールに関しては [公式の解説](https://opam.ocaml.org/doc/Install.html) が存在する。ここでは、ユーザーベースの大きさを加味して、Cygwin 向けと、WSL も含む Ubuntu 向けと、macOS 向けの記述を概説する。

### Windows における OPAM のインストール方法
WindowsでOPAMを使用する方法は主にWSL 2とCygwinがある。Windowsネイティブ版は2020年10月現在未サポートである (https://github.com/ocaml/opam/issues/246)。

#### WSL 2

[Ubuntu における OPAM のインストール方法](#ubuntu-における-opam-のインストール方法) に従う。

#### Cygwin

Cygwin のインストール方法は https://www.sw.it.aoyama.ac.jp/2011/CP1/cygwin/ を参考にするとよい。

[OPAM は Cygwin のパッケージとして提供されている](http://cygwin.com/packages/summary/opam.html)ので、インストーラーからほかのパッケージ同様インストールすることができる。

以下のパッケージをインストールする必要がある。

- opam

Windows のホームディレクトリとは別の場所に Cygwin のホームディレクトリが作成されるので、Windows のホームディレクトリへのシンボリックリンクを `~/winhome` に、ドキュメントフォルダへのシンボリックリンクを `~/documents` に作成すると便利である。

```shell-session
$ ln -s "$(cygpath "$HOMEDRIVE$HOMEPATH")" winhome
$ ln -s "$(cygpath -O)" documents
```

[次はSATySFiの設定をしよう。](#opam-の設定--ocaml-のインストール)

### [Ubuntu における OPAM のインストール方法](https://opam.ocaml.org/doc/Install.html#Ubuntu)

#### Ubuntu 19.10 以後
Universe に [OPAM 2.0.5](https://repology.org/project/opam/versions) が用意されているため、これを用いてインストールすれば宜しい。

```
$ sudo apt update
$ sudo apt install opam
```

[次はSATySFiの設定をしよう。](#opam-の設定--ocaml-のインストール)

#### Ubuntu 18.04
OPAM 用の ppa が用意されているため、これを用いてインストールすれば宜しい。

```
$ sudo add-apt-repository ppa:avsm/ppa
$ sudo apt update
$ sudo apt install opam
```

[次はSATySFiの設定をしよう。](#opam-の設定--ocaml-のインストール)

#### Ubuntu 18.04 よりも前
バイナリを直接ダウンロードすることが推奨されている。この際、OCaml 本体やその他ライブラリなどのビルドに必要なパッケージもインストールする必要があるので、ここでやってしまおう。

```shell-session
$ sudo apt-get update
$ sudo apt-get install build-essential git m4 unzip curl

$ sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)
```

[次はSATySFiの設定をしよう。](#opam-の設定--ocaml-のインストール)

### macOS における OPAM のインストール方法
Homebrew を使っているならば、[単純に gpatch と opam をインストールすれば良い](https://opam.ocaml.org/doc/Install.html#OSX)。

```shell-session
$ brew install gpatch
$ brew install opam
```

[次はSATySFiの設定をしよう。](#opam-の設定--ocaml-のインストール)

## OPAM の設定 & OCaml のインストール
OPAM は pyenv のようなものなので、利用する OCaml のバージョンによって、シェル上において PATH 等の環境変数を変更する必要がある。`opam init` を実行することによって、利用しているシェルの設定ファイルに必要な記述を追加させたりすることができる。

また、初期設定時に一緒に OCaml をインストールすることができる。2020 年 8 月現在 SATySFi で公式にサポートされているのは OCaml 4.10.0 なので、もし問題が発生した場合にはこれに切り替えると円滑に進むことだろう。設定方法は次節を見よ。

ここで注意せねばならないこととして、WSL1 等では [bwrap による<ruby>砂場機能<rp>(</rp><rt>サンドボックス</rt><rp>)</rp></ruby>](https://opam.ocaml.org/doc/FAQ.html#Why-does-opam-require-bwrap)が上手く動かないことが知られている（見 [ocaml/opam-repository#12050](https://github.com/ocaml/opam-repository/issues/12050)）。従って、無効化する `--disable-sandboxing` オプションを必要とする。

纏めると、以下のコマンドを打つ必要がある

WSL1 等 bwrap が上手く動かない OS 向けには

```
$ opam init --disable-sandboxing
$ eval $(opam env)
```

そうではない OS 向けには

```
$ opam init
$ eval $(opam env)
```

を実行すること。

### OPAM インストール後の確認

OPAM インストール後に `opam switch list` を実行し、switch の一覧が表示されれば成功である。

```
$ opam switch list
#   switch                     compiler                    description
    4.06.1                     ocaml-base-compiler.4.06.1  4.06.1
    4.07.1                     ocaml-base-compiler.4.07.1  4.07.1
    4.08.1                     ocaml-base-compiler.4.08.1  4.08.1
    4.09.0                     ocaml-base-compiler.4.09.0  4.09.0
    4.09.1                     ocaml-base-compiler.4.09.1  4.09.1
    4.10.0                     ocaml-base-compiler.4.10.0  4.10.0
->  ocaml-base-compiler.4.11.1 ocaml-base-compiler.4.11.1  ocaml-base-compiler.4.11.1
```

以下のように、switch が一つも存在しない場合には、`opam switch create` で新規 switch を作成すること。

```
$ opam switch create
# switch  compiler  description
```

OPAM switch についての解説は次項を見よ。

## （余談）OCaml のバージョン切り替え
OPAM は複数のバージョンの OCaml を同時にインストールし、切り替えて使うことができる。現在のバージョンは

```
# OPAM に管理されている OCaml 環境一覧
$ opam switch

# 現在の OCaml のバージョン
$ ocaml --version
```

で確認できる（はずである）。

例えば、OCaml 4.07.1 をインストールし、そちらに切り替えたい時には、[`opam switch` コマンド](https://opam.ocaml.org/doc/Usage.html#opam-switch)を用いる。

```
# OCaml 4.11.0 環境を構築
$ opam switch create 4.11.0
# 又は
$ opam switch create ocaml-base-compiler.4.11.0

# OCaml 4.11.0 環境に切り替え
$ opam switch 4.11.0
$ eval $(opam env)
```

既に構築してある環境に切り替えるには、単に `opam switch` をするだけで良い。

```
# OCaml 4.10.0 環境に切り替え
$ opam switch 4.10.0
$ eval $(opam env)
```

## 外部レポジトリの設定
SATySFi は、公式の OPAM レポジトリには登録されていないライブラリを使用する。ここでは、satysfi-external という名前で、外部レポジトリを追加する。

```
$ opam repository add --all-switches satysfi-external https://github.com/gfngfn/satysfi-external-repo.git
```

また、SATySFi 用パッケージマネージャーである Satyrographos も外部レポジトリにてパッケージを管理するので、こちらも追加する。

```
$ opam repository add --all-switches satyrographos-repo https://github.com/na4zagin3/satyrographos-repo.git
```

## SATySFi のインストール
ようやく事前準備が終わったのでインストールする。ついでに、Satyrographos もインストールしてしまおう。

```
# SATySFi 本体 ＋ 標準ライブラリ ＋ Satyrographos の依存システムパッケージをインストール
$ opam depext satysfi satysfi-dist satyrographos

# SATySFi 本体 ＋ 標準ライブラリ ＋ Satyrographos をインストール
$ opam install satysfi satysfi-dist satyrographos
```

これで SATySFi 本体や付属フォント等々が、OPAM 管理下のディレクトリにインストールされることとなった。

ここでインストールされる satysfi のバージョンは、[私が定期的にとっているスナップショット](https://github.com/na4zagin3/satyrographos-repo/tree/master/packages/satysfi)である。

[さぁSATySFiを動かそう。](#satysfi-ライブラリルートへのインストール)

### 開発版を試したい場合
最新の master ブランチや、その他の feature ブランチを試したい場合には、SATySFi のレポジトリをローカルに `git clone` し、そのディレクトリを `opam pin add` した上で、`opam install` することになる。以下のようにすれば良い。

```
$ cd 好きな場所
$ git clone https://github.com/gfngfn/SATySFi.git
$ cd SATySFi

$ git checkout <好きなブランチ>
$ opam pin add .
$ opam install satysfi
```

`opam pin add .` によって、現在のディレクトリの git レポジトリの HEAD がビルドされインストールされることになる。現在のディレクトリ（ワークツリー）をビルドしたい場合には、`.` ではなく `file://$PWD` を<ruby>ピン留め<rp>(</rp><rt>opam pin</rt><rp>)</rp></ruby>する。

```
$ opam pin "file://$PWD"
$ opam install satysfi
```

その後は README.md に従って作業することとなる。

もし、ローカルの SATySFi を使うのをやめ、satyrographos-repo から提供される SATySFi に戻したい場合は、`opam pin remove` をすれば良い。

```
$ opam pin remove satysfi
```

[さぁSATySFiを動かそう。](#satysfi-ライブラリルートへのインストール)

## SATySFi ライブラリルートへのインストール
SATySFi は、[フォントやリソースやパッケージ等の各種ファイルが `~/.satysfi` 以下にあることを要請している](https://github.com/gfngfn/SATySFi/blob/e1419e0dfa41ff065b0f49701c2dffe04b8b85f4/memo-ja-how-to-use.md)ので、OPAM 管理下にあるファイルをコピーする必要がある。Satyrographos はこれをやってくれるものである。（システムにインストールされているフォントを SATySFi から使用可能にしたりする機能等もあるが、その紹介はまた後日）

```
$ satyrographos install
```

現在の所、`satyrographos install` は SATySFi をアップデートする度に行う必要がある。

## ドキュメントのコンパイル
`demo` や `doc` にあるファイルを処理してみると良いだろう。

以下の問題は 2019-02-08 に [PR#137](https://github.com/gfngfn/SATySFi/pull/137) にて修正された。

> https://github.com/gfngfn/SATySFi には、SATySFi で書かれたファイルが幾つか存在するのだが、2019年1月14日現在、[demo/demo.saty は画像ファイルの不足によりコンパイルできないことが知られている](https://github.com/gfngfn/SATySFi/pull/72)。代わりに、[doc ディレクトリ](https://github.com/gfngfn/SATySFi/tree/master/doc) 以下のファイルで試すことを勧める。
>
> demo/demo.saty をコンパイルしたい場合には、@ogata-k [Ubuntu 18.04.1 LTSでSATySFi 0.0.3をインストールしてみる「世界への挨拶」節](https://qiita.com/ogata-k/items/8238ea10903c8bc62532#%E4%B8%96%E7%95%8C%E3%81%B8%E3%81%AE%E6%8C%A8%E6%8B%B6)後半にあるように、画像ファイルをダウンロードしてきて配置をすれば、正常にコンパイルできるようになる。

## アップデート・アンインストール
SATySFi のアンインストールは

```
$ opam uninstall satysfi
```

アップデート（<ruby>ピン留め<rp>(</rp><rt>opam pin</rt><rp>)</rp></ruby>していない時）は

```
$ opam update satysfi
```

再インストール（<ruby>ピン留め<rp>(</rp><rt>opam pin</rt><rp>)</rp></ruby>している時）は

```
$ opam reinstall satysfi
```

とすれば良い。


## むすび
この文書が、読者の幸せな SATySFi <ruby>生活<rp>(</rp><rt>ライフ</rt><rp>)</rp></ruby>の一助となれば幸いである。

もし、内容に誤りや不明瞭な点を見つけられたり、また、詰まってしまった場合には、コメント欄にてお教えくだされば、修正・明確化等致したく思いますので、是非とも宜しくお願いします。