# インストールガイド

このガイドを読むと、haniwers を簡単にインストールできます。あなたの環境に合わせた方法を選んでください。

## クイックスタート（初心者向け推奨）

もっとも簡単な方法は **`uv run --with`** です。インストール不要で即座に実行できます：

```bash
# インストール不要！ こちらのコマンドで即座に実行
uv run --with haniwers==0.24.2 haniwers version
```

```bash
# 測定開始
uv run --with haniwers==0.24.2 haniwers daq
```

**これだけです！** uvがあれば、すぐにhaniwersを使い始められます。

::::{admonition} uvがない場合
:class: note

uvをまだインストールしていない場合は、下の「**1. uvでインストール**」を読んでください。
または、「**2. pipxでインストール**」でpipxをインストールして使用することもできます。
::::

---

## インストール方法の比較

3 つのインストール方法があります。
あなたの用途に合わせて選んでください。

| 方法 | 難易度 | 推奨ユーザー | 特徴 |
|------|--------|------------|------|
| **uv** | ⭐ 簡単 | 新しいツールを試したい人 | 最新、高速、推奨 |
| **pipx** | ⭐ 簡単 | ツールとして使いたい人 | 安定、シンプル、依存関係の分離 |
| **pip + 仮想環境** | ⭐⭐ 中程度 | 開発者、複数プロジェクト管理 | 標準的、安全 |
| **Poetry** | ⭐⭐⭐ 難しい | 開発に参加したい人 | 完全な開発環境 |

---

## 1. uv でインストール（最新推奨）

**メリット：** 最も高速、最も新しい、開発が盛ん

### uvのインストール

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

# または、pipでインストール
pip install uv

# パスの確認
uv --version
```

### haniwers の実行方法

#### 方法 A: インストール不要（推奨）

```bash
# インストール不要で即座に実行
uv run --with haniwers==0.24.2 haniwers version
```

#### 方法 B: ツールとしてインストール

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

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

### アップデート

```bash
uv tool upgrade haniwers
```

### アンインストール

```bash
uv tool uninstall haniwers
```

---

## 2. pipx でインストール（初心者向け推奨）

**メリット：** シンプル、どこからでも使える、依存関係の分離

### pipx のインストール

pipx をまだインストールしていない場合：

```bash
# macOS（Homebrewおすすめ）
brew install pipx

# Linux
pip3 install --user pipx
export PATH=$PATH:~/.local/bin

# Windows（WSL推奨）
pip install pipx
```

### haniwers のインストール

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

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

### アップデート

```bash
pipx upgrade haniwers
```

### アンインストール

```bash
pipx uninstall haniwers
```

### 使用方法

インストール後は、どのディレクトリからでも使用できます：

```bash
# どこからでも実行可能
haniwers daq --help
haniwers version
haniwers ports
```

---

## 3. pip + 仮想環境でインストール（開発者向け）

**メリット：** 複数プロジェクトを管理できる、カスタマイズ可能

### インストール手順

```bash
# 1. 作業用ディレクトリを作成
mkdir ~/haniwers-workspace
cd ~/haniwers-workspace

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

# 3. 仮想環境を有効化
source .venv/bin/activate

# 4. haniwers をインストール
pip install haniwers

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

**Windows の場合：**

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

# 以降は同じ
pip install haniwers
```

### 仮想環境の有効化（毎回必要）

```bash
# macOS / Linux
cd ~/haniwers-workspace
source .venv/bin/activate

# Windows
cd ~/haniwers-workspace
.venv\Scripts\activate
```

有効化されると、プロンプトが以下のように変わります：

```
(.venv) $
```

### アップデート

```bash
(.venv) $ pip install -U haniwers
```

### アンインストール

```bash
(.venv) $ pip uninstall haniwers
```

### 複数の Python バージョン

特定の Python バージョンで使いたい場合：

```bash
# Python 3.11 で仮想環境を作成
python3.11 -m venv .venv
```

---

## 4. 開発環境のセットアップ（開発者向け）

**メリット：** 最新コード、テスト実行、コード変更可能

### 前提条件

- Git
- Python 3.9 以上
- Poetry

### インストール手順

```bash
# 1. リポジトリをクローン
git clone https://gitlab.com/qumasan/haniwers.git
cd haniwers

# 2. Poetry で依存関係をインストール
poetry install

# 3. バージョン確認
poetry run haniwers version
```

### 開発時のコマンド

```bash
# haniwers を実行
poetry run haniwers daq --help

# テストを実行
poetry run pytest

# コードをフォーマット
poetry run ruff format

