codegreen 0.2.2__tar.gz → 0.3.0__tar.gz

{codegreen-0.2.2 → codegreen-0.3.0}/CMakeLists.txt

@@ -120,37 +120,33 @@ endif()
 # Instrumentation is now Python-based, no C++ build needed
 # add_subdirectory(codegreen/instrumentation)
 
-# Main executable
-add_executable(codegreen 
-    codegreen/measurement/main.cpp
-)
-
-# Ensure instrumentation files are synced before building main executable
-add_dependencies(codegreen sync_instrumentation)
-
-# Link all libraries
-target_link_libraries(codegreen PRIVATE
-    codegreen-core
-    codegreen-nemb
-    ${JSONCPP_LIBRARIES}
-    ${CURL_LIBRARIES}
-    Threads::Threads
-)
-
-target_include_directories(codegreen PRIVATE
-    ${CMAKE_SOURCE_DIR}/codegreen/measurement/include
-    ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/include
-    ${JSONCPP_INCLUDE_DIRS}
-    ${CURL_INCLUDE_DIRS}
-)
-
-# Compiler-specific options
-if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
-    target_compile_options(codegreen PRIVATE 
-        -Wall -Wextra -Wno-unused-parameter
-        $<$<CONFIG:Debug>:-g -O0>
-        $<$<CONFIG:Release>:-O3 -DNDEBUG>
+# Main executable (requires jsoncpp/curl/sqlite -- Linux only)
+# On macOS, only codegreen-nemb is built; the Python CLI handles everything.
+if(NOT APPLE)
+    add_executable(codegreen
+        codegreen/measurement/main.cpp
+    )
+    add_dependencies(codegreen sync_instrumentation)
+    target_link_libraries(codegreen PRIVATE
+        codegreen-core
+        codegreen-nemb
+        ${JSONCPP_LIBRARIES}
+        ${CURL_LIBRARIES}
+        Threads::Threads
     )
+    target_include_directories(codegreen PRIVATE
+        ${CMAKE_SOURCE_DIR}/codegreen/measurement/include
+        ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/include
+        ${JSONCPP_INCLUDE_DIRS}
+        ${CURL_INCLUDE_DIRS}
+    )
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+        target_compile_options(codegreen PRIVATE
+            -Wall -Wextra -Wno-unused-parameter
+            $<$<CONFIG:Debug>:-g -O0>
+            $<$<CONFIG:Release>:-O3 -DNDEBUG>
+        )
+    endif()
 endif()
 
 # Copy runtime modules to build directory with dependency tracking
@@ -242,30 +238,44 @@ if(EXISTS "${CMAKE_SOURCE_DIR}/config/codegreen.json")
     )
 endif()
 
-# Installation
-install(TARGETS codegreen
-    RUNTIME DESTINATION bin
-    COMPONENT runtime
-)
+# Installation (binary only on Linux where codegreen-core is built)
+if(NOT APPLE)
+    install(TARGETS codegreen
+        RUNTIME DESTINATION bin
+        COMPONENT runtime
+    )
+endif()
 
