docs: add submodule setup instructions, renumber BUILD_GUIDE sections

- Add new section 2 'Getting the Source' with git clone --recursive
  and fallback 'git submodule update --init --recursive' instructions.
- Note that the build system auto-initializes submodules and applies
  patches if not done manually.
- Fix DOOM section: reference submodule init instead of manual git
  clone; simplify to 'make doom'.
- Renumber sections 3-8 to accommodate the new section.

diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md
index fa0b4a1aa0e40d34517c52c4b57a6408c557adc0..0764b21fafc4b3c299f5476b97e24a766bdfc60b 100644 (file)
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -25,7 +25,22 @@ sudo apt install build-essential bison flex libgmp3-dev libmpc-dev libmpfr-dev t
     gcc-aarch64-linux-gnu gcc-riscv64-linux-gnu
 ```
 
-## 2. Building & Running (x86)
+## 2. Getting the Source
+
+```bash
+git clone --recursive https://github.com/tadryanom/AdrOS.git
+cd AdrOS
+```
+
+If you already cloned without `--recursive`, initialize the submodules:
+```bash
+git submodule update --init --recursive
+```
+
+The build system will auto-initialize submodules and apply required patches
+if they haven't been set up yet.
+
+## 3. Building & Running (x86)
 
 This is the primary target (standard PC).
 
@@ -182,18 +197,18 @@ Notes:
 - `QEMU_DEBUG=1` enables QEMU logging to `qemu.log` using `-d guest_errors,cpu_reset -D qemu.log`.
 - `QEMU_INT=1` appends `-d int` to QEMU debug flags.
 
-## 3. Building DOOM
+## 4. Building DOOM
 
-The DOOM port uses the [doomgeneric](https://github.com/ozkl/doomgeneric) engine with an AdrOS-specific platform adapter.
+The DOOM port uses the [doomgeneric](https://github.com/ozkl/doomgeneric) engine (included as a git submodule) with an AdrOS-specific platform adapter.
 
 ### Setup
 ```bash
-cd user/doom
-git clone https://github.com/ozkl/doomgeneric.git
-make
+# Submodules should already be initialized (see section 2).
+# If not: git submodule update --init --recursive
+make doom
 ```
 
-This produces `user/doom/doom.elf` (\~450KB). The main `Makefile` will **automatically include** `doom.elf` in the initrd if it exists.
+This produces `user/doom/doom.elf` (~450KB). The main `Makefile` will **automatically include** `doom.elf` in the initrd if it exists.
 
 ### Running DOOM
 ```bash
@@ -212,7 +227,7 @@ DOOM requires:
 - `doom1.wad` (shareware) accessible from the filesystem
 - Kernel support: `/dev/fb0` (mmap framebuffer), `/dev/kbd` (raw PS/2 scancodes), `nanosleep`, `clock_gettime`
 
-## 4. Building & Running (ARM64)
+## 5. Building & Running (ARM64)
 
 ### Build
 ```bash
@@ -240,7 +255,7 @@ Welcome to AdrOS (x86/ARM/RISC-V/MIPS)!
 - To quit QEMU when using `-nographic`: press `Ctrl+A`, release, then `x`.
 - ARM64 boots with PL011 UART at 0x09000000, EL2→EL1 transition, FP/SIMD enabled.
 
-## 5. Building & Running (RISC-V 64)
+## 6. Building & Running (RISC-V 64)
 
 ### Build
 ```bash
@@ -266,7 +281,7 @@ Welcome to AdrOS (x86/ARM/RISC-V/MIPS)!
 - To quit: `Ctrl+A`, then `x`.
 - RISC-V boots with NS16550 UART at 0x10000000, M-mode, `-bios none`.
 
-## 6. Building & Running (MIPS32)
+## 7. Building & Running (MIPS32)
 
 ### Build
 ```bash
@@ -292,7 +307,7 @@ Welcome to AdrOS (x86/ARM/RISC-V/MIPS)!
 - To quit: `Ctrl+A`, then `x`.
 - MIPS32 boots with 16550 UART at ISA I/O 0x3F8 (KSEG1 0xB80003F8), `-march=mips32r2`.
 
-## 7. Common Troubleshooting
+## 8. Common Troubleshooting
 
 - **"Multiboot header not found"**: Check whether `grub-file --is-x86-multiboot2 adros-x86.bin` returns success (0). If it fails, the section order in `linker.ld` may be wrong.
 - **"Triple Fault (infinite reset)"**: Usually caused by paging (VMM) issues or a misconfigured IDT. Run `make ARCH=x86 run QEMU_DEBUG=1` and inspect `qemu.log`.

diff --git a/Makefile b/Makefile
index 45968437f76e1a6aea94fb01d550a6b6452b73bf..a89e0844f59dcc4ff39bd77fa6a1e5e7db17e6ac 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -17,10 +17,13 @@ KERNEL_NAME := adros-$(ARCH).bin
 SRC_DIR := src
 BUILD_DIR := build/$(ARCH)
 
+.DEFAULT_GOAL := all
+
 # --- Submodule auto-init ---
-# If lwIP source is missing, the submodules haven't been initialized.
+# If any submodule source is missing, run git submodule update.
 LWIP_SENTINEL := third_party/lwip/src/core/init.c
-$(LWIP_SENTINEL):
+DOOM_SENTINEL := user/doom/doomgeneric/doomgeneric/doomgeneric.h
+$(LWIP_SENTINEL) $(DOOM_SENTINEL):
        @echo "  GIT     Initializing submodules..."
        @git submodule update --init --recursive
 
@@ -262,7 +265,7 @@ INITRD_FILES := $(FULLTEST_ELF):sbin/fulltest \
 INITRD_DEPS := $(MKINITRD) $(FULLTEST_ELF) $(USER_CMD_ELFS) $(LDSO_ELF) $(ULIBC_SO) $(PIE_SO) $(PIE_ELF) $(FSTAB)
 
 # doom (build via 'make doom', included in initrd if present)
-doom: $(ULIBC_LIB) $(ULIBC_SO)
+doom: $(DOOM_SENTINEL) $(ULIBC_LIB) $(ULIBC_SO)
        @$(MAKE) --no-print-directory -C user/doom TOPDIR=$(CURDIR) ULIBC_BUILDDIR="$(ULIBC_BUILDDIR)"
 
 # Include doom.elf if it has been built