Julia でのパッケージの作り方

自分が作ったパッケージ

https://github.com/cometscome/TightBinding.jl

が無事公式パッケージになりましたので、公式パッケージにするにはどうすればいいのか、書いていきたいと思います。

なお、goropikariさんの

「Julia - パッケージ作り」

https://goropikari.hatenablog.com/entry/julia_make_package

が大変参考になりました。


バージョン

Julia 1.1


オリジナルパッケージの雛形を作る

まず、PkgTemplates.jlを使って、パッケージの雛形を作ります。

Juliaを起動し、]を押してパッケージモードにしてから、

add PkgTemplates

でPkgTemplates.jlをインストールします。

https://github.com/invenia/PkgTemplates.jl

次に、

using PkgTemplates

t = Template(;
user="myusername",
license="MIT",
authors=["Seimei Abe"],
dir="./code",
julia_version=v"1.0",
plugins=[
TravisCI(),
Codecov(),
Coveralls(),
],
)

として、Templete()に必要な情報を入れます。

次に、

generate("TestPkg",t)

としてパッケージTestPkgの雛形を作成します。

上記の設定では、今いるディレクトリにcodeというディレクトリが作られ、そこにTestPkgというディレクトリが作成されると思います。

このディレクトリの中身は、

LICENSE     Project.toml    REQUIRE     test

Manifest.toml README.md src

のような形になっているかと思います。ここでsrcディレクトリの中身には、TestPkg.jlというファイルが作られていると思います。このファイルを編集することでパッケージを作る事ができます。

最初の状態では、

module TestPkg

greet() = print("Hello World!")

end # module

となっていますので、このmoduleの中身を書けば良い、ということになります。


パッケージの作成

TestPkg.jlを編集して新しいパッケージを作ります。例えば、

module TestPkg

using SparseArrays
export test
function test()
A = spzeros(Float64,5,5)
A[1,3] = 4
A[2,5] = 9
return A
end
end # module

というものを作ってみました。ここでは、疎行列に関連するパッケージであるSparseArraysを用いています。このように、Juliaの別のパッケージを利用する場合には、そのパッケージを利用することをはっきりとProject.tomlというファイルに書き込む必要があります。しかし、これは簡単にできます。

一度Juliaを終了し、TestPkgディレクトリに入ります。そしてそこでJuliaを起動してください。

そして、]を押してパッケージモードにして、

activate .

とします。すると

(v1.1) pkg> 

だったものが、

(TestPkg) pkg>

に変わると思います。

そして、自分が使うパッケージ、例えば、SparseArraysが必要であれば、

add SparseArrays

とします。これで、Project.tomlに必要な情報が書き込まれます。

なお、delキーを押してパッケージモードを終了した後、

using TestPkg

とすると読み込む事ができます。なお、moduleの中でexport testとしたので、test()

test()

とそのまま実行する事ができます。

あとは適宜パッケージを追加するなどをして、自分のパッケージを作ってみてください。


testを作る

次に、そのパッケージがちゃんと動いているかを確かめるためのテストのコードを書きます。テストは、testディレクトリの中のruntest.jlを編集して作ることになります。

例えば、

using TestPkg

using Test

@testset "TestPkg.jl" begin
A = test()
@test A[1,3] == 4
# Write your own tests here.
end

という形にしてみましょう。このコードでは、testとして、A[1,3]が4かどうかを調べています。

TestPkgディレクトリでJuliaを起動し、]を押してパッケージモードにしてから

activate .

test

とすると、runtest.jlが実行されます。

無事に走れば、

(TestPkg) pkg> test

Testing TestPkg
Resolving package versions...
Test Summary: | Pass Total
TestPkg.jl | 1 1
Testing TestPkg tests passed

などと出ます。これでテストコードも完成です。


GitHubへの登録

GitHubへリポジトリを登録して、ここで作ったファイル一式をアップロードしましょう。

やり方は様々なページがありますので、ここでは割愛します。

ここまでやれば、野良パッケージ(公式ではないパッケージ)は完成です。

