Write, build, and run Assembly code with a single click!

✨ Key Features

• Smart Auto-Detect: Instantly analyzes your .asm code to determine the optimal build configuration (32-bit/64-bit, Irvine/Native, main/_start).
• True Cross-Platform: Runs seamlessly on Linux (Native & Wine) and Windows (Native MSYS2) directly from your editor.
• macOS Assembly on Linux (New!): Compile and run macOS Mach-O 32-bit and 64-bit Assembly code directly on your Linux machine using osxcross and Darling.
• Irvine32 Support: First-class integration for the Irvine32.inc library, featuring a persistent path saver for a hassle-free setup.
• Integrated Terminal: Automatically spawns a dedicated clean terminal and clears previous execution outputs.
• Multi-Toolchain Magic: Seamlessly orchestrates NASM, GCC, LD, UASM, and Apple Darwin linkers in the background.

🛠️ Requirements & Dependencies

Before using the extension, you need to install the required tools based on your operating system.

🍎 macOS Dependencies

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):

xcode-select --install

🪟 Windows (Using MSYS2)

If you don't have it installed, download and install MSYS2 first. Then, open your MSYS2 terminal and run the pacman command to install the required assemblers and linkers:

pacman -S mingw-w64-i686-gcc mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-gdb mingw-w64-x86_64-nasm make p7zip mingw-w64-x86_64-uasm

🐧 Linux Dependencies

Choose your Linux distribution below to install the required dependencies (nasm, mingw-w64, wine, uasm, binutils, ghex, etc.).

sudo apt update && sudo apt install -y nasm gcc-mingw-w64 wine binutils ghex unzip curl

sudo dnf install -y nasm mingw64-gcc wine binutils ghex unzip curl

sudo xbps-install -S nasm cross-x86_64-w64-mingw32-gcc wine binutils ghex unzip curl

sudo emerge --ask dev-lang/nasm dev-util/mingw64-toolchain app-emulation/wine-vanilla sys-devel/binutils dev-util/ghex app-arch/unzip net-misc/curl

sudo eopkg install nasm mingw-w64 wine binutils ghex unzip curl

sudo zypper install -y nasm mingw64-gcc wine binutils ghex unzip curl

sudo apk add --no-cache nasm mingw-w64-gcc wine binutils ghex unzip curl sed

pkg install nasm mingw-w64-gcc wine binutils ghex unzip curl

⚠️ UASM Manual Installation:

If your distribution does not have uasm in its official repositories, download and install it manually:

Copy

curl -fsSL https://www.terraspace.co.uk/uasm257_linux64.zip -o uasm_linux.zip
unzip -q uasm_linux.zip -d uasm_temp
sudo mv uasm_temp/uasm /usr/local/bin/
sudo chmod +x /usr/local/bin/uasm
rm -rf uasm_linux.zip uasm_temp

SHA256: d9fecb2226f66c7e48d81402fc13a67eda23507be9067a2983ee14ec7d68a94f

sudo pacman -S --needed nasm mingw-w64-gcc wine binutils ghex unzip curl
yay -S --needed uasm

🦾 ARM Execution on x86-64

Native-like ARM Support on ArchLinux

The extension supports running ARM architecture code seamlessly on your x86-64 machine. Make sure to install the required toolchains:

Copy

sudo pacman -S aarch64-linux-gnu-binutils
sudo pacman -S arm-none-eabi-binutils arm-none-eabi-gcc

🪐 RISC-V Execution & Cross-Compilation

Run RISC-V 32/64/128-bit on Arch Linux

To enable full RISC-V support (including the experimental 128-bit mode) on your Arch-based system, install the GNU toolchain and QEMU emulators:

Copy

sudo pacman -S riscv64-linux-gnu-binutils qemu-user-static
sudo pacman -S riscv64-linux-gnu-gcc riscv64-linux-gnu-glibc
sudo pacman -S qemu-user

🍎 The Mach-O Bridge

macOS Cross-Compilation & Execution on Arch Linux

⚠️ Note: Currently, running macOS code is officially tested and supported ONLY on Arch Linux.

This guide documents the complete workflow to transform an Arch Linux system into a full-blown development environment capable of Assembling, Linking, and Running macOS binaries (Mach-O format) natively on Linux.

