Skip to content

extensions_overview.md

Latest commit

 

History

History
69 lines (52 loc) · 4.68 KB

extensions_overview.md

File metadata and controls

69 lines (52 loc) · 4.68 KB
Raw

Extensions Overview

All extensions are optional and gated by ZOOM_USING_* macros in zoom_shell_cfg_user.h. Most default to 0 (see zoom_shell_cfg.h for the authoritative defaults).

The core library (src/) does not depend on any extension. Once an extension is compiled into the project, its commands are registered either through a linker section or a static table.

1. Core feature switches (not in the extensions directory)

Macro Default Description
ZOOM_USING_CMD_EXPORT 1 Export commands via a linker section; when set to 0, the static-array mode is used
ZOOM_USING_HISTORY 1 Command history
ZOOM_USING_USER 1 Users / login / permissions
ZOOM_USING_VAR 1 Variable inspection var
ZOOM_USING_PLUGIN 0 Static plugin table
ZOOM_USING_LOCK 0 Shell mutex callbacks
ZOOM_USING_PERF 1 Command timing perf
ZOOM_USING_ANSI 1 Colors, arrow keys, Tab completion, and so on
ZOOM_USING_AUDIT_LOG 0 Audit log

2. Extension modules at a glance

Macro Source path Shell / API summary
ZOOM_USING_HEXDUMP extensions/hexdump/zoom_shell_hexdump.c mem read/write/dump memory inspection (dangerous; use with care)
ZOOM_USING_LOG extensions/log/ zoom_log.h: ZOOM_LOGI and friends; commands log level/on/off/test
ZOOM_USING_CALC extensions/calc/zoom_shell_calc.c calc <expression>
ZOOM_USING_PASSTHROUGH extensions/passthrough/zoom_shell_passthrough.c passthrough; Ctrl+D to exit; requires a registered callback
ZOOM_USING_REPEAT extensions/repeat/zoom_shell_repeat.c repeat <ms> <cmd> / repeat stop; works with the tick inside zoom_shell_run
ZOOM_USING_KEYBIND extensions/keybind/ Ctrl-key combinations; keybind list; zoom_shell_keybind_init
ZOOM_USING_ALIAS extensions/alias/zoom_shell_alias.c alias; first-word alias expansion
ZOOM_USING_SCRIPT extensions/script/zoom_shell_script.c script define/run/list/delete
ZOOM_USING_PROGRESS extensions/progress/ progress demo; APIs such as zoom_progress_bar
ZOOM_USING_GAME extensions/game/ Shell commands: game_2048, pushbox, snake
ZOOM_USING_AI_BRIDGE extensions/ai_bridge/zoom_shell_ai_bridge.c ai url/ask/status; see ai_bridge.md
ZOOM_USING_SESSION extensions/session/ session save/list/replay/...; record terminal output to a ring buffer, snapshot & replay by name. See session.md
ZOOM_USING_JOURNAL extensions/journal/ journal record/export/replay/...; auto-capture executed commands, move to another board, re-run. See journal.md
(no dedicated macro; header only) extensions/cpp_support/zoom_shell_cpp.h Include this header when exporting commands from C++
(depends on the network stack) extensions/telnet/ Telnet service; requires socket callbacks

3. Capacity macros (extension-related)

Macro Meaning
ZOOM_ALIAS_MAX Number of aliases
ZOOM_SCRIPT_MAX_LINES / ZOOM_SCRIPT_MAX Script line count and number of scripts
ZOOM_KEYBIND_MAX Number of key bindings
ZOOM_LOG_BUFFER_SIZE Per-message log buffer size
ZOOM_AI_URL_MAX / ZOOM_AI_RESP_MAX AI bridge URL length and response length

4. Adding extensions to your build

  • Refer to EXT_SRCS in the official Makefile and pull what you need into your own build system.
  • When ZOOM_USING_CMD_EXPORT is used, the linker script must retain the zoomCommand / zoomVar / zoomUser sections (see porting_general.md).
  • After modifying zoom_shell_cfg_user.h, it is recommended to run make clean and then do a full rebuild to avoid macros and object files getting out of sync.

5. Coupling points with the core

Some extensions have hooks inside zoom_shell_core.c (passthrough, repeat, alias, script, key bindings, and so on). When the corresponding macro is disabled, that code is not compiled in.