Skip to content

Conversation

avrabe
Copy link
Contributor

@avrabe avrabe commented Aug 29, 2025

Summary

Adds a nostdlib option to C++ components to enable creating minimal WebAssembly components that match their WIT specifications exactly for validation purposes.

Changes

  • New nostdlib attribute in cpp_component rule
  • Automatic standard library control - disables C++ standard library linking when nostdlib=true
  • Minimal component generation - components exclude standard library imports to match WIT specs precisely
  • Enhanced validation support - enables strict WIT compliance checking with wasm-tools component targets

Technical Details

Problem: C++ components compiled with WASI SDK automatically include WASI standard library imports (like wasi:cli/exit, wasi:cli/environment) that aren't declared in minimal WIT specifications, causing validation mismatches.

Solution: The nostdlib option allows components to exclude these automatic imports when precise WIT compliance is required for validation scenarios.

Usage Example

cpp_component(
    name = "minimal_component",
    srcs = ["component.cpp"],
    wit = "component.wit",
    nostdlib = True,  # Create minimal component matching WIT spec exactly
)

Validation Results

Confirmed all existing C++ components correctly implement their WIT specifications

  • Components properly export all required WIT functions (70+ functions in data_structures example)
  • Standard library imports don't affect WIT interface compliance
  • wasm-tools component wit validation confirms proper interface implementation

Test Plan

  • Build existing components with and without nostdlib option
  • Validate component exports match WIT specifications
  • Verify standard library linking behavior
  • Confirm backward compatibility with existing components

avrabe added 4 commits August 29, 2025 06:42
Reorganize documentation from 11 overwhelming sections to 4 clear content types
following best practices from Vue.js, Kubernetes, MDN, and Rust Book:

- GET STARTED: Quick success and clear user path guidance
- LEARN: Conceptual understanding separated by technology domain
- BUILD: Task-oriented practical guides with thematic organization
- REFERENCE: Quick lookup with thematic grouping (WIT, Language, Composition, Security rules)

Key improvements:
- Add prominent "Pick Your Learning Path" page with explicit user type guidance
- Create "WebAssembly Component Fundamentals" separating technology concepts from Bazel usage
- Break up massive rule reference into discoverable thematic groups
- Add complexity indicators (Beginner/Intermediate/Advanced) with visual badges
- Implement responsive design improvements and better navigation structure
- Fix cross-references and improve content discoverability

Reduces cognitive load while maintaining excellent technical depth and visual quality.
Addresses information architecture overload and unclear user journeys.
Update JavaScript usage example to match actual WIT definition:
- Change from generic result<T, E> format to custom calculation-result record
- Fix interface name from 'math' to 'calc' matching actual implementation
- Show correct return format: { success: bool, error: option<string>, value: option<f64> }

Verified against examples/js_component/wit/calculator.wit and src/calculator.js
…binding functions

* Add complete C++ implementation of data-structures.wit interface covering:
  - Hash tables with create, put, get, remove, contains, clear, keys, values, size, stats
  - B-trees with insert, search, delete, range queries, min/max keys, predecessors/successors
  - Graphs with node/edge operations, DFS/BFS traversals, shortest paths, components
  - Serialization support (JSON, binary, msgpack, protobuf formats)
  - Memory management with stats, defragmentation, garbage collection
  - Collection management (list, exists, delete, rename, clone)
  - Batch operations and ACID transactions
  - Query interface with SQL-like operations
  - Performance metrics and system configuration
  - Health checks and diagnostics

* Create basic but functional implementations with proper WIT binding integration
* Add working main function demonstrating hash table create/put/get operations
* Successfully validates component exports all 70+ functions via wasm-tools
* Component builds and runs successfully, returning proper exit codes
* Serves as comprehensive reference implementation for large WIT interfaces in C++
- Add nostdlib attribute to cpp_component rule for creating minimal components
- Components with nostdlib=true exclude standard library imports to match WIT specs exactly
- Useful for validation scenarios where precise WIT compliance is required
- Standard library linking is automatically disabled when nostdlib is enabled
@avrabe avrabe closed this Sep 2, 2025
@avrabe avrabe deleted the feature/cpp-component-nostdlib-validation branch September 2, 2025 04:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant