Skip to content

Commit d2d79f9

Browse files
committed
feat: add shell tab completion for bash, zsh, PowerShell and fish
1 parent dd53e6d commit d2d79f9

12 files changed

Lines changed: 924 additions & 74 deletions

‎.github/workflows/ci-linux.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,16 @@ jobs:
5252
run: |
5353
"$MCPP_FRESH" test
5454
55+
- name: Shell completion in bash, zsh, PowerShell and fish
56+
env:
57+
MCPP_REQUIRE_SHELLS: "1"
58+
run: |
59+
set -euo pipefail
60+
sudo apt-get update
61+
sudo apt-get install -y zsh fish
62+
command -v pwsh
63+
MCPP="$MCPP_FRESH" bash tests/e2e/894_shell_completion.sh
64+
5565
# Each package under `modules/` carries its own tests, and they are built
5666
# as that package ALONE -- a configuration the root suite never produces,
5767
# since there every module is linked together. A subsystem that has

‎.github/workflows/ci-windows.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ jobs:
4141
export MCPP_VENDORED_XLINGS=$(cygpath -w "$USERPROFILE/.xlings/subos/default/bin/xlings.exe")
4242
"$MCPP_SELF" test
4343
44+
- name: Native PowerShell completion
45+
shell: pwsh
46+
run: |
47+
$env:MCPP = $env:MCPP_FRESH
48+
python tests/scripts/test_shell_completion.py ShellCompletionTests.test_powershell ShellCompletionTests.test_query_is_read_only_and_does_not_execute_partial_commands
49+
4450
# WS8: this row has Visual Studio, so its answer is the "Windows with
4551
# usable MSVC" row of docs/01 and docs/20.
4652
- name: The documented default toolchain is this host's answer

‎docs/01-getting-started.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,48 @@ mcpp --version
7373
> rather than using `source`, and verify the active command with
7474
> `Get-Command mcpp.exe`.
7575
76+
### Shell completion
77+
78+
mcpp provides Tab completion for bash, zsh, PowerShell (`pwsh`) and fish.
79+
Generate all four scripts, or select one shell:
80+
81+
```bash
82+
mcpp self completion
83+
mcpp self completion bash
84+
```
85+
86+
Scripts are written to `<mcpp-home>/config/shell/`. This command does not
87+
initialize a toolchain or access the network. Normal sandbox initialization
88+
also creates the scripts. Repeating the command updates generated scripts;
89+
keep local customizations in the shell's own configuration file.
90+
91+
For the default `~/.mcpp` home, add the corresponding line to the configuration
92+
file below and start a new shell, or execute the line in the current session:
93+
94+
| Shell | Configuration file | Loading command |
95+
|---|---|---|
96+
| bash | `~/.bashrc` | `source ~/.mcpp/config/shell/mcpp.bash` |
97+
| zsh | `${ZDOTDIR:-$HOME}/.zshrc` | `source ~/.mcpp/config/shell/mcpp.zsh` |
98+
| fish | `$XDG_CONFIG_HOME/fish/config.fish`, or `~/.config/fish/config.fish` | `source ~/.mcpp/config/shell/mcpp.fish` |
99+
| PowerShell | `$PROFILE.CurrentUserAllHosts` | `. "$HOME/.mcpp/config/shell/mcpp.ps1"` |
100+
101+
Use the actual mcpp home for a standalone custom prefix or an explicit
102+
`MCPP_HOME`. zsh initializes its completion system if it is not already active;
103+
when the configuration calls `compinit`, load the mcpp script after that call.
104+
In PowerShell, create the profile's parent directory and file if absent.
105+
106+
The standalone installer generates the scripts and appends a loading command
107+
for the shell identified by `SHELL`. Reinstallation does not append the same
108+
command twice. `MCPP_NO_COMPLETION=1` disables this profile change;
109+
`MCPP_NO_PATH=1` independently disables its PATH change. Unknown shells receive
110+
manual loading instructions.
111+
112+
Completion covers commands, nested subcommands, long and short options, and
113+
built-in values such as cache modes, profiles and mirrors. File arguments use
114+
the shell's filename completion. Completion queries do not run project scripts,
115+
install dependencies or access registries. Package names, custom profiles,
116+
target names and registry versions are not dynamically queried.
117+
76118
## Creating a Project
77119