他の人にパッケージを使ってもらいたい場合には、]を押した後のパッケージモードで、

add [GitHubのURL]

とすれば、入れてもらう事ができます。


README.mdの作成

すでにファイルはあると思いますので、ここにパッケージの説明を英語で記入してください。


Travis CIの登録

公式パッケージにして、パッケージ名だけでaddできるようにしたい場合には、Travis CIの登録が必要なようです。

Travis CIについては、例えば、

https://knowledge.sakura.ad.jp/3754/

が参考になるかと思います。

やることは、

https://travis-ci.org

で「Sign in with GitHub」をクリックし、GitHub連携をします。「Authorize application」をクリックすれば良いです。

これで、.travis.ymlというファイルが存在するリポジトリのtestチェックができるようになります。

このファイルは実はすでに作られていて、中身は、

language: julia

os:
- linux
- osx
julia:
- 1.0
- nightly
matrix:
allow_failures:
- julia: nightly
fast_finish: true
notifications:
email: false
after_success:
- julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
- julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Coveralls.submit(process_folder())'

こんな感じになっていると思います。この状況だと、linuxおよびMacのOS Xにおいて、Juliaの1.0とnightly buildにおいてtestを実行する形です。もし1.1のtestを追加したければ、

julia:

- 1.0
- 1.1
- nightly

と1.1を追加してください。

ここまで設定すると、次にgitでGitHubのリポジトリにコミットした時には、runtest.jlがlinuxとosxの環境で自動実行され、その時の結果が返されます。

こちらのサイト

https://rcmdnk.com/blog/2014/09/08/computer-github-travis/

を参考にすると良いと思います。

最後に重要なことは、「バッジを貼る」です。

README.mdにバッジを貼る事で、そのパッケージがテストを通っていることが一目でわかるようになります。公式パッケージにする場合には重要です。


Coverallsの設定

次に、テストがコード全体のどのくらいをテストしたかを示すバッジを貼りたいので、

https://rcmdnk.com/blog/2014/09/09/computer-github-travisci/

を参考に設定してみてください。

coverallsのサイト

http://coveralls.io

に行って、GitHub連携をすれば問題ありません。


AttoBotの登録

最後に、公式パッケージにするためにはGitHubにAttoBotを登録します。

https://github.com/attobot/attobot

このページ

https://github.com/integration/attobot

に行き、Configureボタンを押します。そして、公開したいパッケージのリポジトリを選択します。


リリースの登録

AttoBotを登録すると、あとはリリースをするだけでAttoBotが自動的にJuliaのMETADATA.jlにプルリクエストをしてくれます。

https://github.com/attobot/attobot

に絵があるのでわかりやすいです。

GitHubの自分のリポジトリのページで、「releases」をクリック。「Draft new release」をクリック。tagとして、v0.1.0などと書きます。なお、ここのバージョンは、Project.tomlファイルにあるバージョンと合わせるべきだと思います。概要など必要事項を書いたら、「Publish release」をクリック。これで公式パッケージにしたいという要請がJuliaのMETADATA.jlに飛びます。

https://github.com/JuliaLang/METADATA.jl/pulls

に自分のパッケージが出てきているか確認しましょう。タイトルの横のチェック印が緑になるように、適宜エラーメッセージを見てみましょう。もしuuidがどうこうでエラーが出ていた場合には、そこに書いてあるuuidをコピーして、Project.tomlに書かれているuuidを書き換えて再度リリースしなおすとエラーが消えるかもしれません。

もし、微妙に変えたいとかなんかうまく行っていないという時には、

リリースを削除してから同じtagで再度リリースをすると、AttoBotがプルリクエストの部分に追記してくれます。

あとは、適切にコメントに返信する、返信がなければそのまま、3日が経つと、自動的にそのパッケージは公式パッケージになります。見た感じ、名前がわかりにくいとか、類似パッケージと同じでは、などというコメントが出ていますので、そのような場合には適切に対処しましょう。


公式パッケージ登録

3日経ち、何事もなければ、パッケージは公式パッケージとなり、

add TestPkg

で入れられるようになります。