🤖✨ Assembler (C)

Developed by: AmirHossein Karimi & Moein Hosseini 🤝🔥

Welcome! This repository contains a small educational two-pass assembler implemented in C.

📚 Table of contents

• Overview
• Files
• Build & Run (CLion / CMake)
• Build & Run (Command-line / MinGW / GCC)
• Examples
• Troubleshooting
• Quick checklist

🧩 Overview

This assembler performs a two-pass assembly on a small instruction set and supports directives .SPACE and .FILL.

• Input: plain-text .asm file
• Output: text .mc machine code file (one integer per line)
• Pass 1: build symbol table
• Pass 2: generate machine code

Supported mnemonics include: ADD, SUB, SLT, OR, NAND, ADDI, ORI, SLTI, LUI, LW, SW, BEQ, JALR, J, HALT.

📁 Files

Key files and folders:

• Final/
  • assembler.h — public header (types & prototypes)
  • main.c — program entrypoint (arg parsing, defaults)
  • parser.c — parsing & assembly logic (pass1 + pass2)
  • symbol_table.c — symbol table functions
  • program.asm — sample assembly (recommended test file)
  • Makefile.txt — example Makefile for quick gcc builds
• main.c — legacy monolithic assembler (alternate)
• CMakeLists.txt — project CMake file (builds Final/ sources)
• cmake-build-debug/Assembler.exe — built executable (CLion debug)
• explanation.pdf, Final Phase 1.pdf — documentation

📥 Download from Releases (ZIP) & Run

If you don’t want to build from source, you can download a ready-to-use ZIP from the Releases page.

1) Download

1. Open the repository on GitHub.
2. Click Releases (right side panel or top section).
3. Open the latest release.
4. Under Assets, download the ZIP file (for example: Assembler-windows.zip).

2) Extract

• Right-click the ZIP file and choose Extract All...
• Open the extracted folder.

3) Run

• If the release includes Assembler.exe, open PowerShell inside that folder and run:

.\Assembler.exe program.asm output.mc

• Or double-click Assembler.exe (if your package is prepared for double-click run).

4) Input/Output notes

• program.asm = input assembly file
• output.mc = output machine code file
• You can replace filenames with your own files:

.\Assembler.exe my_input.asm my_output.mc

⚠️ If Windows shows a security warning

• Click More info → Run anyway (only if you trust the file/source).

🛠️ Build & Run (CLion / CMake)

Recommended: open the repository in CLion and run the Assembler CMake target.

1. Open the repository root in CLion.
2. Let CLion load the CMakeLists.txt (or choose "Reload CMake Project").
3. Build via Build → Build Project.

Or from PowerShell:

cd "E:\Amir\git hub repository work\Assembler"
cmake -S . -B build
cmake --build build --config Debug

Run (example):

.\cmake-build-debug\Assembler.exe Final\program.asm output.mc

Notes:

• In CLion, run the CMake target Assembler (not a single source file). Running a single .c file may compile only that file and cause linker errors (undefined references to symbols defined in other source files).
• Set the Run Configuration working directory to the project root to use default Final/program.asm when no args are passed.

💻 Build & Run (Command-line / MinGW / GCC)

Option A — CMake (recommended):

cd "E:\Amir\git hub repository work\Assembler"
cmake -S . -B build -G "MinGW Makefiles"
cmake --build build --config Release
build\Assembler.exe Final\program.asm output.mc

Option B — Direct gcc (quick test):

cd Final
gcc -o assemble main.c parser.c symbol_table.c -std=c17 -Wall
.\assemble program.asm output.mc

Option C — Example Makefile in Final/:

cd Final
make -f Makefile.txt
.\assemble Final\program.asm output.mc

• Run with defaults (no args):
  • Final/main.c will use program.asm and write output.mc in the current working directory — make sure the input file is present or pass full paths.

🆘 Troubleshooting

• Linker errors (undefined reference to init_symbol_table, open_and_read_file_Pass1, etc.):

  • Cause: compiling/running only main.c (single-file run) so the linker doesn't include parser.c and symbol_table.c.
  • Fix: build/run the full CMake target (Assembler) so CLion or your build links all sources listed in CMakeLists.txt.

• "Executable not found" after build:

  • Verify the build output directory (cmake-build-debug\ or build\). CLion typically places the exe under cmake-build-debug\.

• Assembler errors (undefined label / out-of-range immediate):

  • Inspect your .asm file for misspelled labels, incorrect directives, or immediates outside allowed ranges. Use .FILL and .SPACE correctly.

✅ Quick checklist

• Use Final/ modular sources and the CMake target Assembler.
• For quick tests compile Final/main.c, Final/parser.c, and Final/symbol_table.c together.
• If you see linker undefined references in CLion, stop running the single file: run the CMake .

---

Made with ❤️ by Amir & Moein

🔗 Check us out on GitHub:

• 👤 Amir (ahk1384)
• 👤 Moein (MoeinH-0)

---