78120
```bash
@@ -267,4 +309,3 @@ For the differences between the four modes and their artifact layouts, see [10
267309
- Explaining default decisions: `mcpp why [toolchain|runtime|deps]`; host capability checkup: `mcpp self doctor`;
268310
machine-readable resolution manifest: the build artifact `target/<triple>/<fp>/resolution.json`.
269311
- Offline operation: `mcpp --offline` or `MCPP_OFFLINE=1` prevents index refreshes, downloads, and toolchain installation. In a home that has never been used it also skips the first-use sandbox bootstrap (index clone, ninja, patchelf), announces the skip once, and leaves the home un-bootstrapped; commands that need those tools report it.
270-

‎docs/zh/01-getting-started.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,43 @@ mcpp --version
7070
> 命令安装,重启 PowerShell 而不是执行 `source`,并用
7171
> `Get-Command mcpp.exe` 确认当前生效的命令。
7272
73+
### Shell 补全
74+
75+
mcpp 为 bash、zsh、PowerShell(`pwsh`)和 fish 提供 Tab 补全。
76+
以下命令生成全部四种脚本,或仅生成指定 shell 的脚本:
77+
78+
```bash
79+
mcpp self completion
80+
mcpp self completion bash
81+
```
82+
83+
脚本写入 `<mcpp-home>/config/shell/`。该命令不初始化工具链,也不访问网络。
84+
正常的沙箱初始化也会生成这些脚本。重复执行会更新生成的脚本;本地自定义配置
85+
放在 shell 自身的配置文件中。
86+
87+
使用默认 `~/.mcpp` home 时,将对应加载语句加入下表中的配置文件并启动新 shell,
88+
或在当前会话直接执行该语句:
89+
90+
| Shell | 配置文件 | 加载语句 |
91+
|---|---|---|
92+
| bash | `~/.bashrc` | `source ~/.mcpp/config/shell/mcpp.bash` |
93+
| zsh | `${ZDOTDIR:-$HOME}/.zshrc` | `source ~/.mcpp/config/shell/mcpp.zsh` |
94+
| fish | `$XDG_CONFIG_HOME/fish/config.fish`,未设置时为 `~/.config/fish/config.fish` | `source ~/.mcpp/config/shell/mcpp.fish` |
95+
| PowerShell | `$PROFILE.CurrentUserAllHosts` | `. "$HOME/.mcpp/config/shell/mcpp.ps1"` |
96+
97+
独立安装的自定义前缀或显式设置的 `MCPP_HOME` 使用实际的 mcpp home 路径。
98+
zsh 的补全系统尚未启用时,脚本会初始化它;配置中已有 `compinit` 调用时,
99+
在该调用之后加载 mcpp 脚本。PowerShell 的 profile 文件及其父目录不存在时,
100+
先创建它们。
101+
102+
独立安装器会生成脚本,并为 `SHELL` 标识的 shell 追加加载语句。重复安装不会
103+
重复追加同一条语句。`MCPP_NO_COMPLETION=1` 关闭这一配置文件修改;
104+
`MCPP_NO_PATH=1` 独立控制 PATH 修改。未识别的 shell 会收到手动加载提示。
105+
106+
补全覆盖命令、嵌套子命令、长短选项,以及缓存模式、构建 profile、镜像等内置值。
107+
文件参数使用 shell 原生文件名补全。补全查询不执行项目脚本、不安装依赖,也不访问
108+
索引。包名、自定义 profile、目标名称和索引中的版本不进行动态查询。
109+
73110
## 创建项目
74111

75112
```bash

‎install.sh‎

Lines changed: 68 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@
88
# MCPP_VERSION — pin a specific version (default: latest)
99
# MCPP_PREFIX — install root (default: $HOME/.mcpp)
1010
# MCPP_NO_PATH — set to skip shell-rc PATH editing
11+
# MCPP_NO_COMPLETION — set to skip shell-rc completion editing
1112
#
1213
# Layout afterwards (PREFIX = $HOME/.mcpp by default):
1314
# $PREFIX/bin/{mcpp,xlings} ← binary + pinned bundled xlings
15+
# $PREFIX/config/shell/ ← sourceable shell completion scripts
1416
# $PREFIX/registry/ ← seeded on first `mcpp` invocation
1517
# $PREFIX/... ← mcpp's full self-contained tree
1618
#
@@ -21,6 +23,8 @@ set -euo pipefail
2123
REPO="mcpp-community/mcpp"
2224
VERSION="${MCPP_VERSION:-latest}"
2325
PREFIX="${MCPP_PREFIX:-$HOME/.mcpp}"
26+
shell_name="${SHELL:-}"
27+
shell_name="${shell_name##*/}"
2428

2529
# ---- platform detection ---------------------------------------------------
2630
# OS+arch → release asset platform tag. Linux reports the arch as aarch64;
@@ -126,22 +130,46 @@ mkdir -p "$PREFIX"
126130
echo ":: Extracting to $PREFIX"
127131
tar -xzf "$WORK/mcpp.tar.gz" -C "$PREFIX" --strip-components=1
128132

