🚀 ahmed_x86_asm

A powerful, all-in-one Visual Studio Code / VSCodium extension to instantly compile and run x86/x64, ARM64, ARM32, RISC-V, MIPS & FASM Assembly code directly from your editor. Now supporting Linux, Windows, macOS, and FreeBSD with a seamless cross-platform workflow for native and cross-platform Assembly development.

✨ Features

• 🏗️ Massive Core Refactoring & Modularization (New in v1.4.8!): The extension's internal architecture has been completely rewritten! Code is now intelligently modularized into platform-specific engines (Linux, Windows, macOS), drastically improving performance, maintainability, and paving the way for seamlessly integrating even more architectures in the future.
• 🍎 Native macOS ARM64 (Apple Silicon) Support (New in v1.4.7!): The ultimate native experience! You can now compile, link, and run macOS ARM64 Assembly natively directly on your M1/M2/M3 Mac. The extension automatically detects the darwin environment and uses Apple's standard as and ld tools for blazing-fast execution without any emulation layers.
• 🪐 Linux RISC-V 128-bit (main) Support (New in v1.4.6!): Pushing the limits even further! You can now cross-compile experimental RISC-V 128-bit (RV128) Linux Assembly using the C-style main entry point. It seamlessly links with the C Runtime using GCC and runs via QEMU directly from your terminal.
• 🪐 Linux RISC-V 128-bit Support (New in v1.4.5!): Pushing the boundaries of architecture! You can now cross-compile and run experimental RISC-V 128-bit (RV128) Linux Assembly using the standard _start entry point directly from your Linux machine.
• 🧹 Clean Snippets Logic (New in v1.4.4!): Speed up your workflow! All built-in templates have been decluttered by removing inline comments. You now get pure, production-ready code instantly upon pressing Tab, keeping your workspace professional and distraction-free.
• 🪐 Linux RISC-V 32-bit Embedded (RV32E) Support (Updated in v1.4.3!): The embedded suite is complete! You can now cross-compile and run RV32E Linux Assembly using both _start and C-style main entry points. It features specialized logic to handle the 16-register constraint and ilp32e ABI syscall conventions.
• 🪐 Linux RISC-V 32-bit (main) Support (New in v1.4.1!): The RISC-V circle is complete! You can now cross-compile and run RISC-V 32-bit (RV32I) Linux Assembly using the C-style main entry point. Utilizing a smart linking workaround, it bypasses 32/64-bit libc conflicts flawlessly on Linux!
• 🪐 Linux RISC-V 32-bit (RV32I) Support (New in v1.4.0!): Shrink it down! You can now cross-compile and run RISC-V 32-bit (RV32I) Linux Assembly using the standard _start entry point directly from your Linux machine using qemu-riscv32-static.
• 🪐 Linux RISC-V 64-bit Support (Updated in v1.3.9!): Enter the future of open hardware! You can now cross-compile and run RISC-V 64-bit Linux Assembly using both _start and the C-style main entry point directly from your Linux machine using qemu-riscv64-static.
• ⚓ FreeBSD 32-bit (main) Support (New in v1.3.7!): We went deeper! You can now cross-compile FreeBSD 32-bit Assembly using the C-style main entry point. It fully supports FreeBSD's unique stack-based syscall convention right from your Linux terminal.
• ⚓ FreeBSD 32-bit (x86) Support (New in v1.3.6!): The BSD collection expands! You can now cross-compile FreeBSD 32-bit Assembly using the standard _start entry point with Stack-based Syscalls directly from Linux.
• 🍎 macOS ARM64 (Apple Silicon) Cross-Compilation (New in v1.3.5!): The ultimate breach! You can now cross-compile macOS ARM64 Assembly using the C-style _main entry point and libSystem. Perfect for building for M1/M2/M3 chips directly from your Arch Linux machine.
• 🦾 Windows ARM32 (main) Support (New in v1.3.4!): The ARM circle is now complete! You can now cross-compile Windows ARM32 (AArch32/armv7) Assembly using the C-style main entry point, allowing seamless integration with the C Runtime on 32-bit ARM hardware.
• 🦾 Windows ARM32 Cross-Compilation (New in v1.3.3!): Breaking more physical boundaries! You can now cross-compile Windows ARM32 (AArch32/armv7) Assembly using _start. It compiles perfectly on Arch Linux, but reminds you that your x86_64 atoms still can't natively run ARM32 code!
• 🦾 Windows ARM64 (main) Support (New in v1.3.2!): The saga continues! You can now cross-compile Windows ARM64 Assembly using the C-style main entry point. Perfect for projects integrating with the C Runtime on ARM hardware.
• 🪟 Windows ARM64 Cross-Compilation (New!): The ultimate flex! You can now cross-compile Windows ARM64 Assembly directly from your Linux machine. It compiles perfectly, but outputs a fun physics reminder since you can't natively run it on x86_64!
• 🍷 Smart Wine Log Control (New in v1.3.0!): Say goodbye to annoying GPU and Mesa warnings when running Windows apps on Linux! You can now easily toggle Wine logs (ON/OFF) directly from the Tools & Settings menu for a perfectly clean terminal output.
• 🦾 Linux ARM32 (main) Support (New in v1.2.9!): Complete the set! You can now compile and run ARM32 (AArch32) Assembly using the C-style main entry point seamlessly, completing the ARM support lineup.
• 🦾 Linux ARM64 (main) Support (New in v1.2.8!): Full flexibility! You can now compile and run ARM64 Assembly using the C-style main entry point seamlessly, in addition to the standard _start.
• 🚀 Universal Assembly Mode Support (New in v1.2.7!): Total freedom! The extension now supports and detects almost every Assembly flavor, including MASM (case-insensitive), FASM, MIPS, UASM, and RISC-V. Even if you manually change the language mode in the status bar or use other ASM extensions, the "Run" and "Info" buttons will stay active and ready to work.
• 🦾 Linux ARM32 Support (New in v1.2.6!): The legacy lives on! You can now write and run ARM32 (AArch32) Assembly directly on your Linux machine. Utilizing arm-none-eabi-as for assembling and qemu-arm-static for execution, perfect for learning embedded systems and mobile architecture.
• 🦾 Linux ARM64 Support (New in v1.2.5!): Expand your horizons! You can now write, compile, and run ARM64 (AArch64) Assembly code directly on your x86_64 Linux machine. Utilizing aarch64-linux-gnu-as for assembling and qemu-aarch64-static for execution, bringing mobile and server-grade architecture development to your desktop.
• ⚓ FreeBSD Cross-Compilation (Enhanced in v1.2.4!): The BSD Gateway is open! You can now compile and run FreeBSD 64-bit Assembly code directly on Linux using both standard _start and C-style main entry points. Utilizing ld.lld (LLVM Linker) for linking and qemu-x86_64-static for execution, bringing BSD development to your Linux environment seamlessly.
• 🍎 macOS Cross-Compilation (Added in v1.2.2): Break the OS boundaries! You can now compile, link, and run macOS Mach-O 64-bit Assembly code directly from Linux. Utilizing osxcross for linking and Darling for execution, bringing Apple development to your Linux environment.
• 🧰 Unified Tools & Settings Menu (Added in v1.2.1): Declutter your workflow! We've added a dedicated "Info" icon (i) right next to the Play button. Clicking it opens a sleek, unified interactive menu giving you instant access to all extension settings, dependency checkers, and linker configurations in one convenient place!
• 🐧 Linux Linker Override (Added in v1.2.0): Full manual control to switch between ld (Standard, best for pure ASM) and gcc (Best for C-Library integration) directly from the Command Palette on Linux, maximizing flexibility!
• 🗑️ Auto-Cleanup Temporary Files (Added in v1.1.9): Keep your project folders clean! The extension can automatically delete temporary build files (.obj, .o, .err, .lst) after a successful run. Completely customizable via settings.
• 💡 Smart Hover Logs (Added in v1.1.8): Say goodbye to opening separate .err files! Simply hover your mouse over the red error squiggles in your code, and an elegant pop-up will instantly display the complete compiler error log.
• 📜 Transparent Build Logging & Error Prevention (Added in v1.1.7): See exactly what's happening under the hood! The extension logs every build command directly to the terminal for full transparency.
• 🔍 Inline Error Diagnostics (Added in v1.1.5): A built-in intelligent linter that runs the assembler in the background, highlighting the exact word with a red squiggle and a custom gutter icon. Now supporting NASM, UASM, and GAS (for ARM and RISC-V).
• 🤖 Smart Auto-Detect: Automatically analyzes your code keywords (like svc #0, ecall, riscv64, rv32i, rv32e, rv128, freebsd, macho64, irvine32, win-arm64) to instantly recommend the perfect build mode.
• 🎛️ Manual Win32/Linux Linker Override: Full manual control to switch between ld and gcc linkers to ensure maximum stability.
• 🖥️ Sequential Terminal Execution: Commands are sent sequentially to the terminal for a cleaner output and easier debugging.
• 📦 Smart Dependency Checker (Enhanced): Automatically verifies if required tools (nasm, gcc, uasm, wine, darling, lld, qemu, cross-compilers) are installed. If any tool is missing, it automatically opens the Installation Guide.
• ⚡ One-Click Execution: Integrated directly into the editor's Run button menu.
• 🧠 Dynamic Irvine Path: Persistent path saver for the Irvine32.inc library.
• 📁 Broad Compatibility: Automatically detects a wide range of assembly extensions (.asm, .s, .S, .inc, .nasm, .masm, .uasm, .fasm, .mips).

🎛️ Extension Commands

You can access these features at any time via the new Tools & Settings button (ℹ️) next to the Play button, or via the Command Palette (Ctrl + Shift + P):

• ahmed-x86 ASM: Settings & Tools: Opens the unified interactive menu to manage all extension features.
• Toggle Wine Log Visibility: Show or hide Wine terminal warnings directly from the settings menu.
• Check ASM Dependencies (ahmed_x86): Scans your system to verify tools like nasm, gcc, wine, darling, lld, aarch64-linux-gnu-as, arm-none-eabi-as, and riscv64-linux-gnu-as.
• Reset Irvine Library Path: Clears your saved Irvine directory path.
• Change Linux/Win32 Linker Method: Manually switch between ld and gcc.

📝 Snippets & Templates

Stop writing boilerplate from scratch! Type any of the following prefixes in an empty .asm or .s file and press Tab or Enter to generate a complete template:

🪐 RISC-V Templates

🦾 ARM Templates

FreeBSD Templates

🍎 macOS (Mach-O) Templates

🐧 Linux Native Templates

🪟 Windows API / Standalone Templates

🛠️ Requirements

🐧 For Linux Users:

Ensure your system has the following dependencies installed:

• nasm, uasm, binutils (ld), mingw-w64-gcc, wine.
• For macOS Cross-compilation: osxcross (linker) and darling (runner).
• For FreeBSD support: lld (linker) and qemu-user-static (runner).
• For Linux ARM64 support: aarch64-linux-gnu-binutils and qemu-aarch64-static.
• For Linux ARM32 support: arm-none-eabi-binutils and qemu-arm-static.
• For Linux RISC-V support: riscv64-linux-gnu-binutils, riscv64-linux-gnu-gcc, qemu-riscv64-static, and qemu-riscv32-static. (Note: The 64-bit RISC-V tools natively support assembling and linking for 32-bit and 128-bit experimental environments via specific flags).
• For Windows ARM (64/32) support: llvm-mingw-w64-toolchain-ucrt-bin (AUR).

🪟 For Windows Users:

Ensure your system has an MSYS2 environment set up with:

• mingw-w64 toolchains and nasm.exe in your PATH.

🍎 For macOS Users:

To natively compile and run ARM64 assembly on your Apple Silicon Mac, simply ensure you have the Xcode Command Line Tools installed (which provides clang, as, and ld):

• Open your terminal and run: xcode-select --install

🎯 How to Use

1. Open any Assembly file in VSCodium / VS Code.
2. Type a snippet prefix (e.g., linux-riscv128-main or linux-arm32-main) and press Tab.
3. Click the drop-down arrow next to the Play (Run) button.
4. Select Run Assembly (ahmed_x86).
5. Watch your code compile and run seamlessly!

🤝 Contributing & Feedback

Feel free to open an issue or a pull request on the GitHub Repository.

⭐ Notice: If you find this extension useful, please consider leaving a 5-star rating on the VS Code Marketplace!

👨‍💻 Author

Created with 💻 & ☕ by ahmed-x86

repo ahmed-x86 asm documentation ahmed-x86 asm