# Makefile — repo-root quality gate.
#
# This is NOT the application build (each example builds from its own directory via make/tk.mk — run
# `make -C examples/<name> BOARD=<board> run`). It is the single entry point for the test harness that
# gates a release: build + run the host unit-test suites, optionally under coverage / MC-DC.
#
#   make test            # build + run every host unit-test suite (exit != 0 on any failing test)
#   make test-arch       # build + run the QEMU arch suites (live kernel: context switch + SMP)
#   make test-all        # host suites, then arch suites
#   make test-coverage   # the host suites under gcov line+branch instrumentation
#   make test-mcdc       # the host suites under LLVM source-based MC/DC (needs clang)
#   make clean-test      # remove the test build trees
#
# The host suites run on the host_test board (arch/flat: no context switch, deterministic) and cover the
# structural / handle-boundary contracts. The arch suites cross-compile a live kernel and run it under
# QEMU (real context save/restore, preemption, cross-hart SMP) — the coverage the no-switch host board
# cannot give. test-arch needs the cross-toolchain + QEMU on PATH; test does not.

.PHONY: help test test-arch test-all test-coverage test-mcdc clean-test docs docs-venv docs-clean

help:
	@echo 'tk kernel — repo-root quality gate:'
	@echo '  make test            build + run the host unit-test suites'
	@echo '  make test-arch       build + run the QEMU arch suites (needs cross-gcc + QEMU)'
	@echo '  make test-all        host suites, then arch suites'
	@echo '  make test-coverage   the host suites under gcov instrumentation'
	@echo '  make test-mcdc       the host suites under LLVM MC/DC (needs clang)'
	@echo '  make clean-test      remove the test build trees'
	@echo ''
	@echo 'Documentation (Sphinx; native Python, no Cygwin — .venv from docs/requirements.txt):'
	@echo '  make docs            build the HTML manual into docs/_build/html'
	@echo '  make docs-venv       create/refresh the docs virtualenv from the pinned lockfile'
	@echo '  make docs-clean      remove the docs build output'
	@echo ''
	@echo 'Applications build from their own dir, e.g.  make -C examples/threads BOARD=host run'

test:
	$(MAKE) -C tests run

test-arch:
	$(MAKE) -C tests arch-run

test-all:
	$(MAKE) -C tests run-all

test-coverage:
	$(MAKE) -C tests run COVERAGE=1

test-mcdc:
	$(MAKE) -C tests run MCDC=1

clean-test:
	$(MAKE) -C tests clean

# --- Documentation (Sphinx) --------------------------------------------------
# Native and Cygwin-free: pure Python. The HTML manual is built from the Markdown
# tree in docs/ via a local virtualenv (.venv) recreated from the pinned, committed
# docs/requirements.txt — so a given git tag always reproduces the same docs.
# `make docs` bootstraps the venv on first run.
DOCS_SRC  := docs
DOCS_OUT  := docs/_build/html
DOCS_REQS := docs/requirements.txt

ifeq ($(OS),Windows_NT)
  VENV_PY := .venv/Scripts/python.exe
else
  VENV_PY := .venv/bin/python
endif

docs: | $(VENV_PY)
	$(VENV_PY) -m sphinx -b html -d docs/_build/.doctrees $(DOCS_SRC) $(DOCS_OUT)
	@echo Docs built at $(DOCS_OUT)/index.html

docs-venv:
	python -m venv .venv
	$(VENV_PY) -m pip install --upgrade pip
	$(VENV_PY) -m pip install -r $(DOCS_REQS)

# Order-only prerequisite of `docs`: bootstrap the interpreter if it is missing.
$(VENV_PY):
	$(MAKE) docs-venv

docs-clean:
	python -c "import shutil; shutil.rmtree('docs/_build', ignore_errors=True)"