{"id":23004361,"url":"https://github.com/amjad50/emerald","last_synced_at":"2025-08-14T01:32:36.447Z","repository":{"id":205774035,"uuid":"715049889","full_name":"Amjad50/Emerald","owner":"Amjad50","description":"An Operating System in Rust","archived":false,"fork":false,"pushed_at":"2024-09-29T06:50:17.000Z","size":17536,"stargazers_count":12,"open_issues_count":23,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-09T03:27:31.673Z","etag":null,"topics":["operating-system","os","rust"],"latest_commit_sha":null,"homepage":"https://amjad.alsharafi.dev/Emerald","language":"Rust","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/Amjad50.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-11-06T11:33:21.000Z","updated_at":"2024-11-01T19:52:58.000Z","dependencies_parsed_at":"2023-12-22T16:36:55.495Z","dependency_job_id":"522fa599-2b29-4e28-b433-1b5ef2b03dc2","html_url":"https://github.com/Amjad50/Emerald","commit_stats":null,"previous_names":["amjad50/kernel","amjad50/emerald","amjad50/os"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2FEmerald","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2FEmerald/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2FEmerald/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amjad50%2FEmerald/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Amjad50","download_url":"https://codeload.github.com/Amjad50/Emerald/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229791309,"owners_count":18124667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["operating-system","os","rust"],"created_at":"2024-12-15T07:18:13.508Z","updated_at":"2024-12-15T07:18:14.130Z","avatar_url":"https://github.com/Amjad50.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Amjad50/Emerald\"\u003e\u003cimg alt=\"emerald OS logo\" src=\"book/src/assets/logo.svg\" width=\"40%\"\u003e\u003c/a\u003e\n  \u003cp align=\"center\"\u003eEmerald \u003cem\u003eOS\u003c/em\u003e\u003c/p\u003e\n\u003c/p\u003e\n\n[![OS Build](https://github.com/Amjad50/Emerald/actions/workflows/ci.yml/badge.svg)](https://github.com/Amjad50/Emerald/actions/workflows/ci.yml)\n[![Documentation](https://github.com/Amjad50/Emerald/actions/workflows/docs.yml/badge.svg)](https://amjad.alsharafi.dev/Emerald)\n\n**Emerald** is an OS written in [Rust] from scratch.\n\nThe plan is to learn everything about the kernel and low level details, so I'm implementing as much as\npossible without using any libraries.\nBut maybe I'll add those just to make the code smaller and better to work with.\n\n## Running\n\nIf you don't want to build the project, you can download the latest artifacts from:\n- [kernel.zip](https://nightly.link/Amjad50/Emerald/workflows/ci/master/kernel.zip)\n- [filesystem_programs.zip](https://nightly.link/Amjad50/Emerald/workflows/ci/master/filesystem_programs.zip)\n\nYou get `ISO` file containing the kernel and compressed `filesystem` directory containing the userspace programs.\n\nThe current command is what we use normally to run the OS, but can be run by any VM with some setup.\n```sh\nqemu-system-x86_64 -cdrom \u003ckernel.iso\u003e -serial mon:stdio -m 512 -boot d -drive format=raw,file=fat:rw:\u003cfilesystem\u003e\n```\n\nwhere `\u003ckernel.iso\u003e` is the path to the ISO file, and `\u003cfilesystem\u003e` is the path to the filesystem directory decompressed.\n\n\u003e Some extra info:\n\u003e - `-serial mon:stdio` is used to redirect the serial output to the terminal.\n\u003e - `-m 512` is the amount of memory to allocate for the VM, `512MB`.\n\u003e - `-boot d` is to boot from the CD-ROM we just loaded.\n\u003e - `-drive format=raw,file=fat:rw:\u003cfilesystem\u003e` is to pass the filesystem directory to the kernel as a disk.\n\u003e\n\u003e Here we use a feature of QEMU, `virtual fat`, where it will treat the directory as a FAT filesystem, and being passed\n\u003e to the kernel as a disk.\n\n## Building\n\nThe whole building and packaging is done by [xtask](./xtask/)\n\n\nThe ISO file can be used to run on other VMs/hardware(not tested)\n\nFor building the ISO image, you can use `make` but you need to have other dependencies installed to build and run the ISO:\n```\nxorriso mtools grub-pc-bin qemu-system-x86\n```\nBuild kernel iso:\n```sh\ncargo xtask build-iso\n```\n### Building userspace programs\nThis builds userspace programs into [`filesystem`](filesystem) directory (used by qemu):\n\nThe userspace programs are built using a custom `rust` toolchain (See more info [here](https://amjad.alsharafi.dev/Emerald/userspace/rust_std.html))\n\nAnyway, there are 2 options to build our userspace programs and in general any other program.\n\n#### Using the prebuilt toolchain\nWe distribute a prebuilt toolchain in:\n- [toolchain.zip](https://nightly.link/Amjad50/Emerald/workflows/ci/master/toolchain.zip)\nWhere you can install with\n```sh\nbash tools/install_toolchain_and_link.sh \u003cpath_to_toolchain.zip\u003e\n```\nThis will install the toolchain into `extern/toolchain` and link it to `rustup` as `emerald`.\n\nThen, `xtask` will use the installed toolchain to build userspace programs, if its not installed\nit will give an error.\n```\ncargo xtask userspace build\n```\n\n#### Building the toolchain\nWe don't build the toolchain automatically, i.e. if you don't have the toolchain you can build the toolchain yourself from source if you don't want to installed prebuilt.\n\n\n```sh\ncargo xtask toolchain\n```\nIf you want to build and install from source into [`extern/toolchain`](extern/toolchain) directory\n\u003e You can then use `rustup toolchain link ...` to link to this folder\n```sh\ncargo xtask toolchain --install\n```\n\n### Building and running\n\nTo build and run kernel and userspace programs:\n```sh\ncargo xtask run\n```\nYou need to have `qemu-system-x86_64` installed.\n\n### Debugging\nYou can use `gdb` or `lldb` to debug this.\n\nBut I have included vscode configs to enable easily debugging with `CodeLLDB` extension.\n\nAnd to boot QEMU in debug mode you can use (it will wait for debugger on port `:1234`)\n```sh\ncargo xtask run --gdb\n```\n\n## Documentation\n\nThe main documentation is in the [`book`](book) directory, you can build it using `mdbook`:\n```sh\nmdbook build book\n```\n\nIts also served in https://amjad.alsharafi.dev/Emerald/\n\n## Kernel\n### Booting\nCurrently, this project compiles a multiboot2 ELF64 kernel that can be booted by several bootloaders,\nI'm using GRUB using a bootloader like GRUB.\n\nGRUB and probably other bootloaders, will setup protected-mode (32bit) and then pass execution to the kernel starting in [`kernel/src/boot.S`].\n\u003e Note here, since we have moved to multiboot2 in [#2], we can directly start in 64bit with EFI, but right now\n\u003e since we already have [`kernel/src/boot.S`] running in 32bit in boot, let's keep on that, so that we can support both BIOS and EFI easily from\n\u003e the same entry point.\n\nIn the start of the kernel, we only do basic setup to switch to long-mode (64bit), this is done in assembly in [`kernel/src/boot.S`].\nAfter setting up long-mode, we jump to rust code, and start executing the `kernel_main` function.\n\nwhen we jump to the `kernel_main`, we have mapped some basic parts of the kernel to virtual memory, a basic GDT with no IDT, and we have interrupts still disabled.\nSo we setup all of those and the rest of the OS then.\n\n## Userland\n\nCurrently, the main focus for running userspace applications is by having `std` in rust, as all userspace applications\nare build in rust, this is the primary support. Thus, we don't have `libc` for now. We have [`emerald_std`](libraries/emerald_std/)\nwhich is the main dependency for that `std` uses.\n\nWe have our own target `x86_64-unknown-emerald` which is a custom target for our OS, added to custom fork\nof `rustc` in here: [`rust`].\n\n## Demo to userspace programs\n\nHere is a demo of the shell as is here. Another more complex application I can run is [lprs-fork](https://github.com/Amjad50/lprs) (not included in the demo below, but there is a demo in the README of that project).\n\n![demo](./assets/demo.gif)\n\n## License\nThis project is licensed under the MIT license, see [LICENSE](LICENSE) for more information.\n\n[Rust]: https://www.rust-lang.org/\n[#2]: https://github.com/Amjad50/Emerald/pull/2\n[`kernel/src/boot.S`]: kernel/src/boot.S\n[`rust`]: https://github.com/Amjad50/rust/tree/emerald_os\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famjad50%2Femerald","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famjad50%2Femerald","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famjad50%2Femerald/lists"}