Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

[RFC]: Extend stdlib's doctesting approach to C examples

Abierto
  • ¿Algo no está bien?
#13,194 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
28/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
c, javascript, node.js
Área
build-system, testing-qa, tooling

Línea de trabajo

Comienza leyendo los objetivos de doctest existentes en tools/make/lib/doctest/c/doctest-c.mk y las issues relacionadas #G96 y #1378. Revisa los límites propuestos de extracción, instrumentación, compilación, ejecución y comparación, y resuelve después las cuestiones sobre la ruta de inclusión, el helper estático, la nomenclatura y las reglas de omisión antes de la implementación; se considera terminado cuando haya un diseño acordado para el pipeline de doctesting de C.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Accepted C RFC Tools

Description

This RFC proposes a suite of packages under @stdlib/_tools/doctest/c implementing an automated extract → instrument → compile → run → compare pipeline for testing C code examples embedded in src/*.c source files and README.md files.

Proposed Changes

Package layout
@stdlib/_tools/doctest/c/           ← orchestrator (bin/cli)
├── extract/ 
├── instrument/ 
├── compile/ 
├── run/ 
└── compare/

Make targets follow the existing doctest namespace in tools/make/lib/doctest/c/doctest-c.mk.

Sub-package API
@stdlib/_tools/doctest/c/extract
extract( filePath, mode ) → Array<block>
// filePath: string  — absolute path to a .c source file or README.md
// mode:     'src' | 'markdown'
// returns an array of self-contained block objects, one per testable example
/* block = {
        file: string,   
        blockIndex: number,                                         ← 0-based, helps segregating example blocks from same file
        includes: Array<{ text: string, line: number }>,            ← #include lines hoisted for this block
        staticHelpers: Array<{ text: string, line: number }>,       ← array of hoisted internal static functions called by this block
        fileScope: Array<{ text: string, line: number }>,           ← pre-function declarations + function definitions for this block (to be hoisted outside main()) (ex, @stdlib/ndarray/base/function-object)
        body: Array<{ text: string, line: number }>,                ← procedural lines for main() for this block
        annotations: Array<{ text: string, line: number }>          ← extracted annotation values (e.g., "~1.571", "true") from // returns comments
      }
*/

Parses @example Doxygen blocks (src mode) or ```c ``` fenced blocks (markdown mode). Each block is independent.
Note: Contiguous lines are grouped into a single text block. The line property indicates the starting line number of that contiguous block

@stdlib/_tools/doctest/c/instrument
instrument( block ) → { tmpFile, annotations }
// block:    block object from extract()
// tmpFile:  absolute path to the generated .c file written to os.tmpdir()
// annotations: Array<{ annotation, type, varName, file, line }>

Wraps the block into a compilable .c file: injects necessary stdlib and standard library headers, hoists static helpers and file-scope declarations, wraps procedural code in main(), and emits a type-aware printf per // returns annotation. Injects #line N "original/file.c" directives so all compiler errors reference the original file and line, not the generated tmp file.
For each annotation, type inference runs via a inferType helper that backward-scans the body lines accumulated up to that annotation to find the preceding variable declaration.

@stdlib/_tools/doctest/c/compile
compile( tmpFile ) → { ok, binary, stderr }
// tmpFile: path from instrument()
// binary:  path to the compiled executable (in os.tmpdir())
// stderr:  raw compiler output (already line-mapped to original file via #line)

Resolves include paths via manifest.json using @stdlib/utils/library-manifest. Handles supplemental headers referenced inside a snippet but absent from the package's core manifest dependencies.

@stdlib/_tools/doctest/c/run
run( binary, opts ) → { ok, stdout, stderr, timedOut }
// binary:  path from compile()
// opts:    { timeout: number }  — default 15000 ms

Executes the compiled binary via spawnSync with a configurable timeout.

@stdlib/_tools/doctest/c/compare
compare( stdout, annotations ) → Array<{ pass, got, expected, file, line }>
// stdout:      raw stdout string from run()
// annotations: annotation metadata array from instrument()

Normalizes tokens (inf/-inf → ±Infinity, nan → NaN, trailing f stripped) before comparison. Uses Object.is for -0 detection and delegates ~-prefixed approximate values to @stdlib/_tools/doctest/compare-values and direct comparison for ints and bools.

Block Skip Rules

In src/*.c files, a trailing comment on the function definition opts the @example blocks of that function out:

// Skips @example blocks of that function:
static double foo( double x ) { // stdlib-c-doctest disable
    ...
}

// Skip all remaining @example blocks in the file:
// stdlib-c-doctest disable-file

In README.md files, the existing <!-- run-disable --> comment before a fenced block opts it out. napi packages (paths containing /napi/) are excluded automatically by the orchestrator.

CLI

Invoked by make targets and pre-commit hooks, one file at a time:

node lib/node_modules/@stdlib/_tools/doctest/c/bin/cli.js \
    --mode=src \
    --file=lib/node_modules/@stdlib/math/base/special/sin/src/main.c \
    [--verbose] [--timeout=<ms>]
Flag Description
--mode src or markdown
--file File to process
--verbose Print compiler output and instrumentation trace
--timeout Per-binary execution timeout in ms (default: 15000)
Output Format

Compiler errors are surfaced directly from the compiler's own output, which are already mapped to the original file via #line directives. Annotation mismatches and pipeline errors (compare stage) are formatted by the orchestrator as file:line:col: error: message [rule].

Stretch Goals
  • Mutated scalar annotation: // out => 0.5
  • Flat array annotation: // x => <double>[ 1.0, 2.0, 3.0 ]
  • Complex number annotation: // returns <complex128>[re, im]
Related Issues

Related issues #G96 , #1378.

Questions

  1. Include path resolution: Should supplemental dep resolution remain in the doctest tool, or should a docs task config be added to manifest.json so library-manifest handles it fully?

  2. Static helper handling: Should internal static helpers be hoisted exactly into the tmp file, or promoted to namespaced internal symbols (e.g., stdlib_internal_*) via a restricted header?

  3. Tool structuring/naming: Any feedback on the sub-package naming or placement under @stdlib/_tools/doctest/c/?

  4. Skip rule scope for @example blocks: When // stdlib-c-doctest disable is placed on a function definition, it skips all @example blocks for that function. However, since a function can have multiple example blocks, should there be a way to skip specific blocks (e.g., using an index-based approach)?

Other

No.

Checklist
  • I have read and understood the Code of Conduct.
  • Searched for existing issues and pull requests.
  • The issue name begins with RFC:.
Lenguaje dominante
JavaScript
Estrellas
6k
Forks
1.3k
Merge medio
1 d 10 h
PR fusionados (30 d)
568

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de stdlib-js/stdlib

Todos los issues de stdlib-js/stdlib

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.