インストール - Hazkeyのソースを表示

== 概要 ==
Hazkeyは、Fcitx5向けの高精度日本語入力エンジンである。<br>
スローガンは「思考を止めない日本語入力」であり、入力作業を妨げないUI/UXの実装を目指して設計されている。<br>
<br>
iOS/MacOS向けアプリであるazooKeyと同じ高精度変換技術 (AzooKeyKanaKanjiConverter) を採用しており、Linux環境での日本語入力を効率化する。<br>
<br>
ビルドにはSwift 6.1以上が必要であり、RHEL および SUSE環境ではビルド環境の構築に一定の手順を要する。<br>
<br>
主な特徴は以下の通りである。<br>
<br>
<center>
{| class="wikitable"
|+ Hazkeyの機能
|-
! 機能 !! 説明
|-
| 高精度変換エンジン || iOS/MacOS向けアプリであるazooKeyと同じ変換技術を採用し、高い変換精度を実現する。
|-
| 自動変換機能 || 入力すると即座に自動で変換され、変換操作に妨げられることなく長文を入力できる。
|-
| Zenzaiニューラル変換 || GPT-2ベースのAIによるプロフィールや文脈を考慮した高度な変換に対応する。(オプション)
|-
| GGMLサポート || GPU対応バックエンド (Vulkan) を利用した高速処理が可能である。
|}
</center>
<br>
公式情報は以下を参照する。<br>
* 公式サイト
*: [https://hazkey.hiira.dev hazkey.hiira.dev]
* GitHubリポジトリ
*: [https://github.com/7ka-Hiira/fcitx5-hazkey github.com/7ka-Hiira/fcitx5-hazkey]
<br><br>

== 動作要件 ==
Hazkeyのビルドおよび動作に必要なソフトウェアを以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ 動作要件一覧
! ソフトウェア !! 必要バージョン !! 備考
|-
| Swift || 6.1 以上 || Swiftlyによるインストールを推奨
|-
| fcitx5 || 5.0.4 以上 || 入力フレームワーク本体
|-
| Qt || 6.7推奨 (6.2以降で可) || 6.7未満では表示に問題が発生する場合がある。
|-
| CMake || 3.21以上 (4.x以降推奨) || ビルドシステム
|-
| Protobuf || 3.12以上 || プロトコルバッファライブラリ
|-
| Ninja || 最新版推奨 || ビルドツール
|-
| Gettext || 最新版推奨 || 国際化対応ライブラリ
|-
| Vulkan headers || 最新版推奨 || GPU対応バックエンド用 (オプション、無効化可能)
|}
</center>
<br><br>

== Swiftのインストール ==
Hazkey のビルドには Swift 6.1以上が必要である。<br>
現在の推奨インストール方法は、公式ツールの Swiftly (rustup 相当) を使用する方法である。<br>
<br>
==== 公式サポート状況 ====
ディストリビューションごとの公式サポート状況を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ Swift 公式サポート状況
! ディストリビューション !! 公式サポート
|-
| RHEL 9 || 公式サポート
|-
| RHEL 10 || 未公式 (RHEL 9ツールチェインで動作可)
|-
| SUSE 15 / 16 || 未公式 (RHEL 9ツールチェインで動作可)
|}
</center>
<br>
==== RHEL ====
RHEL 10は、Swiftの公式サポートリストに未掲載だが、RHEL 9と非常に近い構成のため、同ツールチェインで動作する。<br>
<br>
まず、依存パッケージをインストールする。<br>
 sudo dnf install pkg-config binutils gcc git glibc-static libbsd-devel libcurl-devel libedit-devel libicu-devel libstdc++-static \
                  python3 sqlite-devel zlib-devel ncurses-devel
<br>
Swiftlyをダウンロードして初期化する。<br>
 curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz
 tar xf swiftly-$(uname -m).tar.gz
 cd swiftly-$(uname -m)
 
 ./swiftly init --quiet-shell-followup
<br>
init実行時に <u>RHEL 10は未公式プラットフォームです</u> と表示された場合は、プロンプトでRHEL 9を選択する。<br>
<br>
環境変数を設定する。<br>
 <syntaxhighlight lang="sh">
 # Bash / Zsh
 . "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh"
 
 # Fish
 source (set -q SWIFTLY_HOME_DIR; and echo $SWIFTLY_HOME_DIR; or echo $HOME/.local/share/swiftly)/env.fish
 </syntaxhighlight>
<br>
最新のSwiftをインストールする。<br>
 swiftly install latest
