{"id":24369965,"url":"https://github.com/unikraft/app-click","last_synced_at":"2025-04-10T17:29:38.363Z","repository":{"id":53468942,"uuid":"241380385","full_name":"unikraft/app-click","owner":"unikraft","description":"Click Modular Router on Unikraft","archived":false,"fork":false,"pushed_at":"2024-06-03T10:44:14.000Z","size":10,"stargazers_count":3,"open_issues_count":0,"forks_count":6,"subscribers_count":12,"default_branch":"stable","last_synced_at":"2024-06-03T12:53:10.160Z","etag":null,"topics":["click","unikernel","unikraft-application"],"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/unikraft.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}},"created_at":"2020-02-18T14:20:35.000Z","updated_at":"2023-09-09T12:07:05.000Z","dependencies_parsed_at":"2023-01-22T11:40:12.394Z","dependency_job_id":"bbcb095f-8c77-4695-a69f-92d48ce2192b","html_url":"https://github.com/unikraft/app-click","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-click","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-click/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-click/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-click/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unikraft","download_url":"https://codeload.github.com/unikraft/app-click/tar.gz/refs/heads/stable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234597689,"owners_count":18857984,"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":["click","unikernel","unikraft-application"],"created_at":"2025-01-19T04:11:10.822Z","updated_at":"2025-01-19T04:11:11.982Z","avatar_url":"https://github.com/unikraft.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Click on Unikraft\n\nThis application starts a [Click](https://github.com/sysml/clickos) program with Unikraft.\nFollow the instructions below to set up, configure, build and run Click.\n\n## Quick Setup (aka TLDR)\n\nFor a quick setup, run the commands below.\nNote that you still need to install the [requirements](#requirements).\n\nFor building and running everything for `x86_64`, follow the steps below:\n\n```console\ngit clone https://github.com/unikraft/app-click click\ncd click/\nmkdir .unikraft\ngit clone https://github.com/unikraft/unikraft .unikraft/unikraft\ngit clone https://github.com/unikraft/lib-lwip .unikraft/libs/lwip\ngit clone https://github.com/unikraft/lib-musl .unikraft/libs/musl\ngit clone https://github.com/unikraft/lib-click .unikraft/libs/click\nUK_DEFCONFIG=$(pwd)/.config.click-qemu-x86_64 make defconfig\nmake -j $(nproc)\n./run-qemu-x86_64.sh\n```\n\nThis will configure, build and run the `click` application.\n\nThe same can be done for `AArch64`, by running the commands below:\n\n```console\nmake properclean\nUK_DEFCONFIG=$(pwd)/.config.click-qemu-aarch64 make defconfig\nmake -j $(nproc)\n./run-qemu-aarch64.sh\n```\n\nSimilar to the `x86_64` build, this will start the `click` application.\nInformation about every step is detailed below.\n\n## Requirements\n\nIn order to set up, configure, build and run Click on Unikraft, the following packages are required:\n\n* `build-essential` / `base-devel` / `@development-tools` (the meta-package that includes `make`, `gcc` and other development-related packages)\n* `sudo`\n* `flex`\n* `bison`\n* `git`\n* `wget`\n* `uuid-runtime`\n* `qemu-system-x86`\n* `qemu-system-arm`\n* `qemu-kvm`\n* `sgabios`\n* `gcc-aarch64-linux-gnu`\n\nOn Ubuntu/Debian or other `apt`-based distributions, run the following command to install the requirements:\n\n```console\nsudo apt install -y --no-install-recommends \\\n  build-essential \\\n  sudo \\\n  gcc-aarch64-linux-gnu \\\n  libncurses-dev \\\n  libyaml-dev \\\n  flex \\\n  bison \\\n  git \\\n  wget \\\n  uuid-runtime \\\n  qemu-kvm \\\n  qemu-system-x86 \\\n  qemu-system-arm \\\n  sgabios\n```\n\nRunning Click Unikraft with QEMU requires networking support.\nFor this to work properly a specific configuration must be enabled for QEMU.\nRun the commands below to enable that configuration (for the network bridge to work):\n\n```console\nsudo mkdir /etc/qemu/\necho \"allow all\" | sudo tee /etc/qemu/bridge.conf\n```\n\n## Set Up\n\nThe following repositories are required for Click:\n\n* The application repository (this repository): [`app-click`](https://github.com/unikraft/app-click)\n* The Unikraft core repository: [`unikraft`](https://github.com/unikraft/unikraft)\n* Library repositories:\n  * The networking stack library: [`lib-lwip`](https://github.com/unikraft/lib-lwip)\n  * The Musl libc library: [`lib-musl`](https://github.com/unikraft/lib-musl)\n  * The Click library: [`lib-click`](https://github.com/unikraft/lib-click)\n\nFollow the steps below for the setup:\n\n  1. First clone the [`app-click` repository](https://github.com/unikraft/app-click) in the `click/` directory:\n\n     ```console\n     git clone https://github.com/unikraft/app-click click\n     ```\n\n     Enter the `click/` directory:\n\n     ```console\n     cd click/\n\n     ls -F\n     ```\n\n     This will print the contents of the repository:\n\n     ```text\n     .config.click-qemu-aarch64  .config.click-qemu-x86_64  fs0/  kraft.yaml  Makefile  Makefile.uk  README.md helloworld.click\n     ```\n\n  1. While inside the `click/` directory, create the `.unikraft/` directory:\n\n     ```console\n     mkdir .unikraft\n     ```\n\n     Enter the `.unikraft/` directory:\n\n     ```console\n     cd .unikraft/\n     ```\n\n  1. While inside the `.unikraft` directory, clone the [`unikraft` repository](https://github.com/unikraft/unikraft):\n\n     ```console\n     git clone https://github.com/unikraft/unikraft unikraft\n     ```\n\n  1. While inside the `.unikraft/` directory, create the `libs/` directory:\n\n     ```console\n     mkdir libs\n     ```\n\n  1. While inside the `.unikraft/` directory, clone the library repositories in the `libs/` directory:\n\n     ```console\n     git clone https://github.com/unikraft/lib-lwip libs/lwip\n     git clone https://github.com/unikraft/lib-musl libs/musl\n     git clone https://github.com/unikraft/lib-click libs/click\n     ```\n\n  1. Get back to the application directory:\n\n     ```console\n     cd ../\n     ```\n\n     Use the `tree` command to inspect the contents of the `.unikraft/` directory.\n     It should print something like this:\n\n     ```console\n     tree -F -L 2 .unikraft/\n     ```\n\n     The layout of the `.unikraft/` directory should look something like this:\n\n     ```text\n     .unikraft/\n     |-- libs/\n     |   `-- lwip/\n     |   `-- musl/\n     |   `-- click/\n     `-- unikraft/\n         |-- arch/\n         |-- Config.uk\n         |-- CONTRIBUTING.md\n         |-- COPYING.md\n         |-- include/\n         |-- lib/\n         |-- Makefile\n         |-- Makefile.uk\n         |-- plat/\n         |-- README.md\n         |-- support/\n         `-- version.mk\n\n     10 directories, 7 files\n     ```\n\n## Configure\n\nConfiguring, building and running a Unikraft application depends on our choice of platform and architecture.\nCurrently, supported platforms are QEMU (KVM), Xen and linuxu.\nQEMU (KVM) is known to be working, so we focus on that.\n\nSupported architectures are x86_64 and AArch64.\n\nUse the corresponding the configuration files (`.config-...`), according to your choice of platform and architecture.\n\n### QEMU x86_64\n\nUse the `.config.click-qemu-x86_64` configuration file together with `make defconfig` to create the configuration file:\n\n```console\nUK_DEFCONFIG=$(pwd)/.config.click-qemu-x86_64 make defconfig\n```\n\nThis results in the creation of the `.config` file:\n\n```console\nls .config\n.config\n```\n\nThe `.config` file will be used in the build step.\n\n### QEMU AArch64\n\nUse the `.config.click-qemu-aarch64` configuration file together with `make defconfig` to create the configuration file:\n\n```console\nUK_DEFCONFIG=$(pwd)/.config.click-qemu-aarch64 make defconfig\n```\n\nSimilar to the x86_64 configuration, this results in the creation of the `.config` file that will be used in the build step.\n\n## Build\n\nBuilding uses as input the `.config` file from above, and results in a unikernel image as output.\nThe unikernel output image, together with intermediary build files, are stored in the `build/` directory.\n\n### Clean Up\n\nBefore starting a build on a different platform or architecture, you must clean up the build output.\nThis may also be required in case of a new configuration.\n\nCleaning up is done with 3 possible commands:\n\n* `make clean`: cleans all actual build output files (binary files, including the unikernel image)\n* `make properclean`: removes the entire `build/` directory\n* `make distclean`: removes the entire `build/` directory **and** the `.config` file\n\nTypically, you would use `make properclean` to remove all build artifacts, but keep the configuration file.\n\n### QEMU x86_64\n\nBuilding for QEMU x86_64 assumes you did the QEMU x86_64 configuration step above.\nBuild the Unikraft Click image for QEMU x86_64 by using the command below:\n\n```console\nmake -j $(nproc)\n```\n\nThis will print a list of files that are generated by the build system.\n\n```text\n[...]\n  LD      click_qemu-x86_64.dbg\n  UKBI    click_qemu-x86_64.dbg.bootinfo\n  SCSTRIP click_qemu-x86_64\n  GZ      click_qemu-x86_64.gz\nmake[1]: Leaving directory '[...]/click/.unikraft/unikraft'\n```\n\nAt the end of the build command, the `click-x86_64` unikernel image is generated.\nThis image is to be used in the run step.\n\n### QEMU AArch64\n\nIf you had configured and build a unikernel image for another platform or architecture (such as x86_64) before, then:\n\n1. Do a cleanup step with `make properclean`.\n\n1. Configure for QEMU AAarch64, as shown above.\n\n1. Follow the instructions below to build for QEMU AArch64.\n\nBuilding for QEMU AArch64 assumes you did the QEMU AArch64 configuration step above.\nBuild the Unikraft Click image for QEMU AArch64 by using the same command as for x86_64:\n\n```console\nmake -j $(nproc)\n```\n\nThis will print a list of files that are generated by the build system.\n\n```text\n[...]\n  LD      click_qemu-arm64.dbg\n  UKBI    click_qemu-arm64.dbg.bootinfo\n  SCSTRIP click_qemu-arm64\n  GZ      click_qemu-arm64.gz\nmake[1]: Leaving directory '[...]/click/.unikraft/unikraft'\n```\n\nSimilarly to x86_64, at the end of the build command, the `click-arm64` unikernel image is generated.\nThis image is to be used in the run step.\n\n## Run\n\nThe resulting image can be run with the `qemu-system-*` commands.\nIn order to run the `click` helloworld application, you need to first set up a network bridge.\nAll this is part of the `./run-qemu-*.sh` scripts.\n\n### QEMU x86_64\n\nTo run the QEMU x86_64 build, use `./run-qemu-x86_64.sh`:\n\n```console\n./run-qemu-x86_64.sh\n```\n\nThis will start the `click` helloworld application:\n\n```text\nSeaBIOS (version 1.16.0-debian-1.16.0-5)\n\niPXE (https://ipxe.org) 00:03.0 CA00 PCI2.10 PnP PMM+06FCAFC0+06F0AFC0 CA00\n                                                    \nPowered by\no.   .o       _ _               __ _\nOo   Oo  ___ (_) | __ __  __ _ ' _) :_\noO   oO ' _ `| | |/ /  _)' _` | |_|  _)\noOo oOO| | | | |   (| | | (_) |  _) :_\n OoOoO ._, ._:_:_,\\_._,  .__,_:_, \\___)\n      Prometheus 0.14.0~c66cdc68-custom\nReceived config (length 144):\ndefine($MAC0 52:54:00:12:34:56);\n/* End unikraft-provided MAC preamble */\nFromDevice\n  -\u003e Print('Hello, World!')\n  -\u003e EtherMirror\n  -\u003e ToDevice;\nHello, World!:   90 | 33330000 0016fe93 a0e40183 86dd6000 00000024 00010000\nHello, World!:  130 | 33330000 00160af9 d92a3d5f 86dd6000 0000004c 0001fe80\n[router_thread:200] Starting driver...\n\nHello, World!:   86 | 3333ffe4 0183fe93 a0e40183 86dd6000 00000020 3aff0000\nHello, World!:   90 | 33330000 0016fe93 a0e40183 86dd6000 00000024 00010000\n```\n\nTo close the QEMU `click` application, use the `Ctrl+a x` keyboard shortcut;\nthat is press the `Ctrl` and `a` keys at the same time and then, separately, press the `x` key.\n\n### QEMU AArch64\n\nTo run the AArch64 build, use `./run-qemu-aarch64.sh`:\n\n```console\n./run-qemu-aarch64.sh\n```\n\nSimilar to running for x86_64, this will start the `click` helloworld application.\nSimilarly, to close the QEMU Click instance, use the `Ctrl+a x` keyboard shortcut.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikraft%2Fapp-click","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funikraft%2Fapp-click","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikraft%2Fapp-click/lists"}