# ark shell

**Repository Path**: xw19981010/ark-shell

## Basic Information

- **Project Name**: ark shell
- **Description**: 此项目为SVCRTOS的ark c Compiler衍生项目，用于指令的操作，方便实现在stm32上编译stm32程序
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ark Shell

一个专为嵌入式系统设计的轻量级命令行 Shell 组件，极其便于移植，支持多种串口工作模式。

## 特性

- **极致可移植**：平台抽象层仅 8 个函数，移植到新 MCU 只需实现这 8 个函数
- **三种串口模式**：支持 POLL（轮询）/ IRQ（中断）/ DMA 三种工作模式，可运行时切换
- **完整行编辑**：支持光标移动、字符插入删除、单词删除等操作
- **命令历史**：上下箭头翻阅历史命令，环形缓冲存储
- **Tab 自动补全**：前缀匹配，公共前缀补全，双击 Tab 列出全部候选
- **ANSI 颜色**：支持 VT100 转义序列，彩色提示符和错误信息
- **Ctrl 快捷键**：支持 Ctrl+A/B/C/E/F/K/L/U/W 等常用快捷键
- **历史搜索**：可选的 Ctrl+R 反向搜索功能
- **C99 标准**：纯 C99 编写，兼容 ARM Compiler 5 (armcc) / GCC / IAR
- **零动态内存**：全静态分配，适合资源受限的 MCU

## 项目结构

```
arkshell/
├── platform/
│   ├── platform.h                 # 平台抽象层接口（8 个函数 + UART 模式枚举）
│   ├── platform_linux.c           # PC 模拟实现（Linux/macOS/Windows MinGW）
│   └── platform_port_template.c   # MCU 移植模板（STM32 等）
├── src/
│   ├── ark_shell_config.h         # 全局配置（尺寸/功能开关/颜色）
│   ├── ark_shell.h / ark_shell.c  # 主框架（状态机/主循环/命令执行）
│   ├── ark_shell_line_editor.h/.c # 行编辑器（插入/删除/光标/重绘）
│   ├── ark_shell_history.h / .c   # 历史系统（环形数组/上下箭头/搜索）
│   ├── ark_shell_commands.h / .c  # 命令注册（ARK_SHELL_CMD 宏/查找/内置命令）
│   └── ark_shell_autocomplete.h/.c# Tab 补全（前缀匹配/公共前缀/候选列表）
├── main.c                         # PC 演示入口
└── 从零手搓嵌入式Shell完整指南.md   # 设计文档
```

## 快速开始

### PC 模拟编译运行

```bash
gcc -o shell_test main.c src/ark_shell.c src/ark_shell_line_editor.c \
    src/ark_shell_history.c src/ark_shell_commands.c src/ark_shell_autocomplete.c \
    platform/platform_linux.c -Isrc -Iplatform -std=c99 -Wall -Wextra
./shell_test
```

运行后会出现：

```
Ark Shell v1.0
Type 'help' for commands.

ark>
```

### 移植到 MCU

1. 复制 `platform/platform_port_template.c` 为 `platform_<mcu>.c`
2. 实现其中的 8 个平台函数（参考模板中的 TODO 注释）
3. 编译时排除 `platform_linux.c`，链接你的 `platform_<mcu>.c`
4. 在 `main()` 中调用 `ark_shell_init()` 初始化，然后在主循环调用 `ark_shell_run()`

详细移植步骤请参考 [用户手册](USER_MANUAL.md)。

## 内置命令

| 命令     | 说明                        |
| -------- | --------------------------- |
| `help`   | 显示所有可用命令            |
| `clear`  | 清屏                        |
| `version`| 显示 Shell 版本信息         |
| `echo`   | 回显参数                    |
| `reboot` | 重启系统                    |
| `mode`   | 切换串口工作模式（演示用）  |

## 快捷键

| 快捷键          | 功能               |
| --------------- | ------------------ |
| `Tab`           | 自动补全           |
| `↑` / `↓`       | 历史命令翻阅       |
| `Ctrl+A`        | 光标移到行首       |
| `Ctrl+E`        | 光标移到行尾       |
| `Ctrl+B`        | 光标左移           |
| `Ctrl+F`        | 光标右移           |
| `Ctrl+C`        | 中断当前输入       |
| `Ctrl+L`        | 清屏               |
| `Ctrl+U`        | 删除到行首         |
| `Ctrl+K`        | 删除到行尾         |
| `Ctrl+W`        | 删除前一个单词     |
| `Ctrl+R`        | 历史搜索（可选）   |
| `Backspace`     | 删除光标前字符     |
| `Delete`        | 删除光标处字符     |
| `Home` / `End`  | 行首 / 行尾        |

## 配置

所有配置项集中在 `src/ark_shell_config.h`，可在移植时调整：

| 配置项                          | 默认值 | 说明                |
| ------------------------------- | ------ | ------------------- |
| `ARK_SHELL_LINE_SIZE`           | 128    | 命令行最大长度      |
| `ARK_SHELL_MAX_ARGS`            | 16     | 最大参数个数        |
| `ARK_SHELL_MAX_COMMANDS`        | 32     | 命令表容量          |
| `ARK_SHELL_HISTORY_CAPACITY`    | 32     | 历史条数            |
| `ARK_SHELL_ENABLE_HISTORY`      | 1      | 启用历史            |
| `ARK_SHELL_ENABLE_AUTOCOMPLETE` | 1      | 启用 Tab 补全       |
| `ARK_SHELL_ENABLE_COLOR`        | 1      | 启用 ANSI 颜色      |
| `ARK_SHELL_ENABLE_HISTORY_SEARCH`| 0     | 启用 Ctrl+R 搜索    |

## 目标平台

- STM32 系列（STM32H743、STM32F401 等）
- 其他 ARM Cortex-M MCU
- Linux / macOS / Windows（PC 模拟开发）

## 许可证

MIT License