dartmetal 0.1.1

DartMetal — Low-level system programming for Dart. Touch the metal. Allocate memory. Talk to syscalls. No guardrails.

---

DartMetal

DartMetal — Touch the Metal from Dart.

DartMetal is a low-level system programming library for Dart. It provides manual memory management, raw syscalls, and direct CPU introspection via FFI — essentially bringing Dart into the world of systems programming.

⚠️ Warning: This library is unsafe by design. You can crash the Dart VM, corrupt memory, or perform invalid syscalls. Use at your own risk.

---

✨ Features

• 🧠 UnsafePointer<T> — C-style typed pointers with read/write and arithmetic.
• 💾 Manual memory control — malloc, free, memcpy, memset.
• ⚙️ Native syscalls — cross-platform process and I/O access.
• 🧩 Raw FFI bridge to C for native execution.
• 🧬 CPU feature detection (SSE, AVX, AES-NI, etc.) using real CPUID.
• 🔧 Cross-platform builds (Windows, Linux, macOS).

---

📦 Installation

Add to your pubspec.yaml:

dependencies:
  dartmetal: ^0.1.0

Then build the native library for your platform:

cd lib
cd native
dart run build.dart

This will produce:

Platform	Output file
Windows	dartmetal.dll
Linux	libdartmetal.so
macOS	libdartmetal.dylib

Ensure it resides in lib/native/.

---

🧩 Basic Usage

Memory Allocation

import 'package:dartmetal/dartmetal.dart';

void main() {
  final ptr = UnsafePointer<Uint32>.allocate(4);
  ptr.write(0, 0xDEADBEEF);
  print('Memory first 4 bytes: 0x${ptr.read<int>(0).toRadixString(16)}');
  ptr.free();
}

Pointer Arithmetic

final ptr = UnsafePointer<Uint32>.allocate(2);
ptr.write(0, 0xCAFEBABE);
ptr.write(1, 0xFEEDFACE);

final second = ptr.offset(1);
print('Second value: 0x${second.read<int>(0).toRadixString(16)}');

ptr.free();

---

⚙️ Syscalls

// test/syscall_test.dart
import 'dart:ffi';
import 'dart:io';
import 'package:ffi/ffi.dart';
import 'package:dartmetal/dartmetal.dart';

void main() {
  print('===== DartMetal Syscall Test =====\n');

  // ---------- PID ----------
  final pid = MetalSyscall.getpid();
  print('Current PID: $pid\n');

  // ---------- Write to stdout ----------
  print('Writing to stdout using DartMetal:');
  MetalSyscall.writeStdout('Hello from DartMetal!\n');
  MetalSyscall.writeBytes([72, 105, 32, 102, 114, 111, 109, 32, 98, 121, 116, 101, 115, 10]);
  print(''); // newline

  // ---------- Sleep ----------
  print('Sleeping for 1 second...');
  MetalSyscall.sleepMs(1000);
  print('Awake!\n');

  // ---------- Current Working Directory ----------
  final cwd = MetalSyscall.getCwd();
  print('Current working directory: $cwd');

  // ---------- Change Directory ----------
  final parentDir = Directory.current.parent.path;
  final changeResult = MetalSyscall.chdir(parentDir);
  print('Changed to parent directory: ${changeResult == 0 ? "Success" : "Fail"}');
  print('New cwd: ${MetalSyscall.getCwd()}\n');

  // ---------- Environment Variables ----------
  const envKey = 'DARTMETAL_TEST';
  MetalSyscall.setenv(envKey, 'foobar');
  final envValue = MetalSyscall.getenv(envKey);
  print('Environment variable $envKey = $envValue\n');

  // ---------- Unlink / File Deletion ----------
  final testFile = File('dartmetal_temp.txt');
  testFile.writeAsStringSync('test');
  print('Created temporary file: ${testFile.path}');
  final unlinkResult = MetalSyscall.unlink(testFile.path);
  print('Deleted temporary file: ${unlinkResult == 0 ? "Success" : "Fail"}');
}

---

🧬 CPU Feature Detection

You can inspect real CPU capabilities directly from Dart, through FFI bindings to native CPUID.

Example

// test/cpu_test.dart
import 'package:dartmetal/dartmetal.dart';

void main() {
  print('===== DartMetal CPU Test =====\n');

  // Show general CPU info
  CPU.info();

  print('\n--- Individual Properties ---');
  print('Architecture: ${CPU.architecture}');
  print('Cores       : ${CPU.coreCount}');
  print('Endianness  : ${CPU.endianness}');
  print('Vendor      : ${CPU.vendor}');

  // Check some key features
  final features = CPU.featureFlags;
  print('\n--- Selected Feature Checks ---');
  print('SSE:   ${features['SSE'] ?? false}');
  print('SSE2:  ${features['SSE2'] ?? false}');
  print('SSE3:  ${features['SSE3'] ?? false}');
  print('SSE4_1:${features['SSE4_1'] ?? false}');
  print('SSE4_2:${features['SSE4_2'] ?? false}');
  print('AVX:   ${features['AVX'] ?? false}');
  print('AES-NI:${features['AES'] ?? false}');
  print('MMX:   ${features['MMX'] ?? false}');

  print('\n✅ CPU test completed successfully!');
}

Example Output

===== DartMetal CPU Test =====

CPU Info
├─ Architecture : x86_64
├─ Cores        : 4
├─ Endianness   : LittleEndian
✅ Loaded native library: C:\Users\Eudald\Desktop\Projectes\Dart\dartmetal\lib\native\dartmetal.dll
└─ Vendor       : GenuineIntel
Features:
  └─ FPU
  └─ VME
  └─ PSE
  └─ TSC
  └─ MSR
  └─ PAE
  └─ MCE
  └─ APIC
  └─ SEP
  └─ MTRR
  └─ CMOV
  └─ PAT
  └─ CLFSH
  └─ MMX
  └─ FXSR
  └─ SSE
  └─ SSE2
  └─ HTT
  └─ SSE3
  └─ PCLMULQDQ
  └─ SSSE3
  └─ SSE4_1
  └─ SSE4_2
  └─ AES
  └─ AVX
  └─ FMA
  └─ MOVBE
  └─ POPCNT

--- Individual Properties ---
Architecture: x86_64
Cores       : 4
Endianness  : LittleEndian
Vendor      : GenuineIntel

--- Selected Feature Checks ---
SSE:   true
SSE2:  true
SSE3:  true
SSE4_1:true
SSE4_2:true
AVX:   true
AES-NI:true
MMX:   true

✅ CPU test completed successfully!

---

🧪 Running Tests

Run the included test suite:

dart run test/cpu_test.dart

or for memory/syscall tests:

dart run test/dartmetal_test.dart

Example result:

✅ Loaded native library: dartmetal.dll
✅ CPU test completed successfully!
✅ All tests passed!

---

🤝 Contributing

DartMetal is experimental and evolving. Contributions are welcome, especially for:

• New syscalls and platform bindings
• Advanced CPU topology parsing
• Threading & atomic ops
• macOS and Linux testing

---

⚖️ License

MIT License © 2025 [MuerteSeguraZ]

---