{"id":51391736,"url":"https://github.com/rodrgds/machine-lab","last_synced_at":"2026-07-04T00:06:17.522Z","repository":{"id":367642832,"uuid":"1276104142","full_name":"rodrgds/machine-lab","owner":"rodrgds","description":"Portable C courseware for teaching device-shaped systems programming, computer architecture, and final interactive projects.","archived":false,"fork":false,"pushed_at":"2026-07-02T14:02:54.000Z","size":26287,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T15:20:52.934Z","etag":null,"topics":["c","computer-architecture","courseware","education","emulator","operating-systems","systems-programming","teaching"],"latest_commit_sha":null,"homepage":"https://machine-lab-docs.pages.dev","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rodrgds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T14:44:46.000Z","updated_at":"2026-07-02T14:04:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rodrgds/machine-lab","commit_stats":null,"previous_names":["rodrgds/lcom-ng","rodrgds/machine-lab"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rodrgds/machine-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrgds%2Fmachine-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrgds%2Fmachine-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrgds%2Fmachine-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrgds%2Fmachine-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rodrgds","download_url":"https://codeload.github.com/rodrgds/machine-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodrgds%2Fmachine-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35105536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","computer-architecture","courseware","education","emulator","operating-systems","systems-programming","teaching"],"created_at":"2026-07-04T00:06:14.857Z","updated_at":"2026-07-04T00:06:17.514Z","avatar_url":"https://github.com/rodrgds.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Machine Lab\n\nMachine Lab is a portable C course kit for teaching how programs talk to\nmachine-like devices: ports, IRQs, framebuffers, audio buffers, serial links,\nand event loops. It keeps the useful ideas from older PC/Minix lab work, then\nremoves the VM and service-management ceremony so students can focus on the\nmachine model and the program they are building.\n\nThe historical LCOM material is treated as source material, not as the public\nidentity. The CLI is `machinelab`; `lcom` and `lowlab` stay as compatibility\naliases, and the C API still uses `lcom_*` names so older examples and lab code\nremain easy to port.\n\n\u003cp\u003e\n  \u003cimg src=\"docs/assets/screenshots/word-processor.png\" width=\"49%\" alt=\"Machine Lab word processor example\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/music-maker.png\" width=\"49%\" alt=\"Machine Lab music maker example\"\u003e\n\u003c/p\u003e\n\u003cp\u003e\n  \u003cimg src=\"docs/assets/screenshots/breakout.png\" width=\"49%\" alt=\"Machine Lab breakout project seed\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/flappy.png\" width=\"49%\" alt=\"Machine Lab Flappy Bird replay\"\u003e\n\u003c/p\u003e\n\n[Watch the 90-second demo](docs/assets/demo/machine-lab-90s.mp4): setup, a\nfailing lab test, the word processor, the music maker, and a captured project\nartifact.\n\nThe public docs site is live at \u003chttps://machine-lab-docs.pages.dev/\u003e. Its\nsource lives in [docs-site](docs-site) and is built with VitePress for\nCloudflare Pages. It is the canonical public surface for lab guides, adoption,\ndeveloper docs, examples, and launch posts.\n\n## Choose Your Lane\n\n| Audience | Start here | Work area |\n| --- | --- | --- |\n| Students | [Student guide](docs/student-guide.md) | generated workspace from `machinelab setup` |\n| Instructors | [Adoption guide](docs/adoption.md), [Instructor guide](docs/instructor-guide.md) | lab sequence, handouts, rubrics, examples |\n| Machine Lab developers | [Developer guide](docs/developer-guide.md) | this repository's runtime, docs, tests, releases |\n| Curious users | [Examples](examples/README.md) | runnable demos and project seeds |\n\nStudents should not need to understand this repository's CMake, runtime\ninternals, release workflow, or reference solutions. Developers should keep\nthat boundary intact.\n\n## Developer Quick Start\n\n```sh\ndevenv shell\nmachinelab-test\nmachinelab run build/examples/flappy_bird\n```\n\nInside the dev shell:\n\n- `machinelab` runs `./build/machinelab`, building it first if needed.\n- `machinelab-build` configures and builds with SDL enabled.\n- `machinelab-test` builds everything and runs unit, lab, and integration tests.\n- `lcom`, `lowlab`, and `mlab` are compatibility aliases for `machinelab`.\n\nWithout `devenv`, install CMake 3.20+, Ninja, a C/C++ toolchain, and optionally\nSDL3 plus SDL3_ttf. This path is for building Machine Lab itself:\n\n```sh\ncmake -S . -B build -G Ninja -DMACHINE_LAB_WITH_SDL=OFF\ncmake --build build\nctest --test-dir build --output-on-failure\n```\n\n## Student-Facing Course Surface\n\n- focused lab functions for bits, RTC, timers, keyboard, mouse, graphics,\n  audio, and UART;\n- reusable C helper libraries that the final project can link against;\n- deterministic replay scripts for input-heavy programs;\n- visible artifacts: traces, screenshots, WAVs, videos, and app bundles;\n- final projects such as games, editors, trackers, protocol demos, or visual\n  tools.\n\nFresh lab stubs compile and intentionally fail predefined checks until students\nfill the guided gaps.\n\nStudents normally see:\n\n- `machinelab setup \u003cworkspace\u003e`\n- `machinelab test \u003clab\u003e --project \u003cworkspace\u003e`\n- the generated `README.md`, `Makefile`, `include/lcom/`, `labs/`, `lib/`, and\n  `proj/` folders;\n- lab handouts in [course/labs/docs](course/labs/docs).\n\nStudents normally do not see:\n\n- `runtime/`, `common/`, `.github/`, release packaging, CMake internals;\n- reference solutions, except when an instructor intentionally publishes them;\n- `tests/integration.sh` and host-runtime regression tests.\n\n## Instructor Course Map\n\n| Lab | Device idea | Typical check |\n| --- | --- | --- |\n| 1 | bit masks, CMOS/RTC reads, BCD conversion | `machinelab test rtc` |\n| 2 | i8254 PIT divisors and IRQ0 event loops | `machinelab test timer` |\n| 3 | i8042 keyboard status and scancodes | `machinelab test kbd` |\n| 4 | PS/2 mouse commands and packet parsing | `machinelab test mouse` |\n| 5 | VBE modes, mapped framebuffers, sprites | `machinelab test graphics` |\n| 6 | AC97-style PCM buffers and playback | `machinelab test audio` |\n| 7 | 16550 UART setup, FIFOs, loopback, protocols | `machinelab test uart` |\n\nThe first half works like a lab track. The second half is a project studio:\nstudents combine several device areas into one reactive C application.\n\n## Runtime Features For Courses\n\n- virtual i8254 PIT, i8042 keyboard/mouse, RTC/CMOS, VBE framebuffer,\n  AC97-lite audio, and 16550 UART devices;\n- interactive SDL display, keyboard, mouse, text overlay, and audio;\n- deterministic headless execution for tests and CI;\n- authored replay scripts, live recording, captions, frame dumps, WAV capture,\n  MP4 rendering, and JSONL traces;\n- paired runtimes with bridged serial ports for two-player or protocol work;\n- generated student workspaces with Makefiles, lab stubs, test contracts, and\n  reference-solution-backed checks;\n- single-file or directory app bundles for finished projects.\n\n## Example Projects\n\n```sh\nmachinelab run --headless --script scripts/write_note.mlabscript \\\n  --dump-frame build/write.ppm -- build/examples/word_processor\n\nmachinelab run --headless --script scripts/music_maker_demo.mlabscript \\\n  --audio-wav build/music.wav --dump-frame build/music.ppm -- build/examples/music_maker\n\nmachinelab run --headless --script scripts/breakout_demo.mlabscript \\\n  --dump-frame build/breakout.ppm -- build/examples/breakout_demo\n```\n\nThe examples are deliberately more than toy snippets:\n\n- `word_processor`: cursor movement, insertion/deletion, wrapping, scrolling,\n  status bars, and document stats.\n- `music_maker`: tracker grid, tempo, playhead, per-track instruments, mixer\n  meters, and generated PCM output.\n- `breakout_demo`: timer-driven physics, keyboard state, collision, score,\n  lives, and a game HUD.\n- `flappy_bird`, `ninjix`, and `pvz`: larger ports that exercise game loops,\n  rendering, input, audio, and project structure.\n\n## Student Workspace\n\n```sh\nmachinelab setup student\nmake -C student\nmachinelab test rtc --project student\n```\n\nGenerated workspaces contain:\n\n| Path | Purpose |\n| --- | --- |\n| `include/lcom/` | public runtime/device headers |\n| `labs/\u003cdevice\u003e/` | guided starter implementations |\n| `lib/\u003cdevice\u003e/` | optional reusable helpers |\n| `proj/` | tiny app linked with lab objects |\n| `.mlab/` | copied tests and generated build artifacts |\n\n## Docs\n\n- [Public docs site source](docs-site): canonical VitePress site for students, instructors, and maintainers.\n- [Docs index](docs/index.md): student-facing, teacher-facing, and developer-facing map.\n- [Student guide](docs/student-guide.md): generated workspace workflow.\n- [Adoption guide](docs/adoption.md): how to use Machine Lab in a class in one week.\n- [Instructor guide](docs/instructor-guide.md): adoption and course operation.\n- [Developer guide](docs/developer-guide.md): maintaining Machine Lab itself.\n- [Getting started](docs/getting-started.md): local repo prerequisites and daily commands.\n- [Course labs](course/README.md): lab flow, handouts, and project studio.\n- [Examples](examples/README.md): focused demos and complete project seeds.\n- [Runtime and CLI](docs/runtime-and-cli.md): execution, capture, replay, bundles.\n- [Architecture](docs/architecture.md): process boundary and virtual devices.\n- [From Minix to Machine Lab](docs/from-minix.md): what stayed and what changed.\n- [Video demo](docs/video-demo.md): short teacher-demo script.\n- [Roadmap](docs/roadmap.md): implemented scope and future work.\n- [Contributing](CONTRIBUTING.md): contribution rules and review checklist.\n\nRun the generated CLI reference at any time:\n\n```sh\nmachinelab docs cli\n```\n\n## Repository Map For Developers\n\n| Path | Audience | Purpose |\n| --- | --- | --- |\n| `sdk/include/lcom/` | students | public C headers copied into workspaces |\n| `course/labs/docs/` | students/instructors | lab handouts |\n| `course/labs/templates/` | students | starter API contracts copied by `machinelab setup` |\n| `examples/` | instructors/developers | demos and final-project seeds |\n| `scripts/` | instructors/developers | deterministic input/replay timelines |\n| `docs-site/` | public | VitePress website deployed to Cloudflare Pages |\n| `runtime/`, `common/`, `sdk/client/` | developers | runtime server, protocol, and C client |\n| `dev/lab-solutions/`, `dev/lab-tests/`, `tests/` | developers/instructors | reference checks and regression tests |\n| `.github/workflows/release.yml` | developers | Linux, macOS, and Windows release builds |\n\nThe runtime is an educational device model, not a replacement for an operating\nsystems internals course. It is meant to make device-shaped C programming\nobservable, testable, and portable enough for a public course.\n\n## License\n\n- Code: [MIT License](LICENSE).\n- Course material, docs, screenshots, and demo media: [CC BY 4.0](course/LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodrgds%2Fmachine-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frodrgds%2Fmachine-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodrgds%2Fmachine-lab/lists"}