<br>
正常にインストールされているかどうかを確認する。<br>
 swift --version
<br>
==== SUSE ====
SUSEでは、Swiftlyが非公式プラットフォームと検出するため、手動でRHEL 9ツールチェインを選択する。<br>
<br>
まず、依存パッケージをインストールする。<br>
<br>
 # SUSE 16
 sudo zypper install pkg-config binutils gcc gcc-c++ git gzip glibc-static libbsd-devel libedit-devel libicu-devel \
                     libcurl-devel ncurses-devel sqlite3-devel zlib-devel python3
 
 # SUSE 15.6
 sudo zypper install pkg-config binutils binutils-gold gcc gcc-c++ git gzip glibc-static libbsd-devel libedit-devel libicu-devel \
                     libcurl-devel ncurses-devel sqlite3-devel zlib-devel python3
<br>
Swiftlyをダウンロードして初期化する。<br>
 curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz
 tar xf swiftly-$(uname -m).tar.gz
 cd swiftly-$(uname -m)
 
 ./swiftly init --quiet-shell-followup
<br>
<code>./swiftly init --quiet-shell-followup</code> コマンドを実行した時、以下に示すエラーが出力される場合がある。
<br>
 Error: The ca-certificates package is not installed. Swiftly won't be able to trust the sites to perform its downloads. 
 
 You can install the ca-certificates package on your system to fix this.
<br>
これは、Swiftlyは特定のLinuxディストリビューション (Debian系) のファイルパス (/etc/ssl/certs/ca-certificates.crt )を探しているためである。<br>
SUSEにおいてはパスが異なるため、所定のパスにシンボリックリンクを貼る必要がある。<br>
<br>
 sudo ln -s /var/lib/ca-certificates/ca-bundle.pem \
            /etc/ssl/certs/ca-certificates.crt
<br>
再度、<code>./swiftly init --quiet-shell-followup</code> コマンドを実行する。<br>
<br>
初期化中に以下のプロンプトが表示されるので、<u>6</u> を入力して、RHEL 9を選択する。<br>
<br>
 SUSE Linux Enterprise 15 SP 6 is not an officially supported platform,
 but the toolchains for another platform may still work on it.
 Please select the platform to use for toolchain downloads:
 
 0) Cancel
 1) Ubuntu 24.04
 2) Ubuntu 22.04
 3) Ubuntu 20.04
 4) Ubuntu 18.04
 5) Fedora Linux 39
 6) RHEL 9
 7) Amazon Linux 2
 8) Debian GNU/Linux 12
<br>
環境変数を設定する。<br>
 <syntaxhighlight lang="sh">
 # Bash / Zsh
 . "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh"
 
 # Fish
 # Fishの場合は、~/.config/fish/conf.d/swiftly.fish にパスが追加される
 source (set -q SWIFTLY_HOME_DIR; and echo $SWIFTLY_HOME_DIR; or echo $HOME/.local/share/swiftly)/env.fish
 </syntaxhighlight>
<br>
最新のSwiftをインストールする。<br>
 swiftly install latest
<br>
正常にインストールされているかどうかを確認する。<br>
 swift --version
<br>

==== Swiftlyの主なコマンド ====
下表に、Swiftlyの主なコマンドを示す。<br>
<br>
<center>
{| class="wikitable"
|+ Swiftly コマンド一覧
! コマンド !! 説明
|-
| swiftly list-available || インストール可能なバージョンの一覧を表示する。
|-
| swiftly install 6.2.3 || 特定バージョンをインストールする。
|-
| swiftly use 6.2.3 || 使用するバージョンを切り替える。
|-
| swiftly uninstall 5.10 || 指定バージョンを削除する。
|-
| swiftly self-update || Swiftly自体を更新する。
|-
| swiftly install main-snapshot || 開発スナップショットをインストールする。
|}
</center>
<br>
==== Dockerを使用する方法 ====
RHEL / SUSEの環境構築に問題が生じる場合は、公式コンテナイメージを使用する方法が最も確実である。<br>
Docker および Podman のどちらでも使用可能である。<br>
<br>
 # バージョン確認
 podman run -it --rm swift:latest swift --version
 
 # プロジェクトのビルド
 podman run -it --rm \
    -v $(pwd):/workspace -w /workspace \
    swift:latest swift build
<br><br>

== Swiftのアンインストール ==
Swiftlyでインストールした場合は、Swiftly経由で削除する。<br>
<br>
==== ツールチェーンの確認と削除 ====
まず、インストール済みのツールチェーンを確認する。<br>
<br>
 swiftly list
