# インストールガイド

`haniwers`はPyPIで公開されており、Pythonの標準的なツールで簡単にインストールできます。

:::{tip}
**はじめての方へ**: このガイドでは、高速でモダンな`uv`を使ったインストール方法を推奨しています。
:::

:::{warning}
**動作環境について**

haniwersは主にmacOSとLinux（Raspberry Pi）で開発・テストされています。
Windowsでの動作は未検証です。Windows環境で問題が発生した場合は、[GitLab Issues](https://gitlab.com/qumasan/haniwers/-/issues)で報告してください。
:::

---

## 🚀 推奨: `uv`を使ったインストール

`uv`は非常に高速なPythonパッケージインストーラーです。
従来のpipと比べて10～100倍高速で、依存関係の解決も賢くなっています。

### 1. `uv`のインストール

**macOS / Linux**の場合:

```bash
# Homebrewでインストール（macOS）
brew install uv

# またはインストールスクリプト（Linux/macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows**の場合:

```powershell
# PowerShellでインストール
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. `haniwers`のインストール

`uv tool install`を使ってインストールします。

```bash
# インストール
uv tool install haniwers

# バージョン確認
haniwers version

# ヘルプ表示
haniwers --help
```

:::{note}

`uv tool install`は、haniwersを独立した環境にインストールするため、他のPythonプロジェクトと干渉しません。

:::

### 運用: アップデートとアンインストール

```bash
# 最新バージョンへアップデート
uv tool upgrade haniwers

# アンインストール
uv tool uninstall haniwers

# インストール済みツール一覧
uv tool list
```

---

## 📦 代替方法: `pipx`を使ったインストール

`pipx`は、Pythonで書かれたCLIツールを独立した環境にインストールするためのツールです。
uvが使えない環境や、従来の方法を好む場合に利用できます。

### 1. `pipx`のインストール

**macOS / Linux**の場合:

```bash
# Homebrewでインストール（macOS）
brew install pipx
pipx ensurepath

# またはpipでインストール（Linux/macOS）
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```

**Windows**の場合:

```powershell
# pipでインストール
python -m pip install --user pipx
python -m pipx ensurepath
```

:::{important}
`pipx ensurepath`実行後、シェルを再起動してください。
:::

### 2. `pipx`で`haniwers`をインストール

```bash
# インストール
pipx install haniwers

# バージョン確認
haniwers version
```

### 運用: `pipx`でのアップデートとアンインストール

```bash
# アップデート
pipx upgrade haniwers

# アンインストール
pipx uninstall haniwers

# インストール済みツール一覧
pipx list
```

---

## 🔧 上級者向け: `pip`を使った仮想環境へのインストール

プロジェクトごとに環境を分けたい場合や、開発用途の場合は`venv`と`pip`を使う従来の方法も利用できます。

### 1. 仮想環境の作成と有効化

```bash
# プロジェクトディレクトリに移動
cd ~/workspaces/daq/

# 仮想環境を作成
python3 -m venv .venv

# 仮想環境を有効化（macOS/Linux）
source .venv/bin/activate

# 仮想環境を有効化（Windows）
.venv\Scripts\activate
```

### 2. 仮想環境に`haniwers`をインストール

```bash
# 仮想環境内にインストール
pip install haniwers

# バージョン確認
haniwers version
```

### 運用: 仮想環境でのアップデートとアンインストール

```bash
# アップデート
pip install -U haniwers

# アンインストール
pip uninstall haniwers

# 仮想環境の無効化
deactivate
```

---

## ❓ よくある質問

### どのインストール方法を選べばよいですか？

- **初心者・一般ユーザー**: `uv`を推奨（高速・簡単・最新）
- **従来の方法に慣れている**: `pipx`も選択肢
- **開発者・複数プロジェクト管理**: `pip` + `venv`

### インストールできない場合は？

1. **Pythonのバージョン確認**: `python --version`（Python 3.9以上が必要）
2. **パスの確認**: `uv`や`pipx`がPATHに含まれているか確認
3. **権限エラー**: `sudo`は不要です（`--user`フラグや`uv tool`を使用）
4. **ネットワークエラー**: プロキシ設定が必要な環境か確認

### アップデート通知を受け取りたい

GitLabのリリースページをWatch設定するか、PyPIのRSS feedを購読してください。

- [GitLab Releases](https://gitlab.com/qumasan/haniwers/-/releases)
- [PyPI Project Page](https://pypi.org/project/haniwers/)

---

## 🎯 次のステップ

インストールが完了したら、[測定ワークフロー](./measurement/index.md)で実際のデータ収集方法を学びましょう。

- [ポート管理](./measurement/port.md): OSECHI検出器の接続確認
- [データ取得](./measurement/daq.md): 宇宙線データの収集
- [閾値スキャン](./measurement/scan.md): 検出効率の最適化