---

🚀 Phase 1: Initial AUR Setup & Darling Environment

We begin by attempting to install the core components from the Arch User Repository (AUR).

Copy

# Using 'yay' to fetch the runner and the cross-linker
yay -S darling-bin osxcross-git

🔹 What Happened?

1. Darling Success: darling-bin (the Darwin/macOS emulation layer) installed successfully as a pre-compiled package.
2. osxcross Failure: The osxcross-git package failed due to a 404 Not Found error.
   • Reason: The AUR package relies on a dead link for the MacOSX10.11.sdk. Apple frequently removes older SDKs from its servers.

🔹 Activating the Darling Kernel (Optional/User-space)

To ensure the environment is ready for execution, you might need to enable the kernel module or initialize the userspace server:

Copy

# Note: Modern Darling uses a userspace server (darlingserver), 
# but legacy installs might require the kernel module:
yay -S darling-mach-dkms-git
sudo modprobe darling-mach

---

🛠️ Phase 2: Manual Construction of osxcross

To bypass the dead SDK links, we manually build osxcross using a modern SDK (11.3).

1. Install Essential Dependencies

Copy

sudo pacman -S --needed clang cmake libxml2 zlib openssl pbzip2 mpdecimal

2. Clone the Official Repository

Copy

git clone https://github.com/tpoechtrager/osxcross.git
cd osxcross

3. Fetching the SDK "The Manual Way"

We download the MacOSX11.3.sdk from a verified mirror and place it in the tarballs/ directory:

Copy

wget -nc https://github.com/joseluisq/macosx-sdks/releases/download/11.3/MacOSX11.3.sdk.tar.xz -P tarballs/

4. Initiate the Build Process

Run the build script in unattended mode (this takes several minutes depending on CPU power):

Copy

UNATTENDED=1 ./build.sh

---

⚙️ Phase 3: System Integration & Global Configuration

Once built, we must make the macOS tools available system-wide and ensure the linker can find its shared libraries.

1. Copying to Global Binaries

Copy

sudo cp -r target/bin/* /usr/local/bin/
sudo cp -r target/lib/* /usr/local/lib/
sudo mkdir -p /usr/local/SDK/
sudo cp -r target/SDK/* /usr/local/SDK/ 2>/dev/null || true

2. Resolving Shared Library Issues (libtapi, libxar)

If the linker fails to find shared objects, we must register /usr/local/lib in the system's dynamic linker cache:

Copy

# Create a new configuration file for local libraries
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/usr-local.conf

# Update the linker cache
sudo ldconfig

---

✅ Environment Verification

To confirm that your Linux system can now generate macOS binaries, verify the linker version:

Copy

x86_64-apple-darwin20.4-ld -v

> Result: If the version info (e.g., PROJECT:ld64-711) appears without errors, your Arch-macOS Gateway is officially open! 🌍🔥

---

Summary of Build Commands (for extension.ts)

Step	Command
Assemble	nasm -f macho64 code.asm -o code.o
Link	x86_64-apple-darwin20.4-ld code.o -o code -macosx_version_min 10.11 -lSystem -syslibroot /usr/local/SDK/MacOSX11.3.sdk
Run	darling ./code

📜 Built-in Snippets

Type the prefix in a .asm file and hit Tab for instant boilerplate code!

🐧 GNU/Linux (x86 & x86_64)

🪟 Windows API / Standalone Templates

📚 Irvine32 Library (Optional but recommended)

If your project uses the Irvine32 library, download it, extract it to a known folder, and the extension will handle the linking automatically.

⚙️ How to Use

1. Install the extension from the VS Code Marketplace.
2. Open any .asm file in VS Code.
3. Run Code: Simply click the ▶ Play button in the top right corner of the editor and select Run x86 Assembly (ahmed_x86). Alternatively, you can open the Command Palette (Ctrl+Shift+P) and type Ahmed x86 ASM: Run Code.
4. The extension will Auto-Detect the best environment. Press Enter, and watch your code compile and run in the terminal!
5. Irvine32 Setup: The extension will prompt you to select the folder containing Irvine32.lib only the very first time you need it.
6. Reset Path: To change the Irvine library path later, press Ctrl+Shift+P and search for Ahmed x86 ASM: Reset Irvine Library Path.