{"id":15038942,"url":"https://github.com/includeos/includeos","last_synced_at":"2025-05-13T17:05:51.847Z","repository":{"id":18381731,"uuid":"21562567","full_name":"includeos/IncludeOS","owner":"includeos","description":"A minimal, resource efficient unikernel for cloud services","archived":false,"fork":false,"pushed_at":"2024-11-22T10:29:38.000Z","size":52785,"stargazers_count":5125,"open_issues_count":86,"forks_count":379,"subscribers_count":172,"default_branch":"main","last_synced_at":"2025-04-23T23:18:50.111Z","etag":null,"topics":["cpp","operating-system","unikernel","virtualization"],"latest_commit_sha":null,"homepage":"https://includeos.github.io/","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/includeos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","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":"2014-07-07T08:15:06.000Z","updated_at":"2025-04-21T06:32:23.000Z","dependencies_parsed_at":"2023-01-11T20:28:54.932Z","dependency_job_id":"f230ae84-207e-436c-96a6-1d1f495abfb1","html_url":"https://github.com/includeos/IncludeOS","commit_stats":{"total_commits":8005,"total_committers":86,"mean_commits":93.0813953488372,"dds":0.6664584634603372,"last_synced_commit":"d903be0ec80dd226f75eac56e2ef985d6dcdfe8c"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2FIncludeOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2FIncludeOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2FIncludeOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2FIncludeOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/includeos","download_url":"https://codeload.github.com/includeos/IncludeOS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250528993,"owners_count":21445544,"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":["cpp","operating-system","unikernel","virtualization"],"created_at":"2024-09-24T20:40:52.463Z","updated_at":"2025-04-23T23:18:55.189Z","avatar_url":"https://github.com/includeos.png","language":"C++","readme":"IncludeOS\n================================================\n\n**IncludeOS** is an includable, minimal [unikernel](https://en.wikipedia.org/wiki/Unikernel) operating system for C++ services running in the cloud and on real HW. Starting a program with `#include \u003cos\u003e` will literally include a tiny operating system into your service during link-time.\n\nIncludeOS is free software, with \"no warranties or restrictions of any kind\".\n\n**Note:** *IncludeOS is under active development. The public API should not be considered stable.*\n\n## \u003ca name=\"features\"\u003e\u003c/a\u003e Key features\n\n* **Extreme memory footprint**: A minimal bootable 64-bit web server, including operating system components and anything needed from the C/C++ standard libraries is currently 2.5 MB.\n* **KVM, VirtualBox and VMWare support** with full virtualization, using [x86 hardware virtualization](https://en.wikipedia.org/wiki/X86_virtualization), available on most modern x86 CPUs. IncludeOS will run on any x86 hardware platform, even on a physical x86 computer, given appropriate drivers. Officially, we develop for- and test on [Linux KVM](http://www.linux-kvm.org/page/Main_Page), and VMWare [ESXi](https://www.vmware.com/products/esxi-and-esx.html)/[Fusion](https://www.vmware.com/products/fusion.html) which means that you can run your IncludeOS service on Linux, Microsoft Windows and macOS, as well as on cloud providers such as [Google Compute Engine](http://www.includeos.org/blog/2017/includeos-on-google-compute-engine.html), [OpenStack](https://www.openstack.org/) and VMWare [vcloud](https://www.vmware.com/products/vcloud-suite.html).\n* **Instant boot:** IncludeOS on Qemu/kvm boots in about 300ms but IBM Research has also integrated IncludeOS with [Solo5/uKVM](https://github.com/Solo5/solo5), providing boot times as low as 10 milliseconds.\n* **Modern C++ support**\n    * Full C++11/14/17/20 language support with [clang](http://clang.llvm.org) 18 and later.\n    * Standard C++ library (STL) [libc++](http://libcxx.llvm.org) from [LLVM](http://llvm.org/).\n    * Exceptions and stack unwinding (currently using [libgcc](https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html)).\n    * *Note:* Certain language features, such as threads and filestreams are currently missing backend support but is beeing worked on.\n* **Standard C library** using [musl libc](http://www.musl-libc.org/).\n* **Virtio and vmxnet3 Network drivers** with DMA. [Virtio](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio) provides a highly efficient and widely supported I/O virtualization. vmxnet3 is the VMWare equivalent.\n* **A highly modular TCP/IP-stack**.\n\nA longer list of features and limitations can be found on our [documentation site](http://includeos.readthedocs.io/en/latest/Features.html).\n\n## Contents\n\n- [Getting started](#getting_started)\n    - [Dependencies](#dependencies)\n    - [Hello world](#hello_world)\n    - [Kernel development](#develop_kernel)\n    - [Running tests](#running_tests)\n- [Contributing to IncludeOS](#contribute)\n- [C++ Guidelines](#guideline)\n- [Security contact](#security)\n\n## \u003ca name=\"getting_started\"\u003e\u003c/a\u003e Getting started\n\n### \u003ca name=\"dependencies\"\u003e\u003c/a\u003e Dependencies\n\nFor building and booting IncludeOS services you will need [nix](https://nixos.org) and Linux. Nix will automatically download and set up the correct versions of all the required libraries and compilers.\n\nTo speed up local builds we also recommend configuring nix with [ccache support](https://nixos.wiki/wiki/CCache) but this is not a requirement. To use ccache, `--arg withCcache true` can be added to most `nix-build` and `nix-shell` commands shown below.\n\nIncludeOS can currently not be built on macOS or Windows.\n\n### \u003ca href=\"hello_world\"\u003e\u003c/a\u003e Hello World\n\nA minimal IncludeOS \"hello world\" looks like a regular C++ program:\n\n```c++\n#include \u003ciostream\u003e\n\nint main(){\n  std::cout \u003c\u003c \"Hello world\\n\";\n}\n```\n\nA full \"Hello world\" service with a working nix workflow is available in the [hello world repo](https://github.com/includeos/hello_world). The repository can also be used as a a starting point for developing your own IncludeOS service.\n\nFor more advanced service examples see the the integration tests (under ./IncludeOS/test/\\*/integration).\n\n### \u003ca name=\"develop_kernel\"\u003e\u003c/a\u003e Kernel development\n\nTo build IncludeOS, run\n\n```bash\n$ nix-build\n```\n\nThis will build the toolchain and all IncludeOS kernel libraries.\n\nNote that the first build will take some time to complete, as the IncludeOS toolchain is rebuilt from source code. This includes clang, llvm, libcxx, musl and so on. There is no nix binary cache available for these files at the moment. Subsequent builds will go much faster when the toolchain has been cached in the local nix-store.\n\nAfter making changes to the kernel, run `nix-build` again to get new binaries. If you are iterating on changes in one section of the kernel you can speed up the build significantly by using ccache. All `nix-build` and `nix-shell` commands in this section support the optional parameter `--arg withCcache true`.\n\nIt's not always practical to rebuild the whole kernel during development. You can get a development shell with a preconfigured environment using `shell.nix`:\n\n```bash\n$ nix-shell\n```\n\nFurther instructions will be shown for optionally configuring VM networking or overriding the build path when starting the shell.\n\nBy default th shell will also build the unikernel from `example.nix`. The example unikernel can be booted from within the shell:\n\n```bash\n$ nix-shell\n[...]\nnix$ boot hello_includeos.elf.bin\n```\n\nIf you want to build a different unikernel than the example, this can be specified with the `--argstr unikernel [path]` parameter. This is primarily used for integration tests. For example, to build and run the stacktrace-test:\n\n```bash\n$ nix-shell --argstr unikernel ./test/kernel/integration/stacktrace\n[...]\nnix$ ls -l kernel*\nkernel_stacktrace\nnix$ boot kernel_stacktrace\n[...]\nCalling os::print_backtrace()\nsymtab or strtab is empty, indicating image may be stripped\n[0] 0x000000000025dcd2 + 0x000: 0x25dcd2\n[1] 0x000000000021097d + 0x000: 0x21097d\n[2] 0x00000000002b370a + 0x000: 0x2b370a\n[3] 0x0000000000210eea + 0x000: 0x210eea\nWe reached the end.\n```\n\nTo build and run the test VM as a single command:\n\n```bash\n$ nix-shell --argstr unikernel ./test/kernel/integration/stacktrace --run ./test.py\n```\n\n### \u003ca name=\"running_tests\"\u003e\u003c/a\u003e Running tests\n\nYou can run all the integration tests using the script `./test.sh`. The tests will run locally in the nix environment. We recommend manually verifying that all the tests pass locally before submitting a new PR to IncludeOS to save review time.\n\nIndividual tests can be run with `nix-shell` directly. See `test.sh` for more details.\n\n## \u003ca name=\"contribute\"\u003e\u003c/a\u003e Contributing to IncludeOS\n\nIncludeOS is being developed on GitHub. Create your own fork and send us a pull request. Please read the [Guidelines for Contributing to IncludeOS](http://includeos.readthedocs.io/en/latest/Contributing-to-IncludeOS.html).\n\n## \u003ca name=\"guideline\"\u003e\u003c/a\u003e C++ Guidelines\n\nWe want to adhere as much as possible to the [ISO C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines). When you find code in IncludeOS which doesn't adhere, please let us know in the [issue tracker](https://github.com/includeos/IncludeOS/issues) - or even better, fix it in your own fork and send us a [pull-request](https://github.com/includeos/IncludeOS/pulls).\n\n## \u003ca name=\"security\"\u003e\u003c/a\u003e Security contact\nIf you discover a security issue in IncludeOS please avoid the public issue tracker. Instead send an email to security@includeos.org. For more information and encryption please refer to the [documentation](http://includeos.readthedocs.io/en/latest/Security.html).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincludeos%2Fincludeos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fincludeos%2Fincludeos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincludeos%2Fincludeos/lists"}