-# Create development bin directory and copy binary for CLI integration
-add_custom_target(dev-install ALL
-    DEPENDS codegreen
-    COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/bin
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/codegreen ${CMAKE_SOURCE_DIR}/bin/
-    COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/lib
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/lib/libcodegreen-nemb${CMAKE_SHARED_LIBRARY_SUFFIX} ${CMAKE_SOURCE_DIR}/lib/
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/lib/libcodegreen-core.a ${CMAKE_SOURCE_DIR}/lib/
-    COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/bin/python/instrumentation
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/bridge_analyze.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/bridge_instrument.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_engine.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/ast_processor.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
-    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_configs.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
-    COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_runtimes ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/language_runtimes
-    COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/configs ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/configs
-    COMMENT "Copying binary and instrumentation files to development bin directory for CLI integration"
-)
+# Dev-install: copy NEMB library + instrumentation files for local development
+if(APPLE)
+    add_custom_target(dev-install ALL
+        DEPENDS codegreen-nemb
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/lib
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/lib/libcodegreen-nemb.dylib ${CMAKE_SOURCE_DIR}/lib/
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/bin/python/instrumentation
+        COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_runtimes ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/language_runtimes
+        COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/configs ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/configs
+        COMMENT "Dev-install: NEMB dylib + instrumentation (macOS)"
+    )
+else()
+    add_custom_target(dev-install ALL
+        DEPENDS codegreen
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/bin
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/codegreen ${CMAKE_SOURCE_DIR}/bin/
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/lib
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/lib/libcodegreen-nemb.so ${CMAKE_SOURCE_DIR}/lib/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/lib/libcodegreen-core.a ${CMAKE_SOURCE_DIR}/lib/
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_SOURCE_DIR}/bin/python/instrumentation
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/bridge_analyze.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/bridge_instrument.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_engine.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/ast_processor.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_configs.py ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/
+        COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_runtimes ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/language_runtimes
+        COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/configs ${CMAKE_SOURCE_DIR}/bin/python/instrumentation/configs
+        COMMENT "Dev-install: binary + NEMB + instrumentation (Linux)"
+    )
+endif()
 
 # Install runtime modules
 install(FILES ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_runtimes/python/codegreen_runtime.py

{codegreen-0.2.2/codegreen.egg-info → codegreen-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegreen
-Version: 0.2.2
+Version: 0.3.0
 Summary: Energy-aware software development tool for measuring and optimizing code energy consumption
 Author-email: Saurabhsingh Rajput <saurabh@dal.ca>
 Maintainer-email: Saurabhsingh Rajput <saurabh@dal.ca>
@@ -399,6 +399,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: C++
 Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Environment :: Console
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -447,7 +448,7 @@ CodeGreen is a comprehensive tool for fine-grained energy profiling and optimiza
 pip install codegreen
 ```
 
-Requires Linux with RAPL support. The wheel includes the pre-built C++ measurement backend.
+Pre-built wheels available for Linux x86_64 and macOS ARM64 (Apple Silicon). Includes the native NEMB energy measurement backend.
 
 ### From source (recommended for development)
 
@@ -456,18 +457,28 @@ git clone https://github.com/SMART-Dal/codegreen.git
 cd codegreen
 ./install.sh
 
-# For RAPL sensor access (one-time, requires sudo):
+# Linux: RAPL sensor access (one-time, requires sudo):
 sudo ./install.sh   # or: sudo codegreen init-sensors
-# Then log out and back in for group permissions
+
+# macOS: energy measurement requires sudo (IOReport access):
+sudo codegreen run -- python script.py
 ```
 
+### Platform support
+
+| Platform | pip install | Energy measurement | Backend |
+|----------|------------|-------------------|---------|
+| Linux x86_64 (Intel/AMD) | Pre-built wheel | Full | RAPL via NEMB |
+| macOS ARM64 (Apple Silicon) | Pre-built wheel | Full | IOReport + kpc via NEMB |
+| macOS Intel | From source | Full | IOReport via NEMB |
+| Other | From source | Time-only | Fallback |
+
 ### Requirements
 
-- Linux (kernel 5.0+, Ubuntu 20.04+, Debian 11+, Fedora 35+, MacOS)
 - Python 3.9+
-- CMake 3.16+, g++ 9+ (for source builds only)
-- Intel or AMD CPU with RAPL support
-- `perf` (for `codegreen run` and benchmark validation)
+- Linux: kernel 5.0+, Intel/AMD CPU with RAPL support
+- macOS: Apple Silicon (M1-M5) or Intel, sudo for energy measurement
+- Source builds: CMake 3.16+, C++17 compiler
 
 ## Usage
 
@@ -510,7 +521,7 @@ JSON (default for `--json`), CSV, Markdown table, and text summary. The JSON out
 
 ## Language support
 
-Adding a new language requires only a JSON config file in `src/instrumentation/configs/` plus the tree-sitter grammar. No Python code changes needed.
+Adding a new language requires only a JSON config file in `codegreen/instrumentation/configs/` plus the tree-sitter grammar. No Python code changes needed.
 
 Currently supported: Python, C, C++, JavaScript, Java.
 
@@ -529,7 +540,7 @@ bash scripts/generate_comparison_artifacts.sh docs/benchmarks/
 
 ## Energy Flow Graph (EFG)
 
-CodeGreen includes an Energy Flow Graph module (`src/analysis/cfg/`) that builds energy-annotated control flow graphs from source code:
+CodeGreen includes an Energy Flow Graph module (`codegreen/analysis/cfg/`) that builds energy-annotated control flow graphs from source code:
 
 ```python
 from codegreen.analysis.cfg.builder import build_per_method_cfgs
@@ -544,7 +555,7 @@ Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-
 
 ## Architecture
 
-- **C++ NEMB backend**: RAPL energy reading with sub-microsecond timestamping, configurable polling interval
+- **C++ NEMB backend**: platform-aware energy measurement (RAPL on Linux, IOReport on macOS), sub-microsecond timestamping, background polling with lock-free ring buffers
 - **Python instrumentation**: tree-sitter AST analysis, config-driven checkpoint insertion
 - **Energy Flow Graph**: CFG + energy annotation for path-dependent analysis
 - **Benchmark harness**: multi-suite support (benchmarksgame, PerfOpt), statistical analysis with t-distribution CI, IQR outlier detection, profiler comparison

{codegreen-0.2.2 → codegreen-0.3.0}/README.md

@@ -17,7 +17,7 @@ CodeGreen is a comprehensive tool for fine-grained energy profiling and optimiza
 pip install codegreen
 ```
 
-Requires Linux with RAPL support. The wheel includes the pre-built C++ measurement backend.
+Pre-built wheels available for Linux x86_64 and macOS ARM64 (Apple Silicon). Includes the native NEMB energy measurement backend.
 
 ### From source (recommended for development)
 
@@ -26,18 +26,28 @@ git clone https://github.com/SMART-Dal/codegreen.git
 cd codegreen
 ./install.sh
 
-# For RAPL sensor access (one-time, requires sudo):
+# Linux: RAPL sensor access (one-time, requires sudo):
 sudo ./install.sh   # or: sudo codegreen init-sensors
-# Then log out and back in for group permissions
+
+# macOS: energy measurement requires sudo (IOReport access):
+sudo codegreen run -- python script.py
 ```
 
+### Platform support
+
+| Platform | pip install | Energy measurement | Backend |
+|----------|------------|-------------------|---------|
+| Linux x86_64 (Intel/AMD) | Pre-built wheel | Full | RAPL via NEMB |
+| macOS ARM64 (Apple Silicon) | Pre-built wheel | Full | IOReport + kpc via NEMB |
+| macOS Intel | From source | Full | IOReport via NEMB |
+| Other | From source | Time-only | Fallback |
+
 ### Requirements
 
-- Linux (kernel 5.0+, Ubuntu 20.04+, Debian 11+, Fedora 35+, MacOS)
 - Python 3.9+
-- CMake 3.16+, g++ 9+ (for source builds only)
-- Intel or AMD CPU with RAPL support
-- `perf` (for `codegreen run` and benchmark validation)
+- Linux: kernel 5.0+, Intel/AMD CPU with RAPL support
+- macOS: Apple Silicon (M1-M5) or Intel, sudo for energy measurement
+- Source builds: CMake 3.16+, C++17 compiler
 
 ## Usage
 
@@ -80,7 +90,7 @@ JSON (default for `--json`), CSV, Markdown table, and text summary. The JSON out
 
 ## Language support
 
-Adding a new language requires only a JSON config file in `src/instrumentation/configs/` plus the tree-sitter grammar. No Python code changes needed.
+Adding a new language requires only a JSON config file in `codegreen/instrumentation/configs/` plus the tree-sitter grammar. No Python code changes needed.
 
 Currently supported: Python, C, C++, JavaScript, Java.
 
@@ -99,7 +109,7 @@ bash scripts/generate_comparison_artifacts.sh docs/benchmarks/
 
 ## Energy Flow Graph (EFG)
 
-CodeGreen includes an Energy Flow Graph module (`src/analysis/cfg/`) that builds energy-annotated control flow graphs from source code:
+CodeGreen includes an Energy Flow Graph module (`codegreen/analysis/cfg/`) that builds energy-annotated control flow graphs from source code:
 
 ```python
 from codegreen.analysis.cfg.builder import build_per_method_cfgs
@@ -114,7 +124,7 @@ Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-
 
 ## Architecture
 
-- **C++ NEMB backend**: RAPL energy reading with sub-microsecond timestamping, configurable polling interval
+- **C++ NEMB backend**: platform-aware energy measurement (RAPL on Linux, IOReport on macOS), sub-microsecond timestamping, background polling with lock-free ring buffers
 - **Python instrumentation**: tree-sitter AST analysis, config-driven checkpoint insertion
 - **Energy Flow Graph**: CFG + energy annotation for path-dependent analysis
 - **Benchmark harness**: multi-suite support (benchmarksgame, PerfOpt), statistical analysis with t-distribution CI, IQR outlier detection, profiler comparison

{codegreen-0.2.2 → codegreen-0.3.0}/codegreen/__init__.py

@@ -5,7 +5,7 @@ A comprehensive energy measurement and code optimization tool for developers
 and researchers who need precise, fine-grained energy consumption analysis.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 __author__ = "Saurabhsingh Rajput"
 __email__ = "saurabh@dal.ca"
 __description__ = "Energy-aware software development tool"

{codegreen-0.2.2 → codegreen-0.3.0}/codegreen/cli/cli.py

@@ -35,6 +35,7 @@ except ImportError:
 import typer
 from rich.console import Console
 from rich.panel import Panel
+from codegreen import __version__ as _VERSION
 from rich.text import Text
 from rich.table import Table
 from rich.progress import Progress, SpinnerColumn, TextColumn
@@ -531,7 +532,7 @@ def generate_optimized_config(
         "timestamp": datetime.now().isoformat(),
         "environment_type": environment_info["type"],
         "detected_sensors": list(sensor_info.keys()),
-        "version": "0.1.0"
+        "version": _VERSION
     }
     
     # Environment-specific optimizations
@@ -699,7 +700,7 @@ def main(
     - [dim]codegreen config --show[/dim] - View/edit configuration
     """
     if version:
-        console.print("[bold green]CodeGreen version 0.1.0[/bold green]")
+        console.print(f"[bold green]CodeGreen version {_VERSION}[/bold green]")
         raise typer.Exit()
     
     # If no command is provided and version is not requested, show help
@@ -1700,7 +1701,7 @@ def show_info(
     # Package information
     try:
         import codegreen
-        table.add_row("Version", "[ok]", f"CodeGreen {codegreen.__version__}")
+        table.add_row("Version", "[ok]", f"CodeGreen {_VERSION}")
     except:
         table.add_row("Version", "-", "Unknown")
     
@@ -2272,49 +2273,40 @@ def run_command(
     - codegreen run --repeat 20 ./my_binary arg1 arg2
     - codegreen run --budget 10.0 python train.py
     """
-    import subprocess, time, re, tempfile, math
+    import subprocess, time, math
     from benchmark.results import StatisticalAnalysis
 
+    backend = _get_energy_backend()
+    if not json_output:
+        console.print(f"[dim]Energy backend: {backend.name}[/dim]")
+
     for i in range(warmup):
         if not json_output:
             console.print(f"[dim]Warmup {i+1}/{warmup}[/dim]")
         subprocess.run(command, capture_output=True, timeout=300)
 
-    events = "power/energy-pkg/"
-    try:
-        r = subprocess.run(["perf", "list", "power"], capture_output=True, text=True, timeout=5)
-        if "energy-ram" in r.stdout:
-            events += ",power/energy-ram/"
-    except Exception:
-        pass
-
     energies, times = [], []
     for i in range(repeat):
         if not json_output:
             console.print(f"[dim]Run {i+1}/{repeat}[/dim]")
-        with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:
-            perf_file = f.name
-        try:
-            full = ["perf", "stat", "-e", events, "-o", perf_file, "--"] + command
-            start = time.perf_counter()
-            subprocess.run(full, capture_output=True, text=True, timeout=300)
-            elapsed = time.perf_counter() - start
-            times.append(elapsed)
-            content = open(perf_file).read()
-            total = 0.0
-            for m in re.finditer(r'([\d.,]+)\s+Joules', content):
-                total += float(m.group(1).replace(',', ''))
-            if total > 0:
-                energies.append(total)
-        finally:
-            import os
-            os.unlink(perf_file)
+        energy_j, elapsed = backend.measure(command)
+        times.append(elapsed)
+        if energy_j is not None and energy_j > 0:
+            energies.append(energy_j)
 
     if not energies:
+        msg = f"No energy data from {backend.name}"
+        if isinstance(backend, _TimeOnlyBackend):
+            msg += " (need perf on Linux or sudo powermetrics on macOS)"
         if json_output:
-            print(json.dumps({"success": False, "error": "No energy data (RAPL unavailable?)"}))
+            t_mean = sum(times) / len(times) if times else 0
+            print(json.dumps({"success": False, "error": msg,
+                              "time_seconds": {"mean": t_mean}}))
         else:
-            console.print("[red]No energy data collected. Is RAPL accessible?[/red]")
+            console.print(f"[red]{msg}[/red]")
+            if times:
+                t_stats = StatisticalAnalysis.summarize(times)
+                console.print(f"[bold]Time:[/bold] {t_stats.mean:.4f} s +/- {t_stats.std:.4f} s")
         raise typer.Exit(1)
 
     e_stats = StatisticalAnalysis.summarize(energies)
@@ -2342,6 +2334,197 @@ def run_command(
                 console.print(f"[green]Within budget: {e_stats.mean:.4f}J <= {budget}J[/green]")
 
 
+class _EnergyBackend:
+    """Base class for CLI energy measurement backends.
+    Open/closed: add new hardware support by subclassing and appending to _ENERGY_BACKENDS.
+    No file I/O during measurement -- all data via in-memory APIs or pipes."""
+    name: str = "unknown"
+    priority: int = 0  # higher = preferred
+    def is_available(self) -> bool: return False
+    def measure(self, command: list, timeout: int = 300) -> tuple:
+        """Returns (energy_joules or None, elapsed_seconds)."""
+        raise NotImplementedError
+    def wrap_command(self, cmd_str: str, energy_file: str, checkpoint_file: str) -> str:
+        """Wrap a shell command for energy + checkpoint capture (project mode)."""
+        return f"bash -c '{cmd_str} 2>{checkpoint_file}'"
+    def parse_energy(self, energy_file: str) -> float:
+        """Parse energy from output file (project mode only). Returns joules or 0."""
+        return 0.0
+
+
+class _NEMBBackend(_EnergyBackend):
+    """In-process NEMB measurement via ctypes. Zero file I/O during measurement.
+    Uses the same background polling + ring buffer architecture as fine-grained mode."""
+    name = "NEMB (native energy measurement)"
+    priority = 100
+    _lib = None
+
+    def _load(self):
+        if self._lib is not None:
+            return self._lib
+        import ctypes
+        pkg_root = Path(__file__).resolve().parent.parent
+        for name in ["libcodegreen-nemb.dylib", "libcodegreen-nemb.so"]:
+            for d in [pkg_root / "lib", pkg_root.parent / "lib", pkg_root.parent / "build" / "lib"]:
+                p = d / name
+                if p.exists():
+                    try:
+                        self._lib = ctypes.CDLL(str(p))
+                        return self._lib
+                    except OSError:
+                        pass
+        self._lib = False
+        return False
+
+    def is_available(self) -> bool:
+        lib = self._load()
+        if not lib:
+            return False
+        import ctypes
+        try:
+            lib.nemb_initialize.restype = ctypes.c_int
+            return lib.nemb_initialize() == 1
+        except Exception:
+            return False
+
+    def measure(self, command: list, timeout: int = 300) -> tuple:
+        import ctypes, subprocess, time
+        lib = self._load()
+        lib.nemb_start_session.restype = ctypes.c_uint64
+        lib.nemb_start_session.argtypes = [ctypes.c_char_p]
+        lib.nemb_stop_session.restype = ctypes.c_int
+        lib.nemb_stop_session.argtypes = [ctypes.c_uint64, ctypes.POINTER(ctypes.c_double), ctypes.POINTER(ctypes.c_double)]
+
+        sid = lib.nemb_start_session(b"run")
+        start = time.perf_counter()
+        subprocess.run(command, capture_output=True, timeout=timeout)
+        elapsed = time.perf_counter() - start
+        energy = ctypes.c_double(0)
+        power = ctypes.c_double(0)
+        ok = lib.nemb_stop_session(sid, ctypes.byref(energy), ctypes.byref(power))
+        return (energy.value if ok and energy.value > 0 else None, elapsed)
+
+    def wrap_command(self, cmd_str: str, energy_file: str, checkpoint_file: str) -> str:
+        # NEMB wraps via the codegreen binary which handles measurement internally
+        binary = get_binary_path()
+        if binary:
+            return f"{binary} measure-workload --output {energy_file} -- bash -c '{cmd_str} 2>{checkpoint_file}'"
+        return f"bash -c '{cmd_str} 2>{checkpoint_file}'"
+
+    def parse_energy(self, energy_file: str) -> float:
+        try:
+            d = json.loads(open(energy_file).read())
+            return d.get("summary", {}).get("total_energy_j", 0.0)
+        except Exception:
+            return 0.0
+
+
+class _PerfBackend(_EnergyBackend):
+    name = "perf (Linux RAPL)"
+    priority = 50
+    def is_available(self) -> bool:
+        import shutil
+        return sys.platform == "linux" and shutil.which("perf") is not None
+    def _events(self) -> str:
+        import subprocess
+        events = "power/energy-pkg/"
+        try:
+            r = subprocess.run(["perf", "list", "power"], capture_output=True, text=True, timeout=5)
+            if "energy-ram" in r.stdout:
+                events += ",power/energy-ram/"
+        except Exception:
+            pass
+        return events
+    def measure(self, command: list, timeout: int = 300) -> tuple:
+        import subprocess, time, tempfile, os
+        with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:
+            pf = f.name
+        try:
+            full = ["perf", "stat", "-e", self._events(), "-o", pf, "--"] + command
+            start = time.perf_counter()
+            subprocess.run(full, capture_output=True, text=True, timeout=timeout)
+            elapsed = time.perf_counter() - start
+            energy = self.parse_energy(pf)
+            return (energy if energy > 0 else None, elapsed)
+        finally:
+            os.unlink(pf)
+    def wrap_command(self, cmd_str: str, perf_file: str, checkpoint_file: str) -> str:
+        return f"perf stat -e {self._events()} -o {perf_file} -- bash -c '{cmd_str} 2>{checkpoint_file}'"
+    def parse_energy(self, perf_file: str) -> float:
+        import re
+        try:
+            content = open(perf_file).read()
+            total = 0.0
+            for m in re.finditer(r'([\d.,]+)\s+Joules', content):
+                total += float(m.group(1).replace(',', ''))
+            return total
+        except Exception:
+            return 0.0
+
+
+class _PowermetricsBackend(_EnergyBackend):
+    name = "powermetrics (macOS IOReport)"
+    priority = 30
+    def is_available(self) -> bool:
+        import shutil
+        return sys.platform == "darwin" and shutil.which("powermetrics") is not None
+    def measure(self, command: list, timeout: int = 300) -> tuple:
+        import subprocess, time, tempfile, os, re
+        with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:
+            pm_file = f.name
+        try:
+            proc = subprocess.Popen(
+                ["sudo", "-n", "powermetrics", "--samplers", "cpu_power",
+                 "-i", "100", "-o", pm_file],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            time.sleep(0.2)
+            start = time.perf_counter()
+            subprocess.run(command, capture_output=True, timeout=timeout)
+            elapsed = time.perf_counter() - start
+            time.sleep(0.3)
+            proc.terminate()
+            try: proc.wait(timeout=5)
+            except: proc.kill()
+            mw_samples = []
+            try:
+                for line in open(pm_file):
+                    if "Combined Power" in line or "CPU Power" in line:
+                        import re as _re
+                        m = _re.search(r'(\d+)\s*mW', line)
+                        if m: mw_samples.append(int(m.group(1)))
+            except Exception:
+                pass
+            if mw_samples:
+                return ((sum(mw_samples) / len(mw_samples) / 1000.0) * elapsed, elapsed)
+            return (None, elapsed)
+        finally:
+            os.unlink(pm_file)
+    def wrap_command(self, cmd_str: str, perf_file: str, checkpoint_file: str) -> str:
+        return f"bash -c '{cmd_str} 2>{checkpoint_file}'"
+
+
+class _TimeOnlyBackend(_EnergyBackend):
+    name = "time-only (no energy)"
+    def is_available(self) -> bool: return True
+    def measure(self, command: list, timeout: int = 300) -> tuple:
+        import subprocess, time
+        start = time.perf_counter()
+        subprocess.run(command, capture_output=True, timeout=timeout)
+        return (None, time.perf_counter() - start)
+
+
+_ENERGY_BACKENDS = [_NEMBBackend(), _PerfBackend(), _PowermetricsBackend(), _TimeOnlyBackend()]
+
+def _get_energy_backend() -> _EnergyBackend:
+    """Auto-detect best available energy backend, sorted by priority.
+    NEMB (100) > perf (50) > powermetrics (30) > time_only (0).
+    Extensible: add new backends to _ENERGY_BACKENDS."""
+    for b in sorted(_ENERGY_BACKENDS, key=lambda x: x.priority, reverse=True):
+        if b.is_available():
+            return b
+    return _TimeOnlyBackend()
+
+
 def _load_language_config(language: str) -> dict:
     """Load language config JSON. Single source of truth for language-specific settings."""
     config_dir = Path(__file__).resolve().parent.parent / "instrumentation" / "configs"
@@ -2704,28 +2887,22 @@ def project_energy(
             if cores:
                 full_cmd = f"taskset -c {cores} {full_cmd}"
 
-            # Run with perf stat for total energy + capture stderr for checkpoints
-            perf_file = tempfile.NamedTemporaryFile(suffix='.txt', delete=False).name
+            energy_backend = _get_energy_backend()
+            energy_file = tempfile.NamedTemporaryFile(suffix='.txt', delete=False).name
             checkpoint_file = tempfile.NamedTemporaryFile(suffix='.txt', delete=False).name
 
-            # Run: perf stat wrapping the command, stderr goes to checkpoint_file
-            perf_cmd = f"perf stat -e power/energy-pkg/ -o {perf_file} -- bash -c '{full_cmd} 2>{checkpoint_file}'"
+            wrapped = energy_backend.wrap_command(full_cmd, energy_file, checkpoint_file)
             start_time = time.perf_counter()
             run_result = subprocess.run(
-                perf_cmd, shell=True, cwd=str(project_dir),
+                wrapped, shell=True, cwd=str(project_dir),
                 capture_output=True, text=True, timeout=3600)
             wall_time = time.perf_counter() - start_time
 
-            # Parse perf stat for total energy
-            total_energy_j = 0.0
+            total_energy_j = energy_backend.parse_energy(energy_file)
             try:
-                perf_content = open(perf_file).read()
-                for m in re.finditer(r'([\d.,]+)\s+Joules', perf_content):
-                    total_energy_j += float(m.group(1).replace(',', ''))
-            except Exception:
+                os.unlink(energy_file)
+            except OSError:
                 pass
-            finally:
-                os.unlink(perf_file)
 
             # Parse checkpoints with per-thread call stacks for inclusive/exclusive
             func_data = {}  # name -> {inclusive_uj, exclusive_uj, time_ns, calls}