<br>
表示されたバージョンをアンインストールする。<br>
複数バージョンがある場合は、それぞれに対して実行する。<br>
<br>
 swiftly uninstall <バージョン  例: 6.2.3>
<br>
==== Swiftly本体の削除 ====
Swiftly本体と全てのツールチェーンを削除する。<br>
<br>
 rm -rf ~/.local/share/swiftly
 rm -f ~/.local/bin/swiftly
<br>
==== シェル設定のクリーンアップ ====
Swiftlyインストール時に追加された環境変数の設定を削除する。<br>
<br>
Fishの場合は、以下のコマンドで該当する設定を確認する。<br>
<br>
 grep -rn "swiftly\|SWIFT" ~/.config/fish/
<br>
該当する行があれば、エディタで削除する。<br>
<br><br>

== 依存関係のライブラリのインストール ==
Hazkeyのビルドに必要な依存パッケージをインストールする。<br>
<br>
==== RHEL ====
Vulkanを使用しない場合は、vulkan-headersのインストールを省略できる。<br>
<br>
 sudo dnf install cmake ninja-build gettext protobuf-devel protobuf-compiler fcitx5-devel \
                  qt6-qtbase-devel qt6-qttools-devel vulkan-headers
<br>
==== SUSE ====
Vulkanを使用しない場合は、vulkan-headersのインストールを省略できる。<br>
<br>
 sudo zypper install cmake ninja gettext-tools protobuf-devel fcitx5-devel \
                     qt6-base-devel qt6-tools-devel qt6-linguist-devel vulkan-headers
                     shaderc glslang-devel  # Vulkanを有効にする場合
<br><br>

== ビルドとインストール ==
==== ソースコードの取得 ====
Gitを使用して、Hazkeyのソースコードを再帰的にクローンする。<br>
<code>--recursive</code> オプションはサブモジュールも含めて取得するために必要である。<br>
<br>
 git clone --recursive https://github.com/7ka-Hiira/fcitx5-hazkey.git -b 0.2.1
<br>
==== ビルド ====
Hazkeyをビルドおよびインストールする。<br>
<br>
Vulkanを無効にしてビルドする場合は、<code>-DGGML_VULKAN=OFF</code> を設定する。<br>
<br>
 cd fcitx5-hazkey
 mkdir build && cd build
 
 cmake -G Ninja \
       -DCMAKE_C_COMPILER=<GCC 8以降のGCC>   \
       -DCMAKE_CXX_COMPILER=<GCC 8以降のG++> \
       -DSWIFT_LINK_PATH=$HOME/.local/share/swiftly/toolchains/<バージョン>/usr/lib/swift/linux \
       -DCMAKE_BUILD_TYPE=Release  \
       -DCMAKE_INSTALL_PREFIX=/usr \
       -DGGML_VULKAN=ON            \  # Vulkanを有効にする場合
       ..
 
 ninja -j $(nproc)
 sudo ninja install
<br>
インストール完了後、Fcitx5を再起動して、Hazkeyを入力メソッドとして選択する。<br>
<br><br>

== Zenzaiのインストール ==
Zenzaiは、ニューラル変換用のモデルとGGMLバックエンドを使用するオプション機能である。<br>
<br>
GPUバックエンドを使用する場合は、Hazkeyを <code>-DGGML_VULKAN=ON</code> でビルドする。<br>
<br>
<u>なお、CPUバックエンドのみでもZenzaiは使用可能である。</u><br>
<br>
==== Vulkanドライバのインストール ====
===== NVIDIA GPU =====
NVIDIA GPUでVulkanバックエンドを使用する場合は、NVIDIAプロプライエタリドライバとVulkan ICDをインストールする。<br>
<br>
NVIDIA CUDAリポジトリを追加して、ドライバと確認ツールをインストールする。<br>
<br>
 # RHEL
 # NVIDIA CUDAリポジトリを追加して、ドライバと確認ツールをインストールする
 sudo dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel10/x86_64/cuda-rhel10.repo
 sudo dnf install cuda-drivers vulkan-tools
 
 ## GeForce GT 1030を含むPascal世代以前のGPUは、NVIDIAオープンカーネルモジュールとG07系列に対応していないため、
 ## CUDAリポジトリで提供される580系列を指定する
 sudo dnf install 'cuda-drivers-580*' vulkan-tools
 
 # SUSE
 # nvidia-gl-G07パッケージは、Vulkan ICDを含むユーザ空間ライブラリである
 sudo zypper addrepo --refresh 'https://download.nvidia.com/opensuse/leap/$releasever/' NVIDIA
 sudo zypper refresh
 sudo zypper install nvidia-driver-G07-kmp-meta nvidia-gl-G07 vulkan-tools
 
 ## GeForce GT 1030を含むPascal世代以前のGPUは、NVIDIAオープンカーネルモジュールとG07系列に対応していないため、
 ## プロプライエタリの580系列を使用する
 sudo zypper install nvidia-driver-G06-kmp-meta nvidia-gl-G06 vulkan-tools