133+
# Older pinned releases predate completion. Probe help without initialization.
134+
completion_available=0
135+
if "$PREFIX/bin/mcpp" self --help 2>/dev/null | grep 'completion' >/dev/null; then
136+
MCPP_HOME="$PREFIX" "$PREFIX/bin/mcpp" self completion
137+
completion_available=1
138+
fi
139+
129140
# ---- PATH integration -----------------------------------------------------
130-
if [[ -z "${MCPP_NO_PATH:-}" ]]; then
131-
rc=""
132-
case "${SHELL##*/}" in
133-
bash) rc="$HOME/.bashrc" ;;
134-
zsh) rc="${ZDOTDIR:-$HOME}/.zshrc" ;;
135-
fish) rc="$HOME/.config/fish/config.fish" ;;
141+
rc=""
142+
case "$shell_name" in
143+
bash) rc="$HOME/.bashrc" ;;
144+
zsh) rc="${ZDOTDIR:-$HOME}/.zshrc" ;;
145+
fish) rc="${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish" ;;
146+
pwsh)
147+
if command -v pwsh >/dev/null 2>&1; then
148+
rc=$(pwsh -NoProfile -Command '$PROFILE.CurrentUserAllHosts')
149+
fi ;;
150+
esac
151+
shell_quote() {
152+
local value="$1"
153+
case "$shell_name" in
154+
pwsh) value="${value//\'/\'\'}" ;;
155+
fish)
156+
value="${value//\\/\\\\}"
157+
value="${value//\'/\\\'}" ;;
158+
*) value="${value//\'/\'\\\'\'}" ;;
136159
esac
160+
printf "'%s'" "$value"
161+
}
162+
if [[ -z "${MCPP_NO_PATH:-}" ]]; then
137163
if [[ -n "$rc" ]]; then
138-
if [[ "${SHELL##*/}" == "fish" ]]; then
139-
line="set -gx PATH \"$PREFIX/bin\" \$PATH"
140-
else
141-
line="export PATH=\"$PREFIX/bin:\$PATH\""
142-
fi
164+
quoted_bin=$(shell_quote "$PREFIX/bin")
165+
case "$shell_name" in
166+
fish) line="set -gx PATH $quoted_bin \$PATH" ;;
167+
pwsh) line="\$env:PATH = $quoted_bin + [IO.Path]::PathSeparator + \$env:PATH" ;;
168+
*) line="export PATH=$quoted_bin:\"\$PATH\"" ;;
169+
esac
143170
mkdir -p "$(dirname "$rc")"
144-
if ! grep -Fqs "$PREFIX/bin" "$rc" 2>/dev/null; then
171+
if ! grep -Fqx "$line" "$rc" 2>/dev/null \
172+
&& ! grep -Fqs "$PREFIX/bin" "$rc" 2>/dev/null; then
145173
printf '\n# mcpp\n%s\n' "$line" >> "$rc"
146174
echo ":: Added $PREFIX/bin to PATH via $rc"
147175
else
@@ -153,13 +181,39 @@ if [[ -z "${MCPP_NO_PATH:-}" ]]; then
153181
fi
154182
fi
155183

184+
# ---- completion integration ----------------------------------------------
185+
if [[ -z "${MCPP_NO_COMPLETION:-}" && "$completion_available" == 1 ]]; then
186+
if [[ -n "$rc" ]]; then
187+
extension="$shell_name"
188+
[[ "$shell_name" == pwsh ]] && extension=ps1
189+
script="$PREFIX/config/shell/mcpp.$extension"
190+
quoted_script=$(shell_quote "$script")
191+
if [[ "$shell_name" == pwsh ]]; then
192+
line="if (Test-Path -LiteralPath $quoted_script) { . $quoted_script }"
193+
elif [[ "$shell_name" == fish ]]; then
194+
line="test -f $quoted_script; and source $quoted_script"
195+
else
196+
line="[ ! -f $quoted_script ] || source $quoted_script"
197+
fi
198+
mkdir -p "$(dirname "$rc")"
199+
if ! grep -Fqx "$line" "$rc" 2>/dev/null; then
200+
printf '\n# mcpp completion\n%s\n' "$line" >> "$rc"
201+
echo ":: Enabled completion via $rc"
202+
fi
203+
else
204+
echo ":: Completion scripts: $PREFIX/config/shell/ (source the script for your shell)"
205+
fi
206+
fi
207+
156208
# ---- verify install -------------------------------------------------------
157209
echo
158210
"$PREFIX/bin/mcpp" --version
159211
echo
160212
echo "✓ mcpp installed at $PREFIX"
161-
if [[ -n "${rc:-}" ]]; then
162-
echo " Open a new shell (or 'source $rc') and run: mcpp --help"
213+
if [[ -n "${rc:-}" && -f "$rc" ]]; then
214+
load_command="source $(shell_quote "$rc")"
215+
[[ "$shell_name" == pwsh ]] && load_command=". $(shell_quote "$rc")"
216+
echo " Open a new shell (or $load_command) and run: mcpp --help"
163217
else
164218
echo " Add $PREFIX/bin to your PATH, then run: mcpp --help"
165219
fi

0 commit comments

Comments
 (0)