=================================================================== MacOS (Catalina, Mojave, High Sierra)用バイナリ版インストール手引書 =================================================================== :著者: 稲村 泰弘 :最終更新日: Apr. 7th, 2021 :対応空蟬リリース: 4.0 or later .. contents:: 目次 :depth: 3 インストールが可能なMacOS ============================ 基本的に以下のMacOS Xでのみ動作する。 - 10.15 (macOS Catalina) - 10.14 (macOS Mojave) - 10.13 (macOS High Sierra) なお、既知の問題もあるので、注意すること。 インストール手順 ================== 空蟬4のインストーラは、MacOS Xでよく使用されるパッケージファイル（ファイル名の拡張子が **.pkg** ）として配布される。このファイルをダブルクリックすることで「アプリケーション」フォルダに **Utsusemi** フォルダがインストールされる。 準備：MacOSセキュリティの設定 ------------------------------- 残念ながら空蟬はMacOSから見て安全が保障されたソフトウェア（AppStoreなどで配布されるような公式のアプリケーション）ではないため、実行するためには予めMacOSのセキュリティの設定を行う必要がある。 .. warning:: もしセキュリティ設定前に、すでに空蟬をインストールしていた（アプリケーションフォルダにUtsusemiフォルダがある）場合、予めUtsusemiフォルダを削除しておくこと 1. Finderの「アプリケーション」 -> 「ユーティリティ」 の中の「ターミナル」を起動する 2. ターミナルの中で以下のコマンドを打つ。パスワードを聞かれるので、ログインする時のパスワードを打ち込む。 .. code-block:: shell $ sudo spctl --master-disable 3. MacOS Xのシステム環境設定を開き、「セキュリティとプライバシー」設定の「一般」タブを開く 4. 先のコマンドにより、これまで隠されていた「ダウンロードしたアプリケーションの実行許可」に「すべてのアプリケーションを許可」項目が表示されるので、それを選択する |image14| 5. もし上図の「全てのアプリケーションを許可」項目が見えない場合は、Mac本体を再起動すると「すべてのアプリケーションを許可」が選択できるようになるので、設定する。 このセキュリティ設定がなされていないと、空蟬アプリの起動時に **全く何も反応がない** ので注意すること。 空蟬4のインストール ----------------------- 1. インストーラをダブルクリックする |image00| ダブルクリックした時に下記のような「開発元が未確認のため開けません」とダイアログが出た場合は |image01err| インストーラを右クリック、もしくは *Control* キーを押しながらアイコンをクリックして現れるショートカットメニューから　「開く」を選択する。 |image01menu| すると、下記のような開いて良いかを尋ねるダイアログが現れるので「開く」を選択する。 |image01confirm| 2. 後は通常のインストールダイアログが現れるので「続ける」を押す。 |image02| 3. 場合によってはインストール先を聞かれることもあるので選択して「続ける」を押す |image03| 4. インストール先を変更せずに「インストール」を押す（インストール先は「アプリケーション」フォルダ） |image04| 5. パスワードを入力する |image05| 6. インストールが開始される |image06| 7. インストールが完了するので、「閉じる」を押す |image07| インストールされるアプリケーション ======================================= 空蟬ソフトウェア群は、「アプリケーションフォルダ」の「Utsusemi」フォルダ内にある。もしくはLaunchPadからもアクセスできる。 インストールにより、以下のプログラムが準備される。 |image08| ここには以下のプログラムが準備されている。詳細は後で述べる。 +-----------------------------+--------------------------------------------+ |Utsusemiアプリケーション |説明 | +=============================+============================================+ |D4MatSlicer |D4MatSlicerを起動する | +-----------------------------+--------------------------------------------+ |D4Mat2Slicer |D4Mat2Slicerを起動する | +-----------------------------+--------------------------------------------+ |M2PlotPlus |M2Plotを起動する | +-----------------------------+--------------------------------------------+ |MPlot |MPlotを起動する | +-----------------------------+--------------------------------------------+ |SequenceEditorQ |SequenceEditorを起動する | +-----------------------------+--------------------------------------------+ |Utsusemi Environment Settings|【環境設定】空蟬のフォルダ環境変数を設定する| +-----------------------------+--------------------------------------------+ |Utsusemi Shell |Utsusemi環境が設定されたターミナルを起動する| +-----------------------------+--------------------------------------------+ 初期設定 ========= 必要なフォルダの作成 -------------------------------- 空蟬Mac版では、まず解析用データの置き場所と一時ファイル保存場所をフォルダとして準備する必要がある。 +--------------------------+---------------------------------------------------------------------------------------------------+ |設定（環境変数名） |役割 | +==========================+===================================================================================================+ |データフォルダ (DATA_DIR) |イベントデータなどRAWデータを格納するフォルダ。（Linux版では"/data"） | +--------------------------+---------------------------------------------------------------------------------------------------+ |解析用フォルダ (USR_DIR) |空蟬が作成する一時ファイルを保存先するana/tmpなどのフォルダを置く場所である。（Linux版では"$HOME"）| +--------------------------+---------------------------------------------------------------------------------------------------+ この二つのフォルダは本来どこにあっても良いが、macOS Catalina (10.15)以降のセキュリティ強化の結果、特にデータフォルダをデスクトップや書類フォルダ、共有フォルダに置くとアクセスできないことがある。したがって空蟬のmacOS版ではデフォルトの場所はホームフォルダ直下（/Users//）としている。環境設定 **Utsusemi Environment Setting** （詳細は次項）の初回起動時にこの場所に自動的に作成される。この場所で不都合がある場合は、別途用意すること。 +--------------+--------------------------------------------+ | |デフォルトの場所（インストール時に自動生成）| +==============+============================================+ |データフォルダ|ホームフォルダ/Utsusemi/DATA | +--------------+--------------------------------------------+ |解析用フォルダ|ホームフォルダ/Utsusemi/HOME | +--------------+--------------------------------------------+ |image09| もし、ホームフォルダの場所がよくわからない場合は、下記のようにデスクトップのメニュー **移動** から **ホーム** を選択すれば良い。 |image09r1| 環境設定と初回起動時の注意点 ----------------------------------- 次に空蟬の環境の設定を **Utsusemi Environment Settings** で行う。 .. warning:: この作業は、インストール後に１回は必ず行う必要がある。 このアプリケーションで設定できる内容は以下の通りである。 - 使用する装置環境（BL01, BL11, BL14, BL15） - データフォルダと解析フォルダの設定 - ログを残すかどうか - 高速化のための並列計算の数 - デバッグモードのオン・オフ よって、違う装置（BeamLine）のデータを解析する場合は、この環境設定で装置環境を切り替える必要がある。 環境設定の起動 ^^^^^^^^^^^^^^^^^^^ 「アプリケーション」フォルダ >> Utsusemi もしくは LaunchPad から |image08| **Utsusemi Environment Settings** を起動する。 |image10| 設置項目 ^^^^^^^^^^^^^ 1. **Instrument** 解析に使用するデータの装置の選択を行う。これにより、使用するRAWデータフォルダ、使用できるコマンドなどが変化する。 2. **Log quiet** 解析コマンドのログを減らす場合に使用する。普段はYESで良い。 .. warning:: MacOSのログは通常あらわには表示されない。すべてのログは */tmp/mlfsoft.log* に書き込まれる。 3. **Utsusemi_debugmode** 空蟬のデバッグモード。普段はNO（チェックボックスオフ）で良い。 3. **Number of thread** 一部の解析コマンドが使用するマルチスレッドの最大値を設定する（通常は実行するPCのコアの数程度を設定すると良い） 4. **DATA_DIR** 及び **USR_DIR** ここで必要な設定は、前節で作成した二つのフォルダを指定することである。 +----------------+---------------------------------------------------------------------------------------------------+ |設定（環境変数）|役割 | +================+===================================================================================================+ |DATA_DIR |イベントデータなどRAWデータを格納するフォルダ。（Linux版では"/data"） | +----------------+---------------------------------------------------------------------------------------------------+ |USR_DIR |空蟬が作成する一時ファイルを保存先するana/tmpなどのフォルダを置く場所である。（Linux版では"$HOME"）| +----------------+---------------------------------------------------------------------------------------------------+ 設定後 ^^^^^^^^^^^^^ 設定項目を反映するために **OK** ボタンを押す。正しく設定されれば、確認のダイアログが表示される。 |image11| このダイアログが出ずにエラーのダイアログが出た場合は、特に指定した **DATA_DIR** と **USR_DIR** のフォルダがあるかどうかを確認すること。この設定により、 **USER_DIR** の下に - **ana** フォルダ - この下に **tmp** フォルダ、および **xml** フォルダ がなければ自動的に作成される。 |image12| .. warning:: もし、**ana** フォルダや **tmp** フォルダが見つからないようなら設定を見直すか、自分で作成しておくこと。 **そうでないと空蟬は落ちます** 。 一方、*DATA_DIR* で設定した場所には、次節にて述べるルールで、データ（イベントデータなど）を配置する。 データの配置ルール -------------------- 環境変数 *DATA_DIR* で指定したフォルダに、以下のようなルールで配置する。 1. 装置コードと同じ名前のフォルダを作成する 四季（BL01）なら "SIK"、アマテラス（BL14）なら "AMR" 2. 装置コードのフォルダに、その装置でのRun Noのついたデータのフォルダを置く 四季（BL01）なら、例えば "SIK012345_20150301" など +---------------+----------+---------------------------+ |BL |装置コード|配置例 | +===============+==========+===========================+ |BL01 四季 |SIK |DATA/SIK/SIK012345_20160401| +---------------+----------+---------------------------+ |BL11 PLANET |HPN |DATA/HPN/HPN012345_20160401| +---------------+----------+---------------------------+ |BL14 アマテラス|AMR |DATA/AMR/AMR012345_20160401| +---------------+----------+---------------------------+ |BL15 大観 |SAS |DATA/SAS/SAS012345_20160401| +---------------+----------+---------------------------+ |BL19 匠 |ENG |DATA/ENG/ENG012345_20160401| +---------------+----------+---------------------------+ 解析の開始 ============== 環境設定が終了し、解析するデータの配置も終わったなら、アプリケーションから解析が行えるようになる。 空蟬のインストールにより、以下のアプリケーションが「アプリケーションフォルダ／Utsusemiフォルダ」もしくはLaunchpadから起動できるようになる。 **Utsusemi Environment Settings** 【環境設定】空蟬の環境変数を設定する。詳細は上記の「環境設定と初回起動時の注意点」以下を参照のこと。 **MPlot**, **M2PlotPlus** 空蟬で使用されるデータ可視化ソフトウェアである。それぞれ、1次元プロッタ、2次元プロッタである。詳細は空蟬ユーザーマニュアルを参照のこと。Linux版と同じ。 **D4MatSlicer**, **D4Mat2Slicer** D4MatSlicer、およびD4Mat2Slicerを起動する。あとはLinux版と同じ。 **SequenceEditorQ** SequenceEditorを起動する。 **Utsusemi Shell** 空蟬環境で、Shell（コマンドライン）を起動する。この上で環境設定で指定したビームラインに応じたコマンドを呼び出すことができる。よって、自作のスクリプトを走らせることもできる。 解析に使用するアプリケーションの詳細な説明は、空蟬ユーザーズマニュアルを参照のこと。 起動時の注意 ------------------- 何らかのアプリケーションを実行した場合、下記のようなダイアログが開くことがある。 |image13| この場合、「インストール」を選択すると、インターネットに接続していれば自動的に最小限必要なソフトウェアがダウンロードされる。「キャンセル」を選択もできるが、次回以降も同じダイアログが開くことになる。なお「Xcodeを入手」を選ぶと、MacやiPhoneのアプリを作成するキットソフトウェア一式が導入されるため、膨大な時間がかかるので、気をつけること。 ターミナルからの使用 ============================== アプリケーションを利用せずに、例えば自分で作成したPythonスクリプトを実行することも可能である。特に現場で作成したスクリプト、新しい解析のアイデアを形にしたものなどを自由に実行するためには、 A. **Utsusemi Shell** を起動して利用する B. ターミナルアプリ上で、空蟬環境を利用する のやり方がある。 **Utsusemi Shell** を用いると、シンプルな設定でターミナルが起動する。すでに自分でターミナルの設定を変更していてその環境で空蟬環境も利用する場合は、BのMacOSのターミナル上で空蟬環境を利用する必要がある。その方法を以下に示す。 1. ターミナルを起動する。 2. 以下のコマンドを実行する。 .. code-block:: shell $ source /Applications/Utsusemi/.opt/bin/_loadenv 3. これで直接万葉ライブラリや空蟬の関数を呼び出すことができる。 .. code-block:: shell $ python3 Python 3.7.2 (default, Mar 5 2019, 20:00:04) [Clang 6.0.1 (tags/RELEASE_601/final)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import Manyo Manyo>>> バージョンの確認 =================== インストールされた空蟬のバージョンを確認するには、以下の方法がある。バグなどの報告や、アップデートする際の目安となる。 1. インストーラーのファイル名 インストーラーファイル名には、数字が２種類ある。 +-----+--------------------+ |例 |Utsusemi_X.Y.Z_nnnn | +=====+====================+ |X.Y.Z|リリース番号 | +-----+--------------------+ |nnnn |最終アップデート日付| +-----+--------------------+ 2. **Utsusemi Shell** でのコマンド **Utsusemi Shell** を起動し以下のコマンドを打つ。 .. code-block:: python >>> import utsusemi >>> utsusemi.__version__ '4.0.0' もしくは .. code-block:: python >>> import UtsusemiInfo すると、以下のような情報が表示される。 .. code-block:: shell --------------------------------------------- Utsusemi Info --------------------------------------------- version : X.Y.Z (rev nnnnnn) Contact person : Yasuhiro Inamura e-mail : xxxxx.yyyyy@j-parc.jp --------------------------------------------- ファイル名と同様、X.Y.Zがリリース番号、nnnnが最終アップデート日付である。 アンインストール ==================== アプリケーションフォルダ内の、Utsusemiフォルダをゴミ箱へ捨てるだけである。 ただし、完全には消去されず、幾つかフォルダやファイルが残される。これらも消去したい場合は手動で行うこと。 +------------------------+ |*DATA_DIR* フォルダ | +------------------------+ |*USR_DIR* フォルダ | +------------------------+ また、幾つかの設定ファイルが残されている。次回インストールした時に初期設定として呼び出されるが、消去しても良い。 +----------------------------------------+ |ホームフォルダ/Library/Utsusemi フォルダ| +----------------------------------------+ .. code-block:: shell $ rm -rf $HOME/Library/Utsusemi ただし、これは不可視フォルダなので、通常目にすることはない。 問題が発生した場合 ====================================== 想定とは異なる事象、例えばデータ処理が進まない、GUIのソフトウェアが想定される動作をしない（ボタンが効かない）などあった場合、症状とログファイルを担当者に送付すること。また既知の問題（未解決）もあるので、注意すること。 症状の情報について -------------------- 症状に関しては、 - 何をしようとして - どのコマンド（ソフトウェア）を使用して - 何をしたら - どうなった の情報を整理すること。 ログファイルについて --------------------- MacOS版では、データ処理中のログは全て **/tmp/mlfsoft.log** に書き込まれるので、このログファイルを取り出すこと。 ただし、通常のファインダからはアクセスできないので、ターミナルから :: $ cp /tmp/mlfsoft.log ~/Desktop として、デスクトップにコピーするか、ファインダのメニュー「移動」から「フォルダの移動...」を選んででてきたダイアログに、 **/tmp/** と打ち込めばこのフォルダにアクセスできるようになる。 .. |image00| image:: media/mac_Utsusemi4Installer00.png :width: 132px .. |image01err| image:: media/mac_Utsusemi4Installer01err.png :width: 400px .. |image01menu| image:: media/mac_Utsusemi4Installer01menu.png :width: 200px .. |image01confirm| image:: media/mac_Utsusemi4Installer01conf.png :width: 400px .. |image02| image:: media/mac_Utsusemi4Installer02.png :width: 400px .. |image03| image:: media/mac_Utsusemi4Installer03.png :width: 400px .. |image04| image:: media/mac_Utsusemi4Installer04.png :width: 400px .. |image05| image:: media/mac_Utsusemi4Installer05.png :width: 400px .. |image06| image:: media/mac_Utsusemi4Installer06.png :width: 400px .. |image07| image:: media/mac_Utsusemi4Installer07.png :width: 400px .. |image08| image:: media/mac_Utsusemi4Installer08.png :width: 300px .. |image09| image:: media/mac_Utsusemi4Installer09.png :width: 300px .. |image09r1| image:: media/mac_Utsusemi4Installer09r1.png :width: 300px .. |image10| image:: media/mac_Utsusemi4Installer10.png :width: 300px .. |image11| image:: media/mac_Utsusemi4Installer11.png :width: 300px .. |image12| image:: media/mac_Utsusemi4Installer12.png :width: 300px .. |image13| image:: media/mac_Utsusemi4Installer13.png :width: 300px .. |image14| image:: media/mac_Utsusemi4Installer14.png :width: 300px