docs: 완성된 상태에 맞춰 AGENTS 와 TODO 를 다시 쓴다
파이프라인이 끝에서 끝까지 도는 상태다. 검증이 두 스위트로 나뉜다 -- 컴파일러가 프로그램에 대해 뭐라고 하는가, 그리고 컴파일된 프로그램이 실제로 무엇을 하는가. 전자만 보면 진단은 옳은데 코드가 안 나오는 상태를 놓친다. 세션 중에 완화한 이동 규칙 두 곳을 TODO 맨 위에 사람의 판단을 기다리는 항목으로 적었다. 규칙을 건드리기 전에 프로그램 쪽을 먼저 고쳐보라는 것도 작업 흐름에 넣었다.
This commit is contained in:
@@ -1,61 +1,69 @@
|
||||
# doslang 작업 규칙
|
||||
|
||||
DOS용 시스템 프로그래밍 언어 Ferro와 그 컴파일러 `fec`. 규범 문서는 `SPEC.md`이며
|
||||
이 파일은 그것을 구현할 때의 작업 규칙만 다룬다.
|
||||
DOS/Windows용 시스템 프로그래밍 언어 Ferro와 그 컴파일러 `fec`. 규범 문서는
|
||||
`SPEC.md`이며 이 파일은 그것을 구현할 때의 작업 규칙만 다룬다.
|
||||
|
||||
## 문서 지도
|
||||
|
||||
| 파일 | 역할 |
|
||||
|---|---|
|
||||
| `SPEC.md` | 언어 명세. 유일한 규범 문서. 구현 지시서와 표준 라이브러리 명세는 별도 문서 |
|
||||
| `TODO.md` | 남은 작업, 미결 결정, 순서 |
|
||||
| `SPEC.md` | 언어 명세. 유일한 규범 문서 |
|
||||
| `IR.md` | 중간 표현. 프론트엔드와 기계 사이 |
|
||||
| `TODO.md` | 남은 작업, 미결 결정, 정해진 것 |
|
||||
| `fec/tests/*/README.md` | 각 fixture 디렉터리가 무엇을 검사하는지 |
|
||||
|
||||
테스트 명령과 플래그는 다음 CLI로 확인한다.
|
||||
## 파이프라인
|
||||
|
||||
```powershell
|
||||
uv run python tests/run.py --help
|
||||
```
|
||||
.fe → fec → i386 asm → wasm → wlink → .exe
|
||||
└ lexer parser resolve types own check (프론트엔드)
|
||||
└ lower (IR)
|
||||
└ x86 (백엔드)
|
||||
```
|
||||
|
||||
## 검증 규칙
|
||||
`wasm`과 `wlink`는 고정된 Open Watcom의 어셈블러와 링커다 (WebAssembly와 무관).
|
||||
`SPEC.md` §1 철학 6: 링커와 오브젝트 포맷을 새로 만들지 않는다.
|
||||
|
||||
- 컴파일러는 현재 프런트엔드만 구현되어 있다. 범위: lexer/parser/types/own/check/resolve.
|
||||
- 코드 생성기(백엔드/IR/`lowering`)는 아직 없다.
|
||||
- 호스트 C 컴파일러는 구현/검증 대상이 아니다. 호스트는 편집, Git, 다운로드, 격리
|
||||
작업공간 준비에만 쓴다.
|
||||
## 검증
|
||||
|
||||
```powershell
|
||||
uv run python tests/run.py # 컴파일러가 프로그램에 대해 뭐라고 하는가
|
||||
uv run python tests/exec.py # 컴파일된 프로그램이 실제로 무엇을 하는가
|
||||
uv run python tests/build.py <프로그램.fe> # 하나만 빌드해서 돌려보기
|
||||
```
|
||||
|
||||
- **두 스위트를 모두 통과해야 한다.** `run.py`만 보면 진단은 옳은데 코드가 안 나오는
|
||||
상태를 놓친다. 보고만 되고 방출되지 않는 경계 검사가 그 예다.
|
||||
- 완료하려는 기능을 직접 검사하는 fixture가 통과해야 한다. 테스트가 증명하지 않는
|
||||
기능은 완료로 처리하지 않는다.
|
||||
- `uv run python tests/run.py` 가 유일한 검증 엔트리다. 툴체인은 `.dosboxx/watcom`에
|
||||
고정되어 있고, 없으면 오류로 멈춘다.
|
||||
- 거부를 기대하는 fixture는 첫 줄에 `// ERROR:<줄>:<문구>` 마커를 둔다. 마커가 없으면
|
||||
"거부되기만 하면 통과"라 검증이 약하다.
|
||||
- 과거 VM 이미지나 호스트에 남은 바이너리는 완료 근거로 쓰지 않는다.
|
||||
- 실행해야만 검증되는 fixture는 `fec/tests/pending-backend/`에 두고 러너가 건너뛴다.
|
||||
파일 이름이 기대값이 된다 — `bad`로 시작하면 거부, 아니면 통과.
|
||||
- 실행 프로그램은 첫 줄들에 `// EXIT:<코드>`, `// OUTPUT:<문구>`, `// NOCHECKS:<코드>`를
|
||||
둔다. 마지막 것은 `--no-checks`로 다시 빌드해서 다른 결과를 요구한다.
|
||||
- 툴체인은 `.dosboxx/watcom`에 고정되어 있고, 없으면 오류로 멈춘다.
|
||||
|
||||
## 빌드 함정
|
||||
## 함정
|
||||
|
||||
- [백엔드 복귀 시 유효] 컴파일러는 16비트 large model로 빌드한다. small model은
|
||||
메모리 부족으로 실패한다.
|
||||
- [백엔드 복귀 시 유효] 링크는 `*.obj` 와일드카드로 한다. DOS 명령줄 길이 제한 때문에
|
||||
오브젝트를 개별 열거할 수 없다.
|
||||
- [백엔드 복귀 시 유효] M4 Watcom 테스트는 `-wx -wcd=202`를 쓴다. 생성 C의 보수적 미
|
||||
사용 helper 때문에 W202만 끄고 나머지 경고는 오류로 유지한다.
|
||||
- [백엔드 복귀 시 유효] fixture는 DOS 8.3 이름으로 실행한다. 긴 이름은 registry에서
|
||||
명시적으로 줄인다.
|
||||
- [백엔드 복귀 시 유효] `R:`은 읽기 전용 저장소, `W:`은 읽기 전용 Watcom이다.
|
||||
빌드 산출물은 반드시 임시 `C:\FEC`에 쓴다.
|
||||
- [백엔드 복귀 시 유효] 실패 분석에는 임시 작업공간 보존이 필요하다. 그 플래그는
|
||||
런처와 함께 사라졌으므로 다시 만들어야 한다.
|
||||
- 표준 라이브러리는 프로그램이 아니라 컴파일러 옆에 있다. `--std=<디렉터리>`로
|
||||
넘기며, 그 디렉터리 안에 `std/`가 있어야 한다.
|
||||
- 유닛 경로의 각 segment는 소문자로 시작하고 `a-z0-9_`만, **최대 8자**다.
|
||||
파일 경로와 정확히 대응한다 (`std.io` ↔ `<std>/std/io.fe`).
|
||||
- `extern "c" fn`은 이름을 그대로 쓴다. 나머지는 `fe_<유닛>_<이름>`으로 맹글링하며
|
||||
어셈블러가 받지 않는 문자는 밑줄이 된다.
|
||||
- 슬라이스 배치(포인터 다음 길이)와 wrapper 페이로드 위치는 각각 한 군데에만
|
||||
적혀 있다. 두 군데가 되면 어긋난다.
|
||||
|
||||
## 작업 흐름
|
||||
|
||||
- 명세 판단이 바뀌면 `SPEC.md`를 즉시 갱신한다. 구현이 명세와 다르면 둘 중 하나가
|
||||
틀린 것이므로 그 자리에서 결론을 낸다.
|
||||
- 언어 규칙을 완화하려거든 먼저 프로그램 쪽을 고쳐본다. 규칙이 진짜 언어를 못 쓰게
|
||||
만들 때만 규칙을 건드리고, 무엇을 왜 바꿨는지 `TODO.md`에 남겨 사람이 판단하게
|
||||
한다.
|
||||
- 코드는 컴파일러 단계로 나눈다. 마일스톤 단위 분할은 폐기했다.
|
||||
- 검증된 단위마다 커밋한다. 푸시는 요청받았을 때만 한다.
|
||||
- primary 브랜치는 `master`다.
|
||||
- 검증된 단위마다 커밋한다. primary 브랜치는 `master`다.
|
||||
- `.dosboxx/`의 다운로드, 실행 작업공간, 로그는 커밋하지 않는다.
|
||||
|
||||
## 현재 상태
|
||||
|
||||
`uv run python tests/run.py` 의 통과 수가 현재 상태다. 남은 작업은 `TODO.md`에 있다.
|
||||
두 스위트의 통과 수가 현재 상태다. 남은 작업은 `TODO.md`에 있다.
|
||||
|
||||
@@ -1,9 +1,27 @@
|
||||
# TODO
|
||||
|
||||
현재: **188/188** (`uv run python tests/run.py`)
|
||||
```
|
||||
uv run python tests/run.py 209/209 컴파일러가 프로그램에 대해 뭐라고 하는가
|
||||
uv run python tests/exec.py 21/21 컴파일된 프로그램이 실제로 무엇을 하는가
|
||||
```
|
||||
|
||||
프론트엔드는 끝났다. 목표는 **i386 백엔드 + stdlib 으로 Windows 11 용 컴파일러를
|
||||
완성하는 것**이다. 아직 실행된 Ferro 프로그램은 하나도 없다.
|
||||
파이프라인이 끝에서 끝까지 돈다.
|
||||
|
||||
```
|
||||
.fe → fec → i386 asm → wasm → wlink → .exe → Windows 11
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 네 결정을 기다리는 것
|
||||
|
||||
세션 중에 **이동 규칙 두 곳을 완화**했다. 둘 다 R4(참조는 집합 저장소에
|
||||
못 들어감)가 아니라 이동 쪽이고, 되돌릴 수 있다.
|
||||
|
||||
| | 무엇 | 왜 | 대안 |
|
||||
|---|---|---|---|
|
||||
| 1 | `&mut T`를 `&mut T` 파라미터에 넘기는 것은 이동이 아니라 **호출 동안의 재대여** | 없으면 배타 파라미터를 다시 넘기는 일이 함수당 한 번뿐이라 `&mut`가 사실상 죽는다. SPEC §4.2에 이미 있던 "호출 인자 위치에서만" 재대여를 같은 종류끼리로 넓힌 것 | 되돌리면 재귀 하강 파서 같은 것을 못 쓴다 |
|
||||
| 2 | 자기 `drop` 안에서는 필드를 꺼낼 수 있다 (R7 예외) | 객체가 사라지는 중이라 뒤에 남아 읽힐 것이 없다. `mem.replace`로 우회하려면 유효한 대체값이 필요한데 그런 것이 없다 | `drop(self: Self)`로 값을 소비하게 바꾸면 R7을 안 건드려도 된다 |
|
||||
|
||||
---
|
||||
|
||||
@@ -11,72 +29,43 @@
|
||||
|
||||
| # | 일 | 규모 | 비고 |
|
||||
|---|---|---|---|
|
||||
| 1 | **IR 정의** | 중 | 3-address, 기본 블록, 함수 단위. 명령 12 + 종결자 4 |
|
||||
| 2 | **lowering** | 대 | `try`/`catch`/`orelse`/`defer`/drop/`for`/메서드/경계검사/옵셔널·에러유니온 구성/제네릭 인스턴스 전개. **프로젝트 무게중심** |
|
||||
| 3 | i386 백엔드 | 대 | IR → x86 asm → `wasm` → `wlink` → PE. 명령 선택, 레지스터 할당, 호출 규약 |
|
||||
| 4 | 런타임 | 소~중 | 시작 스텁, `fe_trap(reason, file, line)`, 할당, 종료 |
|
||||
| 5 | `pending-backend/` 4개 복귀 | 소 | bounds trap, `--no-checks` 차등, 소유권 drop. **처음으로 실행이 검증됨** |
|
||||
| 6 | stdlib 명세 | 중 | SPEC §10 이 플레이스홀더. 시그니처·오류·경계 동작 미정 |
|
||||
| 7 | stdlib 구현 | 대 | `core` `mem` `fmt` `io` `sys`, 그리고 제네릭이 생겼으니 `list` `map` |
|
||||
| 1 | 레지스터 할당 | 중 | 지금은 임시값마다 스택 슬롯이다. IR이 "임시값은 블록을 넘지 않는다"라서 블록 단위 할당기면 충분하다 |
|
||||
| 2 | `@print` 전개 | 소~중 | 지금은 `io.print` + `fmt.fmt_*`를 손으로 부른다. SPEC §6.3.1은 컴파일 단계 전개를 요구한다 |
|
||||
| 3 | `std.map` | 중 | `std.list`는 있다. 해시는 아직 |
|
||||
| 4 | `std.io` 읽기 | 소 | `Reader`, `io.read`. 지금은 쓰기만 |
|
||||
| 5 | `match` 페이로드 | 중 | 태그 비교는 된다. 페이로드 바인딩은 아직 |
|
||||
| 6 | `if let` | 소 | 프론트엔드는 검사한다. lowering이 아직 |
|
||||
| 7 | 셀프호스팅 | 대 | `fec`을 Ferro로. 여기까지 오면 언어가 자기 무게를 견딘다는 증거 |
|
||||
|
||||
## 그 이후
|
||||
## 미뤄둔 것
|
||||
|
||||
| | | |
|
||||
|---|---|---|
|
||||
| 셀프호스팅 | 대 | `fec` 을 Ferro 로. 여기까지 오면 언어가 자기 무게를 견딘다는 증거 |
|
||||
| 인터럽트·공유 상태 | 중 | `interrupt` `shared` `atomic` `critical` — 파싱만 되고 의미 없음. SPEC §11 에서 v0.2 |
|
||||
| 다른 32비트 타깃 | 대 | m68k / ARM / MIPS / RV32. IR 결정은 전부 ISA 중립이라 백엔드만 붙이면 됨 |
|
||||
| | |
|
||||
|---|---|
|
||||
| 인터럽트·공유 상태 | `interrupt` `shared` `atomic` `critical` — 파싱만 되고 의미 없음. SPEC §11에서 v0.2 |
|
||||
| 다른 32비트 타깃 | m68k / ARM / MIPS / RV32. IR 결정은 전부 ISA 중립이라 백엔드만 붙이면 된다 |
|
||||
| 엔디안 | 리틀엔디안 가정. `packed struct`가 바이트 배치를 약속하므로 빅엔디안 타깃이 생기면 타깃 파라미터가 된다 |
|
||||
| fixture 이름 122개 | DOS 8.3 시절 잔재. 마커가 다 붙어서 `bad`/`ok` 접두사는 더 이상 기대값이 아니다 |
|
||||
|
||||
---
|
||||
|
||||
## 미결 결정
|
||||
|
||||
| | 내용 | 언제 |
|
||||
|---|---|---|
|
||||
| 덩어리 전달 규약 | 정함 (전부 주소로). 3번 착수 전 재확인 | 3 전 |
|
||||
| `extern` C 상호운용 | 위 규약이 C ABI 와 안 맞음. 경계 변환 필요 | 3 전 |
|
||||
| 엔디안 | 리틀엔디안 가정. `packed struct` 가 바이트 배치를 약속하므로, 빅엔디안 타깃(m68k·MIPS·POWER)이 생기면 타깃 파라미터가 된다 | 다른 타깃 전 |
|
||||
| stdlib 명세 | SPEC §10 이 플레이스홀더 | 6 |
|
||||
|
||||
## 정해진 것
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 타깃 | **i386 하나.** 세그먼트 없음, `far` 영구 제외 (SPEC §2) |
|
||||
| `usize`/`isize` | **타깃의 포인터 폭.** 비트 수를 약속하지 않으므로 64비트 문이 닫히지 않음 |
|
||||
| 제네릭 | 모노모피제이션. 순수 프론트엔드 기능이라 IR 에 제네릭 개념이 없음 |
|
||||
| 덩어리 전달 | 전부 주소로. 크기 임계값 없음 — ISA 마다 다른 구조체 전달 ABI 를 피해감 |
|
||||
| `usize`/`isize` | **타깃의 포인터 폭.** 비트 수를 약속하지 않아 64비트 문이 닫히지 않음 |
|
||||
| 제네릭 | 모노모피제이션. 순수 프론트엔드 기능이라 IR에 제네릭 개념이 없음 |
|
||||
| 덩어리 전달 | 전부 주소로. 크기 임계값 없음 — ISA마다 다른 구조체 전달 ABI를 피해감 |
|
||||
| 트랩 | `trap <reason> <line>` → `fe_trap(reason, UNIT_FILE, line)`. 유닛당 파일 문자열 하나 |
|
||||
| 슬라이스 배치 | 포인터 다음 길이. 오프셋은 `lower.c` 한 군데에만 있다 |
|
||||
| 오류 코드 | `error.Name`을 빌드 전체에서 모아 철자 순으로 1부터. 빌드 순서가 결과를 안 바꿈 |
|
||||
| 셀프호스팅 | 640KB 목표 아님. 32비트 보호모드에서 돈다 (SPEC §2.1) |
|
||||
|
||||
---
|
||||
|
||||
## 순서
|
||||
|
||||
```
|
||||
1 → 2 IR + lowering
|
||||
3 → 4 → 5 i386 백엔드, 런타임, 실행 검증 복귀 ← 여기서 처음 실행됨
|
||||
6 → 7 stdlib
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 위임 정책
|
||||
|
||||
**위임 가능** — 결과가 자명하고 판단이 없는 것
|
||||
**위임 가능** — 결과가 자명하고 판단이 없는 것. 파일 목록을 **명시적으로 열거**하고
|
||||
기준선 두 숫자를 주고 **변하면 안 된다**고 못박을 것.
|
||||
|
||||
- fixture 이름 개선, README 갱신, 문서 정합
|
||||
- 파일 목록을 **명시적으로 열거해서** 줄 것. "찾아서 하라" 는 약함
|
||||
- 기준선 두 숫자(`N/188`, `M pin`)를 주고 **변하면 안 된다**고 못박을 것
|
||||
|
||||
**위임 불가** — 언어 의미론 판단이 섞인 것
|
||||
|
||||
- 마커 판정, IR/lowering/백엔드, stdlib 명세
|
||||
|
||||
---
|
||||
|
||||
## 미뤄둔 정리 작업
|
||||
|
||||
fixture 122개 이름이 아직 DOS 8.3 시절 잔재라 무엇을 검사하는지 이름만으로는
|
||||
알 수 없다. 마커가 전부 붙었으므로 `bad`/`ok` 접두사는 이제 기대값이 아니고,
|
||||
자유롭게 이름을 지을 수 있다. 급하지 않다.
|
||||
**위임 불가** — 언어 의미론 판단이 섞인 것. 마커 판정, IR/lowering/백엔드, stdlib 명세.
|
||||
|
||||
Reference in New Issue
Block a user