🔄

MATLAB File ExchangeとGitHubを連携したコード公開

2025/01/20に公開

はじめに

自作MATLAB関数を公開をGitHubを通じてFile Exchangeに公開しました。

https://jp.mathworks.com/matlabcentral/fileexchange/176183-pomodoro-timer

内容についてはこちらの記事もご覧ください。

https://zenn.dev/kimushun1101/articles/matlab-pomodoro-timer

この記事では、File Exchangeについて簡単に紹介し、その手順を簡単に解説します。

前提としてGitやGitHubの簡単な動作はできているものとして、それらの詳細は割愛します。ご自身のGitHubアカウントを作られており、新規リポジトリが作成できて、Gitコマンドとしてはcloneaddcommitpushくらいできていれば大丈夫です。普段GitHubを使っている方も新たな発見があれば幸いです。

File Exchageとは

File Exchangeでは、MATLABで作成した自分のプログラムを世界中の他の方々に手軽に使っていただくことができます。また、私のように複数のパソコンでMATLABを使用するような用途では、異なるパソコン間で自作関数を共有するのに非常に便利です。
ソースコード公開としてはGitHubによる公開が主流であるかと思われますが、これはソースコード管理が主たる役割であり、ファイルのダウンロードやMATLAB上でのパスの設定、インストール済みの追加ソフト(アドオン)一覧確認など、インストール作業に関してはFile Exchangeを通すことでMATLABがある種自動で実行または管理してくれます。以降では、このGitHubとFile Exchangeを連携して、ソースコードを配布する方法について示します。

GitHubでの公開

まずは、GitHubでリポジトリを作成して、ソースコードをアップロードします。
必要なファイルはソースファイルREADMEファイルLICENSEファイルの3つです。
以下のファイルを含んだGitHubリポジトリを作成しましょう。完成例は以下のリポジトリをご覧ください。

https://github.com/kimushun1101/pomodoro-timer

ソースファイル

まず、公開したいソースコードを用意します。
ライブスクリプトファイル(.mlx)も公開可能ですがこれはバイナリファイルであるため、ソースコードの変更履歴を追えるスクリプトファイル(.m)で公開する方が個人的には好みです。スクリプトで作成した関数の最初にはコメントアウトで関数の説明を行います。例としては以下のとおりです。

https://github.com/kimushun1101/pomodoro-timer/blob/0a158901d48a06e08851fb26403a4d455a61d445/pomodoroTimer.m#L2-L23

これによりdocコマンドやhelpコマンドでこの説明を表示させることができます。動作や引数、参考Webページなど必要な情報をコンパクトにまとめてください。
%%で始める行はセクションタイトルとなってくれます。

ライブスクリプトファイルでも、同様に説明を付けることができます。ライブスクリプトファイルを公開した例は以下にありますので、ご興味がある方はこちらもダウンロードしてみてください。

https://github.com/kimushun1101/arrange-resize-figures

READMEファイル

READMEファイルには、このソースコードの説明を書きます。
関数最初のコメントアウトよりたくさんの情報を掲載できます。

ロゴの使用

この例の一行目