<br>
<u>cuda-drivers</u> は、Vulkan ICDを含む <u>nvidia-driver-libs</u> を依存関係としてインストールする。<br>
<br>
PCを再起動して、NVIDIAドライバとVulkanを確認する。<br>
<br>
 nvidia-smi
 vulkaninfo --summary
<br>
<code>vulkaninfo --summary</code> コマンドの出力にNVIDIA GPUが表示されれば、Vulkanバックエンドは利用可能である。<br>
<br>
===== AMD GPU =====
AMD GPUでVulkanバックエンドを使用する場合は、Vulkan loaderとRADVドライバをインストールする。<br>
<br>
 # RHEL
 sudo dnf install mesa-vulkan-drivers vulkan-tools
 
 # SUSE
 sudo zypper install libvulkan_radeon vulkan-tools
<br>
<code>vulkaninfo --summary</code> コマンドの出力にAMD Radeon GPUが表示されれば、Vulkanドライバは利用可能である。<br>
<br>
 vulkaninfo --summary
<br>
==== モデルのダウンロードと有効化 ====
# hazkey-settingsを起動して、[AI]タブを開く。
# 黄色の警告欄にある [モデルをダウンロード]ボタンを押下する。
# Zenzai v3.1 smallモデルが自動的にダウンロードされて、SHA-256を検証した後に以下に示すディレクトリへ保存される。
#: <pre>~/.local/share/hazkey/zenzai/zenzai.gguf</pre>
# ダウンロード完了後に[再読み込み]ボタンを押下する。
# [Zenzaiを有効化]チェックボックスにチェックを入力して、[適用]ボタン または [OK]ボタンを押下する。
# Vulkan GPUがバックエンドの選択肢に表示されない場合は、Fcitx5を再起動する。
#: <pre>fcitx5-remote -r</pre>
<br><br>

== トラブルシューティング ==
下表に、ビルドおよびインストール時に発生する可能性がある問題と対処法を示す。<br>
<br>
<center>
{| class="wikitable"
|+ トラブルシューティング一覧
! 問題 !! 発生環境 !! 対処法
|-
| 三角関数の再定義エラーが発生する || 全環境 || Swiftのシムヘッダファイル <u>/<swiftのインストール場所>/lib/swift_static/_FoundationCShims/_CStdlib.h</u> の<br>約50行目にある3行をコメントアウトする。
|-
| <code>_mm256_set_m128</code> が未定義のエラーが発生する || SUSE 15 || SUSE 15付属のGCC 7では <u>_mm256_set_m128</u> が未定義のため、GCC 8以降を使用する。
|}
</center>
<br>
==== 三角関数の再定義エラーへの対処 ====
Swift のシムヘッダーファイルに含まれる三角関数の定義が競合する場合がある。<br>
以下に示す手順でエラーを解消する。<br>
<br>
対象ファイルを開いて、該当ファイルの約 50 行目付近にある三角関数の定義に関する3行をコメントアウトする。<br>
 nano /<swiftのインストール場所>/lib/swift_static/_FoundationCShims/_CStdlib.h
<br>
==== GCCバージョン問題への対処 ====
<u>_mm256_set_m128</u> というAVX intrinsic関数は、GCC 8 以降のimmintrin.hファイルで追加されたため、GCC 7以前ではビルドできない。<br>
<br>
 cmake -G Ninja \
    -DCMAKE_C_COMPILER=<GCC 8以降のGCC>   \
    -DCMAKE_CXX_COMPILER=<GCC 8以降のG++> \
    -DCMAKE_BUILD_TYPE=Release  \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DGGML_VULKAN=OFF           \
    ..
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板,Hazkey,Fcitx5,fcitx5-hazkey,日本語入力,IME,azooKey,AzooKeyKanaKanjiConverter,Zenzai,ニューラル変換,Swift,Swiftly,RHEL,SUSE,GCC,CMake,Ninja,Protobuf,Vulkan,GGML
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:RHEL]][[カテゴリ:SUSE]]