{"id":17249769,"url":"https://github.com/maxdesiatov/hleeb","last_synced_at":"2025-04-14T05:10:00.154Z","repository":{"id":66953232,"uuid":"470977317","full_name":"MaxDesiatov/Hleeb","owner":"MaxDesiatov","description":"Swift running on bare metal Raspberry Pi","archived":false,"fork":false,"pushed_at":"2022-03-17T13:47:51.000Z","size":44,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-14T05:09:50.513Z","etag":null,"topics":["bare-metal","kernel","operating-system","operating-system-learning","osdev","raspberry-pi","swift"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaxDesiatov.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":"2022-03-17T12:05:06.000Z","updated_at":"2024-10-13T17:03:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"78ce92c0-2a71-4240-bf1f-da5f90721bbb","html_url":"https://github.com/MaxDesiatov/Hleeb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxDesiatov%2FHleeb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxDesiatov%2FHleeb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxDesiatov%2FHleeb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxDesiatov%2FHleeb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaxDesiatov","download_url":"https://codeload.github.com/MaxDesiatov/Hleeb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824681,"owners_count":21167345,"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":["bare-metal","kernel","operating-system","operating-system-learning","osdev","raspberry-pi","swift"],"created_at":"2024-10-15T06:45:11.531Z","updated_at":"2025-04-14T05:10:00.134Z","avatar_url":"https://github.com/MaxDesiatov.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://vshymanskyy.github.io/StandWithUkraine/)\n\n## Swift running on bare metal Raspberry Pi 2\n\nHleeb (Ukrainian \"хліб\" for \"bread\") is collection of sample code allowing to run trivial Swift functions on bare\nmetal Raspberry Pi 2, aspiring to become an OS kernel in some distant future.\n\nBut Swift already runs on Raspberry Pi, what's the big deal?\n\nExisting port of Swift to Raspberry Pi runs in Linux user space, relying on the Linux kernel for memory management\nand I/O. With Hleeb we're trying to implement foundations of an OS kernel from scratch, utilizing Swift for it as\nmuch as possible.\n\n## Requirements\n\nHleeb relies on [uSwift](https://github.com/compnerd/uswift) as a minimalistic replacement for the Swift standard\nlibrary. Additionally, [a patch enabling bare metal targets](https://github.com/swiftwasm/swift/pull/4374) is\nrequired for the Swift toolchain to compile Hleeb.\n\nOn macOS, build requirements can be installed with [Homebrew](https://brew.sh) by executing `brew bundle` in the root\ndirectory of a clone of this repository.\n\n## How to build\n\n### Building a Swift toolchain for bare metal development\n\n0. Make sure you have at least 20-50 GB of free storage for the toolchain build. 8 GB is the minimal amount of RAM,\n16 GB is recommended. This was tested on macOS Big Sur with Xcode 13.2, earlier versions may work but weren't tested.\nBuilding on Linux may work, but you'll need to adjust these steps accordingly.\n\n1. Create a `swift-source` directory for the toolchain build in your working directory and navigate to it:\n\n```\nmkdir swift-source\ncd swift-source\n```\n\n2. Clone `maxd/baremetal` branch of [this Swift toolchain fork](https://github.com/swiftwasm/swift/pull/4374).\n   The patch is currently hosted in the SwiftWasm repository since bare metal target is just as useful when developing\n   for WebAssembly:\n\n```\ngit clone https://github.com/swiftwasm/swift.git\ncd swift\ngit checkout maxd/baremetal\n```\n\n3. Build the toolchain (this may take up to an hour on MacBook Air M1 or more an older hardware):\n\n```\n./utils/webassembly/ci.sh \u0026\u0026 cd ../..\n```\n\n### Building Hleeb\n\n1. Clone [uSwift](https://github.com/compnerd/uswift) in your working directory:\n\n```\ngit clone https://github.com/compnerd/uswift.git\n```\n\n2. Clone Hleeb directory on the same level as uSwift, it has to be adjacent. This directory structure is important,\n   since Hleeb symlinks the uSwift repository. We may consider converting this setup to use git submodules in the future.\n\n```\ngit clone https://github.com/MaxDesiatov/Hleeb.git\n```\n\n3. Build with CMake and Ninja, we're using `LLVM_BIN` pointing to LLVM installed on M1, you may need to adjust this path\n   if you're building on Intel. You also need to adjust `SWIFT_BIN` to the path of your freshly built Swift toolchain\n   with bare metal support:\n\n```\ncmake -B build -DLLVM_BIN=/opt/homebrew/opt/llvm/bin/ \\\n  -DSWIFT_BIN=\u003cyour_bare_metal_swift_toolchain_bin_path\u003e \\\n  -DCMAKE_TOOLCHAIN_FILE=./toolchain-arm-none-eabi.cmake \\\n  -DCMAKE_BUILD_TYPE=Release \\\n  -G Ninja -S . \u0026\u0026 \\\nninja -C build\n```\n\n### Testing Hleeb\n\nRun `./test.sh` after a successful build. This will execute the newly built \"kernel\" in QEMU emulating Raspberry Pi 2.\nYou should see the following output:\n\n```\n42\nHello, kernel World!\n```\n\nNumber 42 is computed with Swift code as a sum of numbers 40 and 2, called from the C code. Eventually we'd like\nto rewrite remaining C code that controls [UART](https://en.wikipedia.org/wiki/UART) in Swift, as soon as pointer\ntypes are fully working in uSwift.\n\nFor now we're leaving testing procedure on real RPi hardware as an exercise for the reader. See [this \ntutorial](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials#-usb-serial-output) for more details on\nUSB serial output, which is currently the only way to get output from Hleeb when running on real hardware.\n\n## Acknowledgments and educational resources\n\n- [Fork of apple/swift with modifications to the stdlib to use in a bare metal kernel](https://github.com/spevans/swift-kstdlib)\n- [OSDev.org Wiki](https://wiki.osdev.org/Main_Page)\n- [Learn to write an embedded OS in Rust](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)\n- [Learning operating system development using Linux kernel and Raspberry Pi](https://github.com/s-matyukevich/raspberry-pi-os)\n\n## License\n\nWhere not stated otherwise, Hleeb is available under the Apache 2.0 license.\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the [LICENSE](https://github.com/MaxDesiatov/Hleeb/blob/main/LICENSE) file for\nmore info.\n\nThis repository also incorporates code available under BSD-3 and MIT licenses, which is specified in headers of\ncorresponding files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxdesiatov%2Fhleeb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxdesiatov%2Fhleeb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxdesiatov%2Fhleeb/lists"}