MATLAB File ExchangeとGitHubを連携したコード公開
はじめに
自作MATLAB関数を公開をGitHubを通じてFile Exchangeに公開しました。
内容についてはこちらの記事もご覧ください。
この記事では、File Exchangeについて簡単に紹介し、その手順を簡単に解説します。
前提としてGitやGitHubの簡単な動作はできているものとして、それらの詳細は割愛します。ご自身のGitHubアカウントを作られており、新規リポジトリが作成できて、Gitコマンドとしてはclone
、add
、commit
、push
くらいできていれば大丈夫です。普段GitHubを使っている方も新たな発見があれば幸いです。
File Exchageとは
File Exchangeでは、MATLABで作成した自分のプログラムを世界中の他の方々に手軽に使っていただくことができます。また、私のように複数のパソコンでMATLABを使用するような用途では、異なるパソコン間で自作関数を共有するのに非常に便利です。
ソースコード公開としてはGitHubによる公開が主流であるかと思われますが、これはソースコード管理が主たる役割であり、ファイルのダウンロードやMATLAB上でのパスの設定、インストール済みの追加ソフト(アドオン)一覧確認など、インストール作業に関してはFile Exchangeを通すことでMATLABがある種自動で実行または管理してくれます。以降では、このGitHubとFile Exchangeを連携して、ソースコードを配布する方法について示します。
GitHubでの公開
まずは、GitHubでリポジトリを作成して、ソースコードをアップロードします。
必要なファイルはソースファイル、READMEファイル、LICENSEファイルの3つです。
以下のファイルを含んだGitHubリポジトリを作成しましょう。完成例は以下のリポジトリをご覧ください。
ソースファイル
まず、公開したいソースコードを用意します。
ライブスクリプトファイル(.mlx)も公開可能ですがこれはバイナリファイルであるため、ソースコードの変更履歴を追えるスクリプトファイル(.m)で公開する方が個人的には好みです。スクリプトで作成した関数の最初にはコメントアウトで関数の説明を行います。例としては以下のとおりです。
これによりdoc
コマンドやhelp
コマンドでこの説明を表示させることができます。動作や引数、参考Webページなど必要な情報をコンパクトにまとめてください。
%%
で始める行はセクションタイトルとなってくれます。
ライブスクリプトファイルでも、同様に説明を付けることができます。ライブスクリプトファイルを公開した例は以下にありますので、ご興味がある方はこちらもダウンロードしてみてください。
READMEファイル
READMEファイルには、このソースコードの説明を書きます。
関数最初のコメントアウトよりたくさんの情報を掲載できます。
ロゴの使用
[](https://jp.mathworks.com/matlabcentral/fileexchange/176183-pomodoro-timer)
のように記載することで、File Exchangeのロゴを使用したリンクを作成できます。リンク先のURLはご自身が公開したページに変更する必要があることに注意してください。しかしながら公開ページリンクは公開しないと決まらないため、ここは公開後に再編集することになります。File exchangeでの公開の章で再度ご説明いたします。
画像の挿入
画像についてはGit管理に加えていただいても構いませんが、リポジトリサイズを小さく保つために、ブラウザ上のGitHubにドラッグアンドドロップで追加することもできます。
Edit
の状態でドラッグアンドドロップして、完了したあとはPreview
で確認しましょう。
問題なければCommit
して変更を反映させてください。
いずれにしても違和感がない程度に画像ファイルは小さくしたほうが良いです。
LICENSEファイル
自分のソースコードの再配布を許可したり不備による損害を免責したりするために、ライセンスファイルを追加しておくことをオススメします。私は趣味で公開する場合にはMITライセンスを使うことが多いですが、個人の好みやニーズによって適切なライセンスを付加しましょう。自分で作っていただいても構いませんが、有名ライセンスから選択するのが公開者側も利用者側も楽だと思います。
GitHub Repositoryを作成する際に選択して自動生成させることも可能です。
File exchangeでの公開
File exchangeでは直接ファイルアップロードして公開することもできますが、上記で整備してきたGitHubリポジトリと連携させると管理が楽になります。
GitHub連携
以下のページから、ご自身のMathWorksアカウントでログインしてください。
つぎに、New Submission
ボタンからファイルをおきます。置き方はGitHub連携と直接アップロードする2通りがあります。
もちろんここではGitHub連携をしていきましょう。ここのCheck your settings in GitHub
をクリックして連携するリポジトリを選択してください。MATLAB and Simulink Integrationをインストールしましょう。公式の説明(英語)は以下にあります。
ここの例では、すべてのリポジトリを許可しておりますが、個人的には必要なリポジトリだけ許可を与えております。
ここで許可を与えるとNew Submission
ボタンから該当リポジトリを選択できるようになったかと思います。
ブランチとリリースのどちらで公開するかを選択できます。慣れていればリリースで公開したほうがよいと思います。いずれにしても設定から変更することが可能です。設定したブランチに新しいコミットや新しいリリースを作ると自動的に最新のコードに更新されます。「新しいGitHubリリースを作成すると、このページが更新されます。更新には、最大で1時間ほどかかる場合があります。」と案内がありますが、体感として数十秒から数分くらいで反映されていそうな雰囲気です。
公開情報の設定
公開情報の設定画面は以下の通りです。
直感的に設定できると思いますが、以下のような項目があります。
- Image: 画像を設定できます。File Exchageで検索したときのサムネイルになるため、その関数の動作がつかめるような画像がよいでしょう。
- Description: GitHub連携がされていればREADME.mdの内容が転記されます。書き直したい場合には
Use README.md from GitHub
でオフにすることもできそうですが、したことはありません。 - Tags: タグ。適切なタグを付けていると見つけてもらえるかもしれません。
- Cite As: 文献やWebサイトなど引用してほしい文献があれば載せておきましょう。デフォルトではGitHubのリンクが入るようです。
- Acknowledgments: 謝辞。とくになければ空欄でよいと思います。
- GitHub Integration: ブランチとリリースのどちらで公開するかを変更できます。
- Required MathWorks Products: 必要なツールボックスなどがあれば記述してください。
- MATLAB Release Compatibility: どのバージョンで実行可能かを示します。
Compatible With
を設定したい場合には公開するコードで使用している関数がどのバージョンから実行可能であるかなどを注意してみてください。 - Platform Compatibility: どのOSで実行可能かを示します。OS依存の実装をしていなければ基本的にチェックを入れてしまって問題ないかと思います。
これらを右上のpublish
を押せば、更新完了です。もちろん、あとから変更することも可能です。File Exchangeのマイファイルをクリックして、設定を変更したいソフトのManageから「編集」をクリックしてください。
ここで公開が完了することでFile ExchangeのURLが決定されます。READMEファイルのご説明にあったように、URLの追記または変更を行ってください。
インストールと管理
ここでは公開したプログラムを個々のパソコンにインストールする方法を記載します。
まずは、MATLABを起動して、MATLABのホームタブのアドオン(Add-Ons)からAdd-On Explorerを開いてください。
Add-On Explorerの右上の検索窓から、公開したページを検索してください。たとえばpomodoro-timer
と検索していただけますと私のサンプルが見つかるかと思います。そのページにあるAdd
からAdd to MATLAB
をクリックすれば完了です。
また、MATLAB Onlineから開くこともできます。
アンインストールしたい場合には、コマンドパレットに以下のコマンドを入力してください。
matlab.addons.uninstall("pomodoro-timer");
コマンドラインインターフェイスに慣れている身としては、インストールもコマンドでできると嬉しいのですが、matlab.addons.install
コマンドはツールボックスのインストールのみがサポートされており、File Exchangeのファイルについては未対応のようです。
また、同様にインストール済みのアドオン一覧を取得する場合には、
matlab.addons.installedAddons
というコマンドを使用できます。その他にもアドオンに関してさまざまな関数がありますが、公式ページでご確認いただけますと幸いです。
おわりに
この記事では、File Exchangeの概要と使い方、GitHub連携の方法について記載しました。
私は経験がありませんが、ツールボックスの公開についても同様の手順で可能かと思います。
皆様の便利関数やMATLAB芸などが公開されることを期待しております。
Discussion