How ading2210/linuxpdf works
Project Type & Purpose
• This is a hybrid system that combines low-level C emulation (from TinyEMU) compiled to asm.js with a PDF file as the delivery format.
• Its core purpose is to simulate a Linux environment within a PDF by leveraging embedded Javascript in modern browsers.
• The project includes both build/integration scripts (build.sh, Python virtual environment, requirements.txt) and runtime assets (emulator code under “tinyemu”, HTML/JS in “web”, and supporting scripts).
Analysis of the File Structure
• Top-Level Components:
• .github/ (CI/CD workflows like deploy.yaml)
• Build/integration scripts (build.sh, embed_files.py, gen_pdf.py, etc.)
• The “tinyemu” directory contains all the C source code and related files for the RISC-V emulator; this is the core emulation engine.
• “web” directory has the static HTML/CSS files that likely support a demo or a test harness.
• Miscellaneous files like LICENSE, README.md, and project configuration files.
• Notice the multiple Makefiles in tinyemu (for JS and PDFjs targets) that indicate different build scripts for various output targets.
• The build chain includes integration with an old version of Emscripten (v1.39.20) to compile the C code to asm.js, which is the crucial runtime transformation.
Key Components
a. Build System and Toolchain:
• Python Virtual Environment & Dependencies (requirements.txt)
• Build script (build.sh) which downloads and uses Emscripten.
• The compilation process that takes the TinyEMU C source files and converts them into asm.js.
• Optional branches for 32-bit vs 64-bit builds (as mentioned in the README).
b. Core Emulator (TinyEMU):
• “tinyemu” module as the heart of the system.
• Split this into logical components: the CPU cores (RISC-V, x86), memory management (iomem), filesystem modules, network emulation (fs_net, slirp), and peripheral implementations (IDE, VGA, etc.).
• That these modules are compiled down to asm.js.
c. PDF/Javascript Environment:
• PDF file embedding: Show the PDF that integrates the compiled TinyEMU emulator.
• Browser’s PDF Engine: Explain that the browser (Chromium/Firefox) executes the Javascript contained in the PDF.
• Limited JS API set available in PDF viewers due to security restrictions.
d. User Interface:
• Output components: ASCII display where each text field corresponds to screen rows.
e. Runtime Flow:
• Data flow: User input (via browser UI elements) → Javascript in the PDF → Callbacks to the emulated emulator code → Emulated Linux kernel “boot” and response → ASCII screen updates back rendered within the PDF.
f. Deployment/Delivery:
• A web server (as per build instructions using python’s http.server) serves the generated PDF.
• CI/CD integration through GitHub Actions (via the .github/workflows directory).
Final Elements
• Build process: Code in “tinyemu” → Emscripten → asm.js files → included in PDF.
• Runtime flow: Browser loads PDF → Executes embedded JS → Invokes emulator → Processes user input and generates ASCII output.
• Deployment flow: Build artifacts → “out/“ directory → served via a web server.
• Build components (rectangles)
Happy diagramming!