BitKindle README

项目的 README,来自 github.com/tombkeeper/BitKindle。合并为一个 markdown 文件:README.md。

简体中文 · English

BitKindle

A Windows x64 C compiler bootstrapped from a 3,584-byte machine-code seed

Platform: Windows x64 Seed: 3584 bytes Bootstrap: self-hosted License: MIT

Quick start · Bootstrap design · Walkthrough · Usage · Examples

Mario built with BitKindle

Mario example built with the BitKindle toolchain
Actual gameplay recording · Built-in automated player completes the level · Preview at 2× speed
Build and run instructions


Overview

BitKindle includes the complete sources for the A0/A1 assemblers, C0 transitional compiler, self-hosted C1 compiler written in C, runtime library, and PE linker.

Building requires no MSVC, GCC, Clang, Windows SDK, or external linker, and downloads no dependencies. PowerShell 5.1 decodes the seed and orchestrates the build. After decoding, every machine-code binary, object file, and EXE is generated by previously built custom tools.

Bootstrap pipeline

flowchart LR
    S["Hexadecimal seed<br/>3,584 bytes"] --> A["A0 → A1<br/>Custom assemblers"]
    A --> C["C0 → Bridge stages<br/>Transitional compilers"]
    C --> O["Progressive C1 extensions<br/>Object-file support"]
    O --> L["Custom PE linker"]
    O --> H["Final C1 + runtime"]
    L --> H
    H --> G1["Self-compiled generation 1"]
    G1 --> G2["Self-compiled generation 2"]
    G1 -. "Byte-identical" .-> G2

See BOOTSTRAP.md for stage dependencies and WALKTHROUGH.md for building individual stages with build-stage.ps1.

Quick start

Requires Windows x64 and Windows PowerShell 5.1 (powershell.exe); the verified environment is Windows 10 x64. Place the complete source tree in a writable local directory with a short path, preserving the name and hierarchy of src/. Reserve 5 GiB for the full test run.

Run from the release root:

powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\build-all.ps1

The default builds the compiler, linker, and C89/C99 runtimes, without running regression tests. After a successful build, compile and run hello:

