{"id":21682341,"url":"https://github.com/beevik/monkos","last_synced_at":"2025-04-05T13:01:52.057Z","repository":{"id":42437223,"uuid":"50398371","full_name":"beevik/MonkOS","owner":"beevik","description":"an experimental 64-bit operating system","archived":false,"fork":false,"pushed_at":"2024-12-13T22:48:50.000Z","size":1088,"stargazers_count":135,"open_issues_count":0,"forks_count":20,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-29T12:02:45.044Z","etag":null,"topics":["bootloader","kernel","libc","os","osdev","x86-64"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beevik.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":"2016-01-26T02:50:23.000Z","updated_at":"2024-12-13T22:48:54.000Z","dependencies_parsed_at":"2024-11-25T15:51:06.657Z","dependency_job_id":null,"html_url":"https://github.com/beevik/MonkOS","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beevik%2FMonkOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beevik%2FMonkOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beevik%2FMonkOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beevik%2FMonkOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beevik","download_url":"https://codeload.github.com/beevik/MonkOS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339147,"owners_count":20923013,"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":["bootloader","kernel","libc","os","osdev","x86-64"],"created_at":"2024-11-25T15:35:44.594Z","updated_at":"2025-04-05T13:01:52.034Z","avatar_url":"https://github.com/beevik.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"MonkOS\n======\n\nMonkOS is an experimental 64-bit operating system for Intel and AMD\nprocessors. It is a mix of C and assembly language and is a work in progress.\nCurrently, it consists of a BIOS boot loader, a virtual console system, an\ninterrupt handling system, a paged memory manager, a heap allocator, a few\nsimple device drivers, and a primitive interactive shell. The boot loader is\ndesigned to launch the operating system from a cdrom.\n\n## Building\n\nThe OS currently builds under linux using a cross-compiler.  There are two\nways to build it: (1) by installing all the necessary tools on your system and\nrunning `make`, or (2) by using a ready-made docker container that contains\nall the build tools you'll need.\n\n### Building with local tools\n\nTo build with tools installed on your local system, you'll need to have\nthe following software already installed:\n\n* gcc x86_64 cross-compiler for elf binaries (I have used versions 4.8, 5.3,\n  6.3, 7.3, 8.2, 9.2, 10.2 and 14.2 successfully)\n* gnu binutils (I used version 2.34)\n* nasm assembler\n* genisoimage\n* exuberant-ctags (optional, for help with editing)\n* gdb (optional, for debugging)\n* qemu (optional, for testing)\n* doxygen (optional)\n\nMost of these tools are available from standard linux package managers. The\ncross-compiler, however, is not. To build a cross-compiler, consult the\ninstructions on [this page](http://wiki.osdev.org/GCC_Cross-Compiler). Make\nsure to also follow the [libgcc without\nred-zone](http://wiki.osdev.org/Libgcc_without_red_zone) instructions.\n\nOnce you've installed all the tools and made sure the cross-compiler is in\nyour path, run `make`.\n\n```bash\n$ make\n```\n\nThis results in a bootable cdrom ISO file called `monk.iso` in your build\nsubdirectory.\n\n### Building with docker-ized tools\n\nBecause it can be a bit of a hassle to build and install a cross-compiler, a\ndocker container has been prepared, allowing you to avoid building the cross-compiler\nyourself.  To run the docker-based build, make sure you have a recent\nversion of docker installed on your system, add yourself to your system's\ndocker user group, and then type the following:\n\n```bash\n$ make docker\n```\n\nThis will pull down the docker container\n([`brett/monkos-build`](https://hub.docker.com/r/brett/monkos-build/))\nif you don't already have it, run the build inside the container, and generate\nthe iso file (and all other intermediate output files) in your build\nsubdirectory.  It behaves almost exactly as if you ran `make` using a cross-\ncompiler installed locally on your system.\n\n## Running MonkOS\n\nThere are several ways to run MonkOS once you have the iso file. The first and\nmost time-consuming way is to burn it to a CD or DVD ROM using your favorite\nburning utility. This is the only way to test MonkOS on a bare-metal system.\n\nAlternatively, you can launch the operating system using virtual machine\nsoftware like VMware or virtualbox.\n\nOr you can run the operating system in a linux-based emulator like qemu or\nbochs.  The MonkOS makefile makes this alternative particularly easy by\nproviding a simple build rule to launch the OS in qemu:\n\n```bash\n$ make test\n```\n\nYou can also use the makefile to start a kernel debugging session under qemu\nand gdb. First, launch qemu in debugging mode:\n\n```bash\n$ make debug\n```\n\nThen start a gdb debugger session by attaching gdb to the qemu debugger\nendpoint:\n\n```\n$ gdb\n(gdb) set arch i386:x86-64\n(gdb) symbol-file build/monk.sys\n(gdb) target remote localhost:8864\n(gdb) layout src\n```\n\n## Other build options\n\nRun `make docs` to build nicely formatted documentation for MonkOS. You'll\nneed doxygen installed on your system to do this.\n\n```bash\n$ make docs\n```\n\nThe doxygen documents will appear in the `docs/monk` subdirectory. To view\nthem, launch them in your browser (in this case firefox):\n\n```bash\n$ firefox docs/monk/index.html\n```\n\nTo build code tags for easy symbol searching within your editor, use the\nmakefile to run the exuberant-tags utility:\n\n```bash\n$ make tags\n```\n\nThis produces a `.tags` file in your MonkOS directory.\n\nTo clean up all intermediate files, use the clean build:\n\n```bash\n$ make clean\n```\n\nTo clean all generated dependencies files, use the cleandeps build:\n\n```bash\n$ make cleandeps\n```\n\n## Documentation\n\nPlease consult the\n[Doxygen-formatted documentation](https://beevik.github.io/MonkOS/docs/monk/index.html),\nwhich is part of the [MonkOS documentation set](https://beevik.github.io/MonkOS/).\n\n## Resources\n\nThese are some of the resources I have relied on in my attempt to better\nunderstand the numerous and various aspects of bootloader and OS development:\n\n* [Intel 64 and IA-32 Architectures: Software Developer’s Manual](https://www-ssl.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html)\n* [The OsDev wiki](http://wiki.osdev.org/Main_Page)\n  * [Bare Bones guide](http://wiki.osdev.org/Bare_Bones)\n  * [Setting up long mode](http://wiki.osdev.org/Setting_Up_Long_Mode)\n  * [ISO 9660](http://wiki.osdev.org/ISO_9660)\n  * [PS/2 Keyboard](http://wiki.osdev.org/PS2_Keyboard)\n  * [PCI](http://wiki.osdev.org/PCI)\n* [The System V ABI](http://www.sco.com/developers/gabi/latest/contents.html)\n  * [AMD64 supplement](https://www.uclibc.org/docs/psABI-x86_64.pdf)\n* [The El Torito specification](https://pdos.csail.mit.edu/6.828/2014/readings/boot-cdrom.pdf)\n* [Hardware Level VGA and SVGA Video Programming Information Page](http://www.osdever.net/FreeVGA/vga/vgareg.htm)\n  * [CRT Controller Registers](http://www.osdever.net/FreeVGA/vga/crtcreg.htm)\n  * [Advanced Programmable Interrupt Controller](http://www.osdever.net/tutorials/view/advanced-programming-interrupt-controller)\n* [PCI ID repository](https://pci-ids.ucw.cz/)\n* [Write your own operating system](https://web.archive.org/web/20160306003015/http://geezer.osdevbrasil.net/osd/index.htm)\n  * [PC keyboard](https://web.archive.org/web/20160322061251/http://geezer.osdevbrasil.net/osd/kbd/index.htm)\n* Other experimental operating systems\n  * [The Xeos project](https://github.com/macmade/XEOS)\n  * [BareMetal OS](https://gitlab.com/ReturnInfinity/BareMetal-OS)\n  * [IanOS](http://www.ijack.org.uk/)\n\n## License\n\nUse of this source code is governed by a BSD-style license that can be found\nin the [LICENSE](https://github.com/beevik/MonkOS/blob/master/LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeevik%2Fmonkos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeevik%2Fmonkos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeevik%2Fmonkos/lists"}