{"id":28744478,"url":"https://github.com/ktauchathuranga/lua-linux-distro","last_synced_at":"2026-05-15T13:35:29.904Z","repository":{"id":298167822,"uuid":"999088790","full_name":"ktauchathuranga/lua-linux-distro","owner":"ktauchathuranga","description":"3MB Minimal Linux distribution built from scratch, featuring a custom shell and the Lua interpreter","archived":false,"fork":false,"pushed_at":"2025-06-09T18:45:47.000Z","size":1607,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-11T15:22:32.246Z","etag":null,"topics":["linux-distro","lua"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ktauchathuranga.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-09T18:09:10.000Z","updated_at":"2025-06-10T09:40:33.000Z","dependencies_parsed_at":"2025-06-09T19:39:34.460Z","dependency_job_id":"ef72ad98-2298-4780-b2c8-4537194a89d2","html_url":"https://github.com/ktauchathuranga/lua-linux-distro","commit_stats":null,"previous_names":["ktauchathuranga/lua-linux-distro"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ktauchathuranga/lua-linux-distro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktauchathuranga%2Flua-linux-distro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktauchathuranga%2Flua-linux-distro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktauchathuranga%2Flua-linux-distro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktauchathuranga%2Flua-linux-distro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ktauchathuranga","download_url":"https://codeload.github.com/ktauchathuranga/lua-linux-distro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktauchathuranga%2Flua-linux-distro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33068704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["linux-distro","lua"],"created_at":"2025-06-16T12:01:01.242Z","updated_at":"2026-05-15T13:35:29.884Z","avatar_url":"https://github.com/ktauchathuranga.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minimal Linux Distribution with Custom Shell and Lua\n\nThis repository contains a minimal Linux distribution built from scratch, featuring a custom shell and the Lua interpreter, packaged into a bootable ISO image. The distribution uses the Linux 6.15.1 kernel and can be tested using QEMU.\n\n## Overview\n\nThis project creates a lightweight Linux system that boots into a custom shell (`init`) implemented in C and assembly. The shell supports basic command execution using system calls (`fork`, `execve`, `waitid`, etc.) and is packaged into an initramfs (`init.cpio`). The Lua interpreter is included, allowing users to run Lua scripts in the environment. The system is built into a bootable ISO image for testing with QEMU or on real hardware.\n\n## How it looks\n\n![Screenshot From 2025-06-10 00-14-31](https://github.com/user-attachments/assets/a47e72c6-cf3b-41ed-a81c-16ff51e0b2e0)\n\n\n## Features\n- Custom shell written in C (`shell.c`) with x86_64 assembly system call wrappers (`sys.S`).\n- Minimal initramfs (`init.cpio`) containing the shell and Lua interpreter.\n- Bootable ISO image generated using the Linux 6.15.1 kernel.\n- Tested with QEMU for easy development and debugging.\n- Lightweight and optimized build with no stack protection and non-executable stack.\n\n## Prerequisites\n- **Arch Linux** (or another Linux distribution with adjustments).\n- **Linux Kernel Source**: Linux 6.15.1 (place in `~/linux-iso/linux-6.15.1`).\n- **Build Tools**:\n  ```bash\n  sudo pacman -S base-devel gcc make cpio syslinux cdrtools\n  ```\n- **QEMU**:\n  ```bash\n  sudo pacman -S qemu-system-x86\n  ```\n- **Optional (for Lua)**: Ensure the `lua` binary is available in the `work` directory or initramfs.\n\n## Repository Structure\n- `build.sh`: Script to compile `shell.c`, assemble `sys.S`, link the executable, and create `init.cpio`.\n- `shell.c`: C source for the custom shell, implementing a command-line interface.\n- `sys.S`: x86_64 assembly code providing system call wrappers.\n- `init`: The compiled shell executable, used as the init process.\n- `init.cpio`: The initramfs archive containing `init` and `lua`.\n- `lua`: Lua interpreter binary (included in the initramfs).\n- `iso/`: Directory containing the built ISO image (`image.iso`).\n- `shell.o`, `sys.o`: Intermediate object files from compilation.\n- `files`: Optional file list for initramfs creation (commented in `build.sh`).\n\n## Build Instructions\n1. **Clone the Repository**:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd \u003crepository-name\u003e\n   ```\n\n2. **Prepare the Linux Kernel**:\n   - Download and extract the Linux 6.15.1 kernel source to `~/linux-iso/linux-6.15.1`.\n   - Configure and build the kernel:\n     ```bash\n     cd ~/linux-iso/linux-6.15.1\n     make defconfig\n     make -j4\n     ```\n\n3. **Build the Shell and Initramfs**:\n   - Ensure `lua` is in the `work` directory (or modify `init.cpio` to include it).\n   - Run the build script:\n     ```bash\n     chmod +x build.sh\n     ./build.sh\n     ```\n   This compiles `shell.c`, assembles `sys.S`, links them into `init`, and creates `init.cpio`.\n\n4. **Create the Bootable ISO**:\n   - In the kernel source directory:\n     ```bash\n     cd ~/linux-iso/linux-6.15.1\n     make isoimage FDARGS=\"initrd=/init.cpio\" FDINITRD=~/\u003crepository-path\u003e/work/init.cpio\n     ```\n   The ISO will be created at `arch/x86/boot/image.iso`.\n\n## Usage\n1. **Test with QEMU (Serial Console)**:\n   ```bash\n   qemu-system-x86_64 -cdrom ~/linux-iso/linux-6.15.1/arch/x86/boot/image.iso -nographic -serial mon:stdio -append \"console=ttyS0\"\n   ```\n   - This boots the ISO, displaying the shell prompt (`#`) in the terminal.\n   - Type commands (e.g., `lua` to run the Lua interpreter, if included).\n\n2. **Test with QEMU (Graphical Output)**:\n   ```bash\n   qemu-system-x86_64 -cdrom ~/linux-iso/linux-6.15.1/arch/x86/boot/image.iso\n   ```\n   - Connect to the VNC server:\n     ```bash\n     vncviewer localhost:5900\n     ```\n\n3. **Run Commands**:\n   - At the `#` prompt, enter commands like `/bin/lua` (if `lua` is in the initramfs) or other executables included in `init.cpio`.\n   - Note: The shell requires commands to be full paths (e.g., `/bin/lua`).\n\n## Adding Lua to the Initramfs\nTo include the Lua interpreter in `init.cpio`:\n1. Copy the `lua` binary to an initramfs directory:\n   ```bash\n   mkdir -p initramfs/bin\n   cp lua initramfs/bin/lua\n   cp init initramfs/init\n   ```\n2. Create the `cpio` archive:\n   ```bash\n   cd initramfs\n   find . | cpio -o -H newc \u003e ../init.cpio\n   ```\n3. Rebuild the ISO as shown above.\n\n## Notes\n- The shell (`shell.c`) is minimal and expects commands with full paths (e.g., `/bin/lua`).\n- Ensure the Linux kernel is configured with serial console support (`CONFIG_SERIAL_8250_CONSOLE=y`) for `-nographic` output.\n- If the kernel panics (e.g., “No init found”), verify `init.cpio` contains a valid `/init` executable.\n- The `files` file and commented lines in `build.sh` are optional and can be used to customize the initramfs.\n\n## Credits\n- Based on the YouTube tutorial [\"Writing a Simple Operating System from Scratch - Part 2: Writing a Shell\"](https://www.youtube.com/watch?v=u2Juz5sQyYQ) by The CS Guy.\n- Extended with Lua interpreter integration for additional functionality.\n\n## Contributing\nFeel free to submit issues or pull requests to improve the shell, add features, or enhance documentation.\n\n---\n\n**Note**: This is an educational project designed to demonstrate low-level Linux programming concepts. It is not intended for production use.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktauchathuranga%2Flua-linux-distro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktauchathuranga%2Flua-linux-distro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktauchathuranga%2Flua-linux-distro/lists"}