Notification
これは 2019 年１２月ゴロに書いた記事ですが.
2020年 9 月現在 の Julia 1.5 系でも動作できるはずです．適宜読み替えてください．
本日は
-
アドベントカレンダー空いていたので書きました．
-
２０１９年クリスマスシーズンからプログラミング言語 Julia を始めるため，第１歩からN(>=1)歩進む手引き
を書きましたがみなさん真に N > 1 歩進みましたでしょうか？
-
２０１９年クリスマスシーズンからプログラミング言語 Julia を始めるため，第１歩からN(>=1)歩進む手引き
-
以前，PkgTemplates.jl をベースに Julia のパッケージを開発する方法を書きました．
これによると
- Travisを用いたCIやパッケージのドキュメントをGitHubのリポジトリでホスティングできるようになります．
- (もちろん Julia のPkgを用いて generate することもできますが PkgTemplates.jl はこの作業を簡略化してくれます．)
今回は
- Travis でしていたようなワークフロー（Pull Requestしたときにその内容がテストを通るか，masterブランチにマージされたときにdevのドキュメントを生成し
github.ioで公開する作業）を GitHub Actions で賄うようにします． - そして開発作業を Docker コンテナの内部で閉じれるようにする．具体的にはホスト環境に Julia，が導入されていなくても
- Jupyter Notebook を手元のブラウザ上で閲覧し Julia を実行する
- REPLベースで Julia を動かすようにする
- ドキュメントを生成しそれを手元のブラウザ上で閲覧するようにする
はじめよう
PkgTemplates.jl の導入
- PkgTemplates.jl の 0.7 を導入します．これは GitHub Actions のテンプレートを生成するために必要です.
- 2019/12/21 現在では 0.6 が安定版になっていますので．master ブランチの物を導入します．
Pkg> dev PkgTemplates
Pkg> st
...
...(いくつかパッケージとそのバージョンが並ぶ)
...
PkgTemplates v0.7.0-DEV [`~/.julia/dev/PkgTemplates`]
...
...（0.7.x になっていれば OK）
...
テンプレートの準備
- 下記のようなスクリプトを書きます．そしてそれを実行します．
using PkgTemplates
t = Template(;
dir="~/work",
julia=v"1.3",
plugins=[
License(; name="MIT"),
Git(; manifest=false, ssh=true),
GitHubActions(),
Documenter{GitHubActions}(),
],
)
t("MyWorkflow")
t にいれる文字列は将来あなたのパッケージの名前になるものになります．
-
以前はパッケージが生成される場所は
~/.julia/dev固定でしたが dir でどこに置くのかを指定できます． -
pluginsには- ライセンス(ここでは MIT ライセンスとしている)
- Git の設定
- リモートは個人的にSSHを使うため true を指定
-
Manifest.tomlを初期コミットに含めない - GitHub Actions を使うためのおまじない
を含めておきます．
-
t("MyWorkFlow")を実行すると~/work/MyWorkflowが生成されます．
これでほぼ完成です．PkgTemplates による Julia パッケージの作り方（後半） と同様にリモートのリポジトリの受け皿を生成してそれに向けてローカルリポジトリをpushすればOKです．プッシュしたあと
Actions に行って CI が流れていればOK．これでGitHub Actionsで自動テストをする基盤が出来上がります．
DocumenterTools からドキュメント生成の Token を入手
- PkgTemplates による Julia パッケージの作り方（後半） で述べているようにデプロイキーと DOCUMENTER_KEY を生成します．これらは DocumenterTools.jl を用いて生成されます．
-
DOCUMENTER_KEYを リポジトリの Settings -> Secrets -> に進み DOCUMENTER_KEY を追加します． - デプロイキーも Deploy keys に documenter という名前で追加します．要するにTravisでやっていた秘密の呪文をGitHubの方に入れただけですね．
これでパッケージ生成してGitHub Actions と連携することができました．GitHub Actions で何がやっているのかを知るには
MyWorkflow/.github/workflows 直下に ci.yml というのがあるのでそれを眺めてください．
- https://github.com/marketplace/actions/setup-julia-environment を見ると理解が深まるかもしれません．
ここから Docker の導入，カスタマイズしていく
- リポジトリ直下に次を追加します:
ただ追加するだけですので，既存のパッケージにも使えるはずです．
- リポジトリが重くなるとコンテキスト作成に時間がかかるので .dockerignore を使ってDockerイメージ生成に不要なディレクトリを追加しておくと良いでしょう．
- Jupyter notebook と連携させることを考えると必要に応じてPython，Jupyterが生成する不要な物をバージョン管理から外すために .gitignore を追加しても良いでしょう．ちなみに GitHubで生成される
.gitignoreの Julia 版はこちらから入手できます．
カスタマイズ後の開発ワークフロー
まずはビルド
リポジトリ直下に移動して make build を実行します．これは Docker または Docker-compose を利用する際に用いるイメージをビルドします．これはターミナルで次を実行することと等価です．
$ docker-compose build
$ docker build -t myjulia .
$ docker-compose run --rm julia julia --project=. -e 'using Pkg; Pkg.instantiate()'
- 最後の三行目はローカルのJuliaで次を実行することとに対応しています．
$ julia
julia> ] # switch to Pkg mode
pkg> activate
pkg> instantiate
- instantiate は
Manifest.tomlを生成・更新するために使われます．既存のパッケージで Manifest.toml がバージョン管理されている時は instantiate は省いても良さそうです．各自の環境に応じて使い分けてください．
実行（通常のREPLのようにして）
手元の環境が Docker または Docker Compose が整っていれば手元にJulia環境がなくても次のように Julia をコンテナ内で動かすことができます．
$ docker-compose run --rm julia
_
_ _ _(_)_ | Documentation: https://docs.julialang.org
(_) | (_) (_) |
_ _ _| |_ __ _ | Type "?" for help, "]?" for Pkg help.
| | | | | | |/ _` | |
| | |_| | | | (_| | | Version 1.3.0 (2019-11-26)
_/ |\__'_|_|_|\__'_| | Official https://julialang.org/ release
|__/ |
julia> using Example
julia> names(Example)
3-element Array{Symbol,1}:
:Example
:domath
:hello
julia> hello("World")
"Hello, World"
- References:
実行 (通常の Jupyter Notebook のようにして)
- 次を実行すると手元のブラウザ上で
localhost:8888にアクセスすることで Jupyter 上で Juliaが動きます．
ちなみに上で紹介した Dockerfile は jupytext で ipynb 形式を jl 形式にしてバージョン管理しやすくなっています．
使いかは下記の References を参考にしてください． ipynb はバージョン管理せず対応する jl ファイルをバージョン管理する方式をとる感じです．
$ docker-compose up jupyter
...
... (いくつかメッセージが流れる)
...
ドキュメントを閲覧したい
- 次を実行すると手元のブラウザ上で
localhost:8000にアクセスすると見られます．
docker-compose up web
...
... コンテナ内でJuliaが起動しドキュメントが生成される
...
何も書いてないので下記のようなページのみが表示されます．
以上
まとめ
- PkgTemplates.jl の新しい機能を先取りしました．GitHub Actions を用いてCIを進める基盤を作ることができました．
- Dockerで開発をとじるワークフローを提案しました．
- ここでは書いてませんが，起動したコンテナにJuliaIDEのJunoと連携することも確認済みです．
- See Julia v 1.1.0 の Docker を拡張して Jupyter と Atom から利用できるようにしよう to learn more.
- VSCodeを使うとコンテナとの連携がしやすくなるようですのでそれに乗っかるというストラテジーでも良いと思います．