Metadata-Version: 2.4
Name: kikaiken-kst
Version: 0.3.0
Summary: STM32 build tool for non-CubeIDE editors
Requires-Python: >=3.13
Requires-Dist: typer>=0.26.7
Description-Content-Type: text/markdown

# kst

STM32CubeIDE プロジェクトを VS Code などの外部エディタでビルド・書き込みするための CLI ツールです。

`.ioc` ファイルと CubeIDE の内蔵ツールチェーンだけに依存するため、CubeIDE ユーザーのワークフローを一切変えずに、エディタを選ばない開発環境を実現します。

## 前提条件

- Windows
- STM32CubeIDE がインストール済み（`C:\ST\STM32CubeIDE_*`）
- Python 3.13 以上

## インストール

### 1. パッケージをインストールする

```bash
pip install --user kikaiken-kst
```

### 2. Scripts ディレクトリを PATH に追加する

`pip install --user` は `kst.exe` を以下のディレクトリに配置します。

```
C:\Users\<ユーザー名>\AppData\Roaming\Python\Python3xx\Scripts
```

このディレクトリが PATH に含まれていない場合、以下の手順で追加してください。

**PowerShell で自動追加（一度だけ実行）:**

```powershell
$scriptsPath = "$env:APPDATA\Python\$(python -c 'import sys; print(f\"Python{sys.version_info.major}{sys.version_info.minor}\")')\Scripts"
[Environment]::SetEnvironmentVariable("PATH", "$([Environment]::GetEnvironmentVariable('PATH','User'));$scriptsPath", "User")
```

設定後、ターミナルを再起動すると `kst` コマンドが使えるようになります。

### アップデート

```bash
pip install --user --upgrade kikaiken-kst
```

## 使い方

### 1. 初期化（初回・CubeMX 再生成後）

```bash
kst init <プロジェクトディレクトリ>
```

- `.clangd` を生成（VS Code + clangd の IntelliSense 設定）
- `compile_commands.json` を生成（clangd が IntelliSense に使用）
- `kst.toml` を生成（ビルド設定ファイル）
- `.gitignore` に kst の生成物を追加

### 2. ビルド

```bash
kst build <プロジェクトディレクトリ>
```

- `.ioc` を解析して MCU フラグを取得
- プロジェクトを走査してソース・インクルードを収集
- `Makefile.kst` と `compile_commands.json` を生成
- CubeIDE 内蔵の gcc / make でビルド

### 3. 書き込み

```bash
kst flash <プロジェクトディレクトリ>
```

ビルドを行ってから、CubeIDE 内蔵の STM32CubeProgrammer を使って ST-LINK 経由で書き込みます。  
接続モードは CubeIDE のデフォルト（Under Reset + Hardware Reset）に合わせています。

ビルド済みの ELF をそのまま書き込む場合は `--no-build` を指定します。

```bash
kst flash --no-build <プロジェクトディレクトリ>
```

### 4. クリーン

```bash
kst clean <プロジェクトディレクトリ>
```

`kst_build/` ディレクトリを削除します。

---

プロジェクトディレクトリの指定を省略するとカレントディレクトリが使われます。

```bash
cd path/to/project
kst build
```

## kst.toml

`kst init` で生成されるプロジェクト設定ファイルです。git で管理してチームで共有します。

```toml
[build]
# printf / scanf での浮動小数点数の出力・入力を有効にする
# newlib-nano のデフォルトでは無効のため約 +20 KB 増加する
float_io = true

[scan]
# コンパイル対象から除外するファイル（プロジェクトルートからの相対パス）
# 同じディレクトリに排他的な実装が複数ある場合に使用する
exclude_files = []
```

## 仕組み

| 役割 | CubeIDE | kst |
|---|---|---|
| MCU フラグ取得 | `.cproject` | `.ioc` を解析 |
| ソース収集 | GUI で手動登録 | フォルダをスキャンして自動収集 |
| ビルド | CDT make | 同じ CubeIDE 内蔵 gcc / make |
| 書き込み | ST-LINK GDB Server | 同じ CubeIDE 内蔵 STM32CubeProgrammer |
| IntelliSense | CDT Indexer | clangd + `compile_commands.json` |

## git 管理について

| ファイル | git 管理 | 説明 |
|---|---|---|
| `kst.toml` | ✅ する | プロジェクト共通のビルド設定 |
| `kst_build/` | ❌ しない | ビルド成果物 |
| `Makefile.kst` | ❌ しない | `kst build` で毎回生成 |
| `.clangd` | ❌ しない | 環境依存（CubeIDE のインストールパスを含む） |
| `compile_commands.json` | ❌ しない | 環境依存 |

## CubeIDE ユーザーへの影響

**ありません。** `.ioc` の Toolchain/IDE 設定は `STM32CubeIDE` のままです。  
CubeIDE ユーザーは従来通り CubeIDE でビルド・書き込みできます。