# 型チェック
poetry run mypy haniwers
```

詳細は [開発ガイド](dev/index.md) を参照してください。

---

## トラブルシューティング

### 問題：「haniwers: command not found」

**解決方法：**

インストール確認：

```bash
# pipx の場合
pipx list

# pip + 仮想環境の場合
source .venv/bin/activate
which haniwers

# uv の場合
uv tool list
```

### 問題：「Permission denied」エラー

**解決方法：** `sudo` は使わず、pipx または仮想環境を使います：

```bash
# 推奨: pipx を使用
pipx install haniwers

# または仮想環境を作成
python3 -m venv .venv
source .venv/bin/activate
pip install haniwers
```

### 問題：Python のバージョンが古い

**確認方法：**

```bash
python3 --version
# Python 3.9 以上が必要
```

**解決方法：**

```bash
# macOS（Homebrew）
brew install python@3.11

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.11

# その後、指定したバージョンで仮想環境を作成
python3.11 -m venv .venv
source .venv/bin/activate
pip install haniwers
```

### 問題：Windows で動作しない

**解決方法：** Windows Subsystem for Linux（WSL）の使用を推奨します：

```bash
# WSL で実行
wsl

# Linux コマンドを使用
sudo apt-get update
sudo apt-get install python3 python3-pip
pip install pipx
pipx install haniwers
```

---

## システム要件

| 項目 | 要件 |
|-----|-----|
| **OS** | Linux, macOS, Windows（WSL推奨） |
| **Python** | 3.9 以上 |
| **インターネット** | インストール時に必要 |
| **ディスク** | 約 100 MB |

---

## プラットフォーム別の注意事項

### macOS

Apple Silicon（M1/M2）の場合：

```bash
# Homebrew で Python をインストール（推奨）
brew install python@3.11

# または uv を使用（自動的に対応）
brew install uv
uv tool install haniwers
```

Intel Mac の場合：

```bash
brew install python@3.11
pipx install haniwers
```

### Linux（Ubuntu/Debian）

```bash
# 必要なパッケージをインストール
sudo apt-get update
sudo apt-get install python3 python3-pip

# pipx をインストール
pip3 install --user pipx

# パスを設定
export PATH=$PATH:~/.local/bin

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

### Windows

WSL を推奨しますが、ネイティブ Windows でも動作します：

```bash
# Python 3.11 をインストール
# https://www.python.org からダウンロード

# コマンドプロンプトまたは PowerShell で実行
python -m pip install pipx
pipx install haniwers
```

---

## インストール確認

インストール後、以下のコマンドで正常に動作確認できます：

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

# 利用可能なコマンド確認
haniwers --help

# ポート確認（検出器接続確認）
haniwers ports
```

すべてのコマンドが実行できれば、インストール完了です！🎉

---

## 次のステップ

インストール後に進むステップ：

1. **[セットアップ](usage/setup.md)** - 検出器接続の設定
2. **[ワークフロー](usage/workflows.md)** - 最初の測定を実行
3. **[コマンドリファレンス](command/index.md)** - 利用可能なコマンド確認

---

## よくある質問（FAQ）

### Q: uv、pipx、pip どれを使えばいい？

**A:** 初心者なら **uv** または **pipx** を推奨します。開発に参加する場合は **Poetry** を使用してください。

### Q: アンインストールしたい場合は？

**A:** インストール方法に応じて：

```bash
# uv の場合
uv tool uninstall haniwers

# pipx の場合
pipx uninstall haniwers

# pip + 仮想環境の場合
pip uninstall haniwers
```

### Q: 最新版に更新したい場合は？

**A:** インストール方法に応じて：

```bash
# uv の場合
uv tool upgrade haniwers

# pipx の場合
pipx upgrade haniwers

# pip + 仮想環境の場合
pip install -U haniwers
```

### Q: 複数のバージョンを同時に使いたい場合は？

**A:** 複数の仮想環境を作成してください：

```bash
# バージョン 0.23
mkdir ~/workspace-v023
cd ~/workspace-v023
python3 -m venv .venv
source .venv/bin/activate
pip install haniwers==0.23.1

# バージョン 0.22
mkdir ~/workspace-v022
cd ~/workspace-v022
python3 -m venv .venv
source .venv/bin/activate
pip install haniwers==0.22.0
```

---

## サポート

問題が発生した場合：

1. [トラブルシューティング](#トラブルシューティング) セクションを確認
2. [よくある質問](#よくある質問faq) を確認
3. [Issues](https://gitlab.com/qumasan/haniwers/-/issues) を確認または作成