$snapshot = './src/bootstrap-c99'
& "$snapshot/compile-program.ps1" -Source "$snapshot/examples/hello.c" `
    -Output './work/my-hello.exe' -BuildDirectory "$snapshot/build-from-seed" -Standard c89
if (!$?) { throw 'Compilation failed' }
& './work/my-hello.exe'

Expected output: hello.

Build modes

Append a mode option to the build command. All three modes build from the seed and check self-compilation identity and the compiler baseline. -All and -Full are mutually exclusive.

Option Build and test scope
None Toolchain and runtimes; no regression tests
-All Default mode plus compilation of hello, the argument example, minicurl, and Mario; does not run examples or regression tests
-Full Stage regressions, full audit, three supplemental suites, hello and argument examples, and minicurl local HTTP tests; Mario has separate build and test entry points

Logs and results are in work/release-run/. For default and -All, RESULT.json reports Status=BUILT and TestsRun=false. A successful -Full reports Status=PASS, TestsRun=true, and prints PASS release build and verification. An output directory alone is not evidence of success.

build-all.ps1 refuses to run if src/bootstrap-c99/build-from-seed/ or work/release-run/ already exists. Before rebuilding or changing modes, clean the default outputs or use a fresh source copy.

Examples

Example Features and interfaces Documentation
Hello / command-line arguments C runtime, startup, argc/argv Compilation and usage
minicurl HTTP/TLS through system WinHTTP; retrieve content and save it to a file Source and usage
Mario first level Side scrolling, keyboard input, collisions, timers, and GDI double buffering; graphics drawn in C Build and controls

With an existing toolchain, build examples individually using their documentation. Run them manually after building:

# GUI platform game
& './src/examples/mario/build/mario.exe'

# Optional online demo; requires working Windows networking and certificates
& './src/examples/minicurl/minicurl.exe' -o './work/example.html' 'https://example.com/'

Mario is an educational gameplay recreation; its documentation describes differences from the original.

Build artifacts and interfaces

The primary tools are:

src/bootstrap-c99/build-from-seed/
├── host/c1-stage2.exe    # C compiler
└── link-stage2.exe      # Custom Windows x64 PE linker

C1 reads C source from standard input and writes PE or .c1o object bytes to standard output. For ordinary programs, compile-program.ps1 configures headers, the runtime, and linker arguments.

See USAGE.md for multiple source files, command-line arguments, Windows DLL imports, and GUI subsystem selection.

Supported scope

Self-compilation identity and functional tests are not a complete correctness proof or standards certification. See Limits for capacities and restrictions.

Technical documentation

Topic Document
Seed decoding and staged bootstrapping Bootstrap design
Stage commands and validation steps Walkthrough
Application compilation and linking Usage
Source organization and toolchain composition Toolchain source guide
.c1o symbols and relocations Object format
Mathematical functions and internal algorithms Technical documentation

Cleaning and rebuilding

Close examples, wait for builds and tests to finish, and back up any artifacts or logs you need before running:

# Preview, clean, then rebuild from the seed
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\clean-all.ps1 -WhatIf
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\clean-all.ps1
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\build-all.ps1

Cleanup is limited to these default output locations; it does not remove source or documentation or change system settings:

Do not store handwritten files there. These directories are removed in full, including any .c1-build-* children. Manage custom build directories, USAGE examples, and .c1-build-* directories outside this list yourself; the script does not empty all of work/.

The script checks cleanup paths and uses paths in SOURCES.json to protect source files; it does not check source hashes. It stops at out-of-scope paths, symbolic links, or junctions. Do not run it concurrently with a build. If locked files cause partial cleanup failure, release them and retry.

License

Source code and accompanying project documentation use the MIT License. Windows, PowerShell, and system DLLs are supplied by the user's system and are not part of the project's MIT-licensed source.

BitKindle (tombkeeper/BitKindle)

正在搜索数据库…

这是什么?BitKindle 是一套完整的 Windows x64 C 编译工具链,包括汇编器、C 编译器、运行时库和 PE 链接器。它从一个 3,584 字节的机器码种子开始自举,不需要预先安装任何编译器或 SDK。
这是单个编译器程序还是完整的工具链?是完整的工具链。BitKindle 提供 A0/A1 汇编器、过渡期编译器 C0、自托管的 C1 编译器、运行时库以及它自带的 PE 链接器的完整源代码。
我需要先安装 MSVC、GCC 或 Windows SDK 吗?不需要。构建时不需要 MSVC、GCC、Clang 或 Windows SDK,也不会下载任何依赖项,只需要 Windows PowerShell 5.1 来解码种子并协调构建过程。
这个编译器完全符合 C99 标准吗?不完全符合。它支持 C89 以及许多 C99 特性(如变长数组、复数运算、复合字面量等),但不声称完全符合 C99 标准;而且它无法链接通用的 Windows SDK 头文件,也无法链接标准 COFF .obj/.lib 文件。
它能在哪个 Windows 版本上运行?它需要 Windows x64 系统和 Windows PowerShell 5.1;已验证的环境是 Windows 10 x64。
整个技术栈都采用 MIT 许可证吗?源代码和文档采用 MIT 许可证,但构建和运行时用到的 Windows、PowerShell 以及系统 DLL 来自用户自己的系统,不受该许可证约束。
3,584 字节的种子到底是做什么用的?它是最小的机器码起点,PowerShell 会先解码它;之后的每个汇编器、编译器阶段和链接器都由该种子生成的工具构建而来,全程不涉及任何外部编译器。
BitKindle 附带了哪些示例程序?有一个 hello-world/argv 演示程序、minicurl(通过 WinHTTP 获取 HTTP/TLS 内容),以及一个类似马里奥风格的横版卷轴游戏,具有键盘输入、碰撞检测,并且图形完全由 C 语言通过 GDI 绘制。
BitKindle 能链接普通的 Windows 库吗?它生成 Windows x64 PE 文件,使用显式的 DLL 导入,并采用自有的 .c1o 目标文件格式;但它不支持通用的 Windows SDK 头文件,也不支持标准 COFF .obj/.lib 文件,因此现有的开源 C 项目可能需要做适配。
完整构建需要多少磁盘空间?完整的 -Full 模式构建和测试运行大约需要 5 GiB 的可用空间,并且还会运行阶段回归测试以及补充的示例测试套件。
有哪些类似的项目?gcc, blaze, raddebugger, scriptc, porffor, fil-c, goose, compiler
大小
5.1 MB
星标
218
更新
提交Oct 20
时长
29天
提交 · 90 天