Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (62 loc) · 4.41 KB

AGENTS.md

File metadata and controls

84 lines (62 loc) · 4.41 KB
Raw

AGENTS.md

This file provides guidance to AI coding agents working with code in this repository.

Build Commands

# Build for local platform - htop binary
./autogen.sh && ./configure && make

# Build with Performance Co-Pilot (PCP) support - pcp-htop binary
./autogen.sh && ./configure --enable-pcp && make

# Rebuild after code changes (no autogen needed)
make

Key configure flags: --enable-capabilities, --enable-debug, --enable-delayacct, --enable-pcp, --enable-sensors, --enable-unicode.

Code Style (from docs/styleguide.md)

  • Indentation: 3 spaces, never tabs
  • Filenames: CamelCase.c/.h (exceptions: htop.c, pcp-htop.c); directories lowercase
  • Functions: ModuleName_functionName() (e.g. Process_compare())
  • Variables: short and precise (i not someCounterValueForLoop); module-private globals must be static
  • Header guards: #ifndef HEADER_FILENAME placed before the copyright comment
  • Include order (each group separated by blank line):
    1. #include "config.h" // IWYU pragma: keep (required if using XUtils.h)
    2. Accompanying module header (in .c files only)
    3. System headers
    4. Program headers
    5. Conditional headers
  • Includes must be sorted alphabetically, with subdirectory paths sorting after parent-level files (unistd.h before sys/time.h)
  • Braces: omit around simple single statements (return, break, continue, trivial assignments); never put control flow body on same line as condition; if any block in an if/else chain needs braces, all blocks get braces
  • Exports: mark functions static unless they are public API with a header declaration; avoid function-like macros
  • Strings: use String_eq(), String_cat() etc. from XUtils.h instead of raw strcmp/strcat
  • Memory: use xMalloc(), xCalloc(), xRealloc() (never raw malloc); use xReallocArray() for arrays; never allocate 0 bytes
  • Blank lines: use single blank lines to separate groups of related statements within functions

Architecture

htop is a cross-platform interactive process viewer in C99. It uses an object-oriented C pattern with virtual method tables.

Class hierarchy

Object (base with vtable: Display, Compare, Delete) → Row → Process (per-process data) Object → Panel (UI widget with event handling, scrolling) Object → Meter (system metric with text/bar/graph modes)

Platform abstraction

Each platform directory (linux/, darwin/, freebsd/, netbsd/, openbsd/, dragonflybsd/, solaris/, pcp/, unsupported/) provides:

  • Platform.c/.h — platform init/done, load average, clock, etc.
  • <Platform>Machine.c/.h — system state (CPU counts, memory, uptime)
  • <Platform>ProcessTable.c/.h — process enumeration from OS
  • <Platform>Process.c/.h — platform-specific process fields

The pcp/ platform uses PMAPI to fetch metrics and supports dynamic column/meter/screen definitions via config files in pcp/columns/, pcp/meters/, pcp/screens/.

Main loop

htop.c or pcp-htop.c → CommandLine_run() → ScreenManager_run() which loops:

  1. Timer-based recalculation (fetch process data, update meters)
  2. Redraw if dirty
  3. Read keyboard input via Panel_getCh()
  4. Dispatch to action handler → returns Htop_Reaction flags (REFRESH, RECALCULATE, QUIT, etc.)

Key subsystems

  • Action.c — keyboard action handlers, each returns Htop_Reaction
  • Settings.c — config persistence (~/.config/htop/htoprc)
  • Header.c — meter layout in the top area
  • FunctionBar.c — F1-F10 key labels at bottom
  • CRT.c — ncurses abstraction (colors, attributes, input)
  • Vector.c / Hashtable.c — generic containers
  • XUtils.c — memory wrappers, string utilities (requires config.h in any .c that uses it)
  • RichString.c — attributed/colored string buffers
  • generic/ — routines that may be shared across multiple platforms

AI Contributions Policy

Disclose AI use via Assisted-by: or Co-authored-by: commit trailers. Contributor is fully responsible for quality and license compliance. See docs/ai-contributions-policy.md.

Sign off commits with a Signed-off-by: trailer (git commit -s) to certify the Developer Certificate of Origin. Sign-off is distinct from AI disclosure: Assisted-by: records tool use; Signed-off-by: records human responsibility. An agent must not sign off on a contributor's behalf without confirmation.