# lovefromhsd/basm architecture

> Architecture diagram of the GitHub repository lovefromhsd/basm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lovefromhsd/basm
- Repository: https://github.com/lovefromhsd/basm

## Overview

basm is a pure-Bash x86-64 assembler and linker. Its documented workflow takes an assembly input and optional output path through `src/basm.sh`, producing an executable (default `a.out`). The tree identifies assembly, ELF, and linking modules, but no source excerpts were available to verify their call relationships; the detailed internal stages are therefore shown without speculative connections.

Main entry points: [`src/basm.sh`](https://github.com/lovefromhsd/basm/blob/main/src/basm.sh) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_entrypoint["CLI entry<br/>[basm.sh]"]
  node_library["Bash library<br/>[basm.lib.sh]"]
end

subgraph group_assembly["Assembly"]
  node_preprocessor["Macro preprocessing"]
  node_mode["Assembly mode<br/>[assembly_mode.sh]"]
  node_firstpass["First pass<br/>[first_pass.sh]"]
  node_secondpass["Second pass<br/>[second_pass.sh]"]
  node_opcodes["Opcode handling<br/>[opcodes.sh]"]
  node_operands["Operand parsing<br/>[operand_parsers.sh]"]
end

subgraph group_elf["ELF and linking"]
  node_elfheader["ELF header"]
  node_object["Object generation"]
  node_collect["Link collection<br/>[linker_collect.sh]"]
  node_resolve["Symbol resolution<br/>[linker_resolve.sh]"]
  node_layout["Link layout<br/>[linker_layout.sh]"]
  node_relocate["Relocation<br/>[linker_relocate.sh]"]
  node_emit["Link emission<br/>[linker_emit.sh]"]
end

node_user(("User"))
node_input["Assembly input"]
node_output["Executable output"]

node_user -->|"invokes"| node_entrypoint
node_user -->|"provides"| node_input
node_entrypoint -->|"produces"| node_output

click node_entrypoint "https://github.com/lovefromhsd/basm/blob/main/src/basm.sh"
click node_library "https://github.com/lovefromhsd/basm/blob/main/lib/basm.lib.sh"
click node_preprocessor "https://github.com/lovefromhsd/basm/blob/main/lib/functions/macro_preprocessor.sh"
click node_mode "https://github.com/lovefromhsd/basm/blob/main/lib/functions/assembly_mode.sh"
click node_firstpass "https://github.com/lovefromhsd/basm/blob/main/lib/functions/first_pass.sh"
click node_secondpass "https://github.com/lovefromhsd/basm/blob/main/lib/functions/second_pass.sh"
click node_opcodes "https://github.com/lovefromhsd/basm/blob/main/lib/functions/opcodes.sh"
click node_operands "https://github.com/lovefromhsd/basm/blob/main/lib/functions/operand_parsers.sh"
click node_elfheader "https://github.com/lovefromhsd/basm/blob/main/lib/functions/build_elf_header.sh"
click node_object "https://github.com/lovefromhsd/basm/blob/main/lib/functions/generate_elf_object_with_symbols.sh"
click node_collect "https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_collect.sh"
click node_resolve "https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_resolve.sh"
click node_layout "https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_layout.sh"
click node_relocate "https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_relocate.sh"
click node_emit "https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_emit.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_library,node_user toneBlue
class node_preprocessor,node_mode,node_firstpass,node_secondpass,node_opcodes,node_operands toneAmber
class node_elfheader,node_object,node_collect,node_resolve,node_layout,node_relocate,node_emit toneMint
class node_input,node_output toneIndigo
```

## Components

### Command entry

- [CLI entry](https://github.com/lovefromhsd/basm/blob/main/src/basm.sh): `src/basm.sh`
- [Bash library](https://github.com/lovefromhsd/basm/blob/main/lib/basm.lib.sh): `lib/basm.lib.sh`

### Assembly

- [Macro preprocessing](https://github.com/lovefromhsd/basm/blob/main/lib/functions/macro_preprocessor.sh): `lib/functions/macro_preprocessor.sh`
- [Assembly mode](https://github.com/lovefromhsd/basm/blob/main/lib/functions/assembly_mode.sh): `lib/functions/assembly_mode.sh`
- [First pass](https://github.com/lovefromhsd/basm/blob/main/lib/functions/first_pass.sh): `lib/functions/first_pass.sh`
- [Second pass](https://github.com/lovefromhsd/basm/blob/main/lib/functions/second_pass.sh): `lib/functions/second_pass.sh`
- [Opcode handling](https://github.com/lovefromhsd/basm/blob/main/lib/functions/opcodes.sh): `lib/functions/opcodes.sh`
- [Operand parsing](https://github.com/lovefromhsd/basm/blob/main/lib/functions/operand_parsers.sh): `lib/functions/operand_parsers.sh`

### ELF and linking

- [ELF header](https://github.com/lovefromhsd/basm/blob/main/lib/functions/build_elf_header.sh): `lib/functions/build_elf_header.sh`
- [Object generation](https://github.com/lovefromhsd/basm/blob/main/lib/functions/generate_elf_object_with_symbols.sh): `lib/functions/generate_elf_object_with_symbols.sh`
- [Link collection](https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_collect.sh): `lib/functions/linker_collect.sh`
- [Symbol resolution](https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_resolve.sh): `lib/functions/linker_resolve.sh`
- [Link layout](https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_layout.sh): `lib/functions/linker_layout.sh`
- [Relocation](https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_relocate.sh): `lib/functions/linker_relocate.sh`
- [Link emission](https://github.com/lovefromhsd/basm/blob/main/lib/functions/linker_emit.sh): `lib/functions/linker_emit.sh`

### Other components

- **User**
- **Assembly input**
- **Executable output**

## Connections

- User → CLI entry: invokes
- User → Assembly input: provides
- CLI entry → Executable output: produces