[![View pomodoro-timer on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://jp.mathworks.com/matlabcentral/fileexchange/176183-pomodoro-timer)

のように記載することで、File Exchangeのロゴを使用したリンクを作成できます。リンク先のURLはご自身が公開したページに変更する必要があることに注意してください。しかしながら公開ページリンクは公開しないと決まらないため、ここは公開後に再編集することになります。File exchangeでの公開の章で再度ご説明いたします。

画像の挿入

画像についてはGit管理に加えていただいても構いませんが、リポジトリサイズを小さく保つために、ブラウザ上のGitHubにドラッグアンドドロップで追加することもできます。

Edit README file

Editの状態でドラッグアンドドロップして、完了したあとはPreviewで確認しましょう。

Uplaod an image

問題なければCommitして変更を反映させてください。
いずれにしても違和感がない程度に画像ファイルは小さくしたほうが良いです。

LICENSEファイル

自分のソースコードの再配布を許可したり不備による損害を免責したりするために、ライセンスファイルを追加しておくことをオススメします。私は趣味で公開する場合にはMITライセンスを使うことが多いですが、個人の好みやニーズによって適切なライセンスを付加しましょう。自分で作っていただいても構いませんが、有名ライセンスから選択するのが公開者側も利用者側も楽だと思います。

https://yamory.io/blog/about-mit-License

GitHub Repositoryを作成する際に選択して自動生成させることも可能です。
https://github.com/new
choose-a-license

File exchangeでの公開

File exchangeでは直接ファイルアップロードして公開することもできますが、上記で整備してきたGitHubリポジトリと連携させると管理が楽になります。

GitHub連携

以下のページから、ご自身のMathWorksアカウントでログインしてください。

https://jp.mathworks.com/matlabcentral/fileexchange/my-file-exchange

つぎに、New Submissionボタンからファイルをおきます。置き方はGitHub連携と直接アップロードする2通りがあります。

new-publish

もちろんここではGitHub連携をしていきましょう。ここのCheck your settings in GitHubをクリックして連携するリポジトリを選択してください。MATLAB and Simulink Integrationをインストールしましょう。公式の説明(英語)は以下にあります。

https://jp.mathworks.com/matlabcentral/fileexchange/my-file-exchange/github-app-installation-guide

ここの例では、すべてのリポジトリを許可しておりますが、個人的には必要なリポジトリだけ許可を与えております。

repository-access

ここで許可を与えるとNew Submissionボタンから該当リポジトリを選択できるようになったかと思います。
ブランチとリリースのどちらで公開するかを選択できます。慣れていればリリースで公開したほうがよいと思います。いずれにしても設定から変更することが可能です。設定したブランチに新しいコミットや新しいリリースを作ると自動的に最新のコードに更新されます。「新しいGitHubリリースを作成すると、このページが更新されます。更新には、最大で1時間ほどかかる場合があります。」と案内がありますが、体感として数十秒から数分くらいで反映されていそうな雰囲気です。

公開情報の設定

公開情報の設定画面は以下の通りです。

file-exchange-manage

直感的に設定できると思いますが、以下のような項目があります。

  1. Image: 画像を設定できます。File Exchageで検索したときのサムネイルになるため、その関数の動作がつかめるような画像がよいでしょう。
  2. Description: GitHub連携がされていればREADME.mdの内容が転記されます。書き直したい場合にはUse README.md from GitHubでオフにすることもできそうですが、したことはありません。
  3. Tags: タグ。適切なタグを付けていると見つけてもらえるかもしれません。
  4. Cite As: 文献やWebサイトなど引用してほしい文献があれば載せておきましょう。デフォルトではGitHubのリンクが入るようです。
  5. Acknowledgments: 謝辞。とくになければ空欄でよいと思います。
  6. GitHub Integration: ブランチとリリースのどちらで公開するかを変更できます。
  7. Required MathWorks Products: 必要なツールボックスなどがあれば記述してください。
  8. MATLAB Release Compatibility: どのバージョンで実行可能かを示します。Compatible Withを設定したい場合には公開するコードで使用している関数がどのバージョンから実行可能であるかなどを注意してみてください。
  9. Platform Compatibility: どのOSで実行可能かを示します。OS依存の実装をしていなければ基本的にチェックを入れてしまって問題ないかと思います。

これらを右上のpublishを押せば、更新完了です。もちろん、あとから変更することも可能です。File Exchangeのマイファイルをクリックして、設定を変更したいソフトのManageから「編集」をクリックしてください。
my file

ここで公開が完了することでFile ExchangeのURLが決定されます。READMEファイルのご説明にあったように、URLの追記または変更を行ってください。

インストールと管理

ここでは公開したプログラムを個々のパソコンにインストールする方法を記載します。
まずは、MATLABを起動して、MATLABのホームタブのアドオン(Add-Ons)からAdd-On Explorerを開いてください。

add-on

Add-On Explorerの右上の検索窓から、公開したページを検索してください。たとえばpomodoro-timerと検索していただけますと私のサンプルが見つかるかと思います。そのページにあるAddからAdd to MATLABをクリックすれば完了です。
また、MATLAB Onlineから開くこともできます。

アンインストールしたい場合には、コマンドパレットに以下のコマンドを入力してください。

matlab.addons.uninstall("pomodoro-timer");

コマンドラインインターフェイスに慣れている身としては、インストールもコマンドでできると嬉しいのですが、matlab.addons.installコマンドはツールボックスのインストールのみがサポートされており、File Exchangeのファイルについては未対応のようです。

https://jp.mathworks.com/help/matlab/ref/matlab.addons.install.html

また、同様にインストール済みのアドオン一覧を取得する場合には、

matlab.addons.installedAddons

というコマンドを使用できます。その他にもアドオンに関してさまざまな関数がありますが、公式ページでご確認いただけますと幸いです。

https://jp.mathworks.com/help/matlab/add-ons.html

おわりに

この記事では、File Exchangeの概要と使い方、GitHub連携の方法について記載しました。
私は経験がありませんが、ツールボックスの公開についても同様の手順で可能かと思います。
皆様の便利関数やMATLAB芸などが公開されることを期待しております。

GitHubで編集を提案

Discussion