From 5e92d29faabfd42d10c6f694751fba15a95788bb Mon Sep 17 00:00:00 2001 From: Alexander Jung Date: Wed, 12 Feb 2025 12:34:21 +0100 Subject: [PATCH] refactor!: Migrate zig from library to example Since Zig is a compile-time language and the entry contains simply a "Hello, world!" application it does not make sense to include it as a standalone entry in the library. This better serves as an example therefore. Additional changes clean up the example. Signed-off-by: Alexander Jung --- examples/helloworld-zig/Dockerfile | 31 ++++ examples/helloworld-zig/Kraftfile | 7 + examples/helloworld-zig/README.md | 57 +++++++ .../helloworld-zig}/helloworld.zig | 2 +- library/zig/0.11.0/Dockerfile | 21 --- library/zig/0.11.0/Kraftfile | 143 ------------------ library/zig/0.11.0/README.md | 21 --- 7 files changed, 96 insertions(+), 186 deletions(-) create mode 100644 examples/helloworld-zig/Dockerfile create mode 100644 examples/helloworld-zig/Kraftfile create mode 100644 examples/helloworld-zig/README.md rename {library/zig/0.11.0 => examples/helloworld-zig}/helloworld.zig (54%) delete mode 100644 library/zig/0.11.0/Dockerfile delete mode 100644 library/zig/0.11.0/Kraftfile delete mode 100644 library/zig/0.11.0/README.md diff --git a/examples/helloworld-zig/Dockerfile b/examples/helloworld-zig/Dockerfile new file mode 100644 index 00000000..44320956 --- /dev/null +++ b/examples/helloworld-zig/Dockerfile @@ -0,0 +1,31 @@ +FROM gcc:13.2.0-bookworm AS zig + +RUN set -xe; \ + apt-get update; \ + apt-get install -y --no-install-recommends \ + ca-certificates \ + curl \ + xz-utils; + +WORKDIR /zig + +ARG ZIG_VERSION=0.11.0 + +RUN set -xe; \ + curl -o /zig.tar.xz https://ziglang.org/download/${ZIG_VERSION}/zig-linux-$(uname -m)-${ZIG_VERSION}.tar.xz; \ + tar -xf /zig.tar.xz --strip-components 1 -C /zig; \ + mv /zig/zig /usr/bin/zig; \ + mv /zig/lib /usr/lib/zig + +FROM zig AS build + +WORKDIR /src + +COPY . /src + +RUN set -xe; \ + zig build-exe /src/helloworld.zig -fPIE -static + +FROM scratch + +COPY --from=build /src/helloworld /helloworld diff --git a/examples/helloworld-zig/Kraftfile b/examples/helloworld-zig/Kraftfile new file mode 100644 index 00000000..9039568f --- /dev/null +++ b/examples/helloworld-zig/Kraftfile @@ -0,0 +1,7 @@ +spec: v0.6 + +runtime: unikraft.org/base:latest + +rootfs: ./Dockerfile + +args: ["/helloworld"] diff --git a/examples/helloworld-zig/README.md b/examples/helloworld-zig/README.md new file mode 100644 index 00000000..d7ced256 --- /dev/null +++ b/examples/helloworld-zig/README.md @@ -0,0 +1,57 @@ +# Zig "Hello, world!" + +This directory contains a Zig-based "Hello, world!" example running on Unikraft. + +## Set Up + +To run this example, [install Unikraft's companion command-line toolchain `kraft`](https://unikraft.org/docs/cli), clone this repository and `cd` into this directory. + +## Run and Use + +Use `kraft` to run the image and start a Unikraft instance: + +```bash +kraft run --rm --plat qemu --arch x86_64 . +``` + +If the `--plat` argument is left out, it defaults to `qemu`. +If the `--arch` argument is left out, it defaults to your system's CPU architecture. + +Once executed, you should see a "Bye, World!" message. + +## Inspect and Close + +To list information about the Unikraft instance, use: + +```bash +kraft ps +``` + +```text +NAME KERNEL ARGS CREATED STATUS MEM PORTS PLAT +elastic_goblin oci://unikraft.org/base:latest /helloworld 9 seconds ago running 64M qemu/x86_64 +``` + +The instance name is `elastic_goblin`. +To close the Unikraft instance, close the `kraft` process (e.g., via `Ctrl+c`) or run: + +```bash +kraft rm elastic_goblin +``` + +Note that depending on how you modify this example your instance **may** need more memory to run. +To do so, use the `kraft run`'s `-M` flag, for example: + +```bash +kraft run --rm --plat qemu --arch x86_64 -M 256M . +``` + +## `kraft` and `sudo` + +Mixing invocations of `kraft` and `sudo` can lead to unexpected behavior. +Read more about how to start `kraft` without `sudo` at [https://unikraft.org/sudoless](https://unikraft.org/sudoless). + +## Learn More + +- [How to run unikernels locally](https://unikraft.org/docs/cli/running) +- [Building `Dockerfile` Images with `BuildKit`](https://unikraft.org/guides/building-dockerfile-images-with-buildkit) diff --git a/library/zig/0.11.0/helloworld.zig b/examples/helloworld-zig/helloworld.zig similarity index 54% rename from library/zig/0.11.0/helloworld.zig rename to examples/helloworld-zig/helloworld.zig index 933ff9b5..2629d29b 100644 --- a/library/zig/0.11.0/helloworld.zig +++ b/examples/helloworld-zig/helloworld.zig @@ -1,5 +1,5 @@ const std = @import("std"); pub fn main() !void { - std.debug.print("Hello, World!\n", .{}); + std.debug.print("Hello, world!\n", .{}); } diff --git a/library/zig/0.11.0/Dockerfile b/library/zig/0.11.0/Dockerfile deleted file mode 100644 index 8c4b6b2b..00000000 --- a/library/zig/0.11.0/Dockerfile +++ /dev/null @@ -1,21 +0,0 @@ -FROM debian:bookworm AS build - -# Necessary tools for instalation -RUN apt-get update && apt-get install curl xz-utils -y - -# Install Zig-0.11.0 -RUN curl https://ziglang.org/download/0.11.0/zig-linux-x86_64-0.11.0.tar.xz > zig-linux-x86_64-0.11.0.tar.xz && \ - tar -xf zig-linux-x86_64-0.11.0.tar.xz && \ - mv zig-linux-x86_64-0.11.0 /usr/local/bin/zig && \ - chmod +x /usr/local/bin/zig - -ENV PATH="/usr/local/bin/zig:${PATH}" - -COPY helloworld.zig / - -# Compile the helloworld.zig file -RUN zig build-exe helloworld.zig -fPIE -static - -FROM scratch - -COPY --from=build /helloworld /helloworld diff --git a/library/zig/0.11.0/Kraftfile b/library/zig/0.11.0/Kraftfile deleted file mode 100644 index 02cbcc68..00000000 --- a/library/zig/0.11.0/Kraftfile +++ /dev/null @@ -1,143 +0,0 @@ -spec: v0.6 - -name: zig - -rootfs: ./Dockerfile - -cmd: ["/helloworld"] - -template: - source: https://github.com/unikraft/app-elfloader.git - version: staging - -unikraft: - source: https://github.com/unikraft/unikraft.git - version: staging - kconfig: - # Configurations options for app-elfloader - # (they can't be part of the template atm) - CONFIG_APPELFLOADER_ARCH_PRCTL: 'y' - CONFIG_APPELFLOADER_BRK: 'y' - CONFIG_APPELFLOADER_CUSTOMAPPNAME: 'y' - CONFIG_APPELFLOADER_STACK_NBPAGES: 128 - CONFIG_APPELFLOADER_VFSEXEC_EXECBIT: 'n' - CONFIG_APPELFLOADER_VFSEXEC: 'y' - CONFIG_APPELFLOADER_HFS: 'y' - CONFIG_APPELFLOADER_HFS_ETCRESOLVCONF: 'y' - CONFIG_APPELFLOADER_HFS_ETCHOSTS: 'y' - CONFIG_APPELFLOADER_HFS_ETCHOSTNAME: 'y' - CONFIG_APPELFLOADER_HFS_REPLACEEXIST: 'y' - # Unikraft options - CONFIG_HAVE_PAGING_DIRECTMAP: 'y' - CONFIG_HAVE_PAGING: 'y' - CONFIG_I8042: 'y' - CONFIG_LIBDEVFS_AUTOMOUNT: 'y' - CONFIG_LIBDEVFS_DEV_NULL: 'y' - CONFIG_LIBDEVFS_DEV_STDOUT: 'y' - CONFIG_LIBDEVFS_DEV_ZERO: 'y' - CONFIG_LIBDEVFS: 'y' - CONFIG_LIBPOSIX_ENVIRON_ENVP0: "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - CONFIG_LIBPOSIX_ENVIRON_ENVP1: "LD_LIBRARY_PATH=/usr/local/lib:/usr/lib:/lib" - CONFIG_LIBPOSIX_ENVIRON_ENVP2: "HOME=/" - CONFIG_LIBPOSIX_ENVIRON: 'y' - CONFIG_LIBPOSIX_ENVIRON_LIBPARAM: 'y' - CONFIG_LIBPOSIX_ENVIRON_LIBPARAM_MAXCOUNT: '64' - CONFIG_LIBPOSIX_EVENTFD: 'y' - CONFIG_LIBPOSIX_FDIO: 'y' - CONFIG_LIBPOSIX_FDTAB: 'y' - CONFIG_LIBPOSIX_FUTEX: 'y' - CONFIG_LIBPOSIX_MMAP: 'y' - CONFIG_LIBPOSIX_NETLINK: 'y' - CONFIG_LIBPOSIX_PIPE: 'y' - CONFIG_LIBPOSIX_POLL: 'y' - CONFIG_LIBPOSIX_PROCESS_CLONE: 'y' - CONFIG_LIBPOSIX_SOCKET: 'y' - CONFIG_LIBPOSIX_SYSINFO: 'y' - CONFIG_LIBPOSIX_TIME: 'y' - CONFIG_LIBPOSIX_TIMERFD: 'y' - CONFIG_LIBPOSIX_UNIXSOCKET: 'y' - CONFIG_LIBPOSIX_USER_GID: 0 - CONFIG_LIBPOSIX_USER_GROUPNAME: "root" - CONFIG_LIBPOSIX_USER_UID: 0 - CONFIG_LIBPOSIX_USER_USERNAME: "root" - CONFIG_LIBPOSIX_USER: 'y' - CONFIG_LIBRAMFS: 'y' - CONFIG_LIBSYSCALL_SHIM_HANDLER_ULTLS: 'y' - CONFIG_LIBSYSCALL_SHIM_HANDLER: 'y' - CONFIG_LIBSYSCALL_SHIM_LEGACY_VERBOSE: 'y' - CONFIG_LIBSYSCALL_SHIM: 'y' - CONFIG_LIBUKALLOCPOOL: 'y' - CONFIG_LIBUKBLKDEV_MAXNBQUEUES: '1' - CONFIG_LIBUKBLKDEV_DISPATCHERTHREADS: 'y' - CONFIG_LIBUKBLKDEV_SYNC_IO_BLOCKED_WAITING: 'y' - CONFIG_LIBUKBLKDEV: 'y' - CONFIG_LIBUKBOOT_BANNER_MINIMAL: 'y' - CONFIG_LIBUKBOOT_HEAP_BASE: '0x400000000' - CONFIG_LIBUKBOOT_MAINTHREAD: 'y' - CONFIG_LIBUKBOOT_SHUTDOWNREQ_HANDLER: 'y' - CONFIG_LIBUKCPIO: 'y' - CONFIG_LIBUKDEBUG_CRASH_SCREEN: 'y' - CONFIG_LIBUKDEBUG_ENABLE_ASSERT: 'y' - CONFIG_LIBUKDEBUG_PRINT_SRCNAME: 'n' - CONFIG_LIBUKDEBUG_PRINT_TIME: 'y' - CONFIG_LIBUKDEBUG_PRINTK_ERR: 'y' - CONFIG_LIBUKDEBUG_PRINTK: 'y' - CONFIG_LIBUKDEBUG: 'y' - CONFIG_LIBUKFALLOC: 'y' - CONFIG_LIBUKMPI: 'n' - CONFIG_LIBUKSIGNAL: 'y' - CONFIG_LIBUKSWRAND_DEVFS: 'y' - CONFIG_LIBUKSWRAND: 'y' - CONFIG_LIBUKVMEM_DEFAULT_BASE: '0x0000001000000000' - CONFIG_LIBUKVMEM_DEMAND_PAGE_IN_SIZE: 12 - CONFIG_LIBUKVMEM_PAGEFAULT_HANDLER_PRIO: 4 - CONFIG_LIBUKVMEM: 'y' - CONFIG_LIBVFSCORE_AUTOMOUNT_CI: 'y' - CONFIG_LIBVFSCORE_AUTOMOUNT_CI_EINITRD: 'y' - CONFIG_LIBVFSCORE_AUTOMOUNT_UP: 'y' - CONFIG_LIBVFSCORE_AUTOMOUNT: 'y' - CONFIG_LIBVFSCORE_NONLARGEFILE: 'y' - CONFIG_LIBVFSCORE: 'y' - CONFIG_OPTIMIZE_DEADELIM: 'y' - CONFIG_OPTIMIZE_LTO: 'y' - CONFIG_PAGING: 'y' - CONFIG_STACK_SIZE_PAGE_ORDER: 4 # 128 * 4K = 512K - CONFIG_UKPLAT_MEMREGION_MAX_COUNT: 64 - CONFIG_LIBUKNETDEV_EINFO_LIBPARAM: 'y' - - # Debug options - # CONFIG_LIBUKDEBUG_PRINTD: 'y' - # CONFIG_LIBUKDEBUG_PRINTK_INFO: 'y' - # CONFIG_LIBSYSCALL_SHIM_STRACE: 'y' - # CONFIG_LIBSYSCALL_SHIM_DEBUG: 'y' - -libraries: - lwip: - source: https://github.com/unikraft/lib-lwip.git - version: staging - kconfig: - CONFIG_LWIP_LOOPIF: 'y' - CONFIG_LWIP_UKNETDEV: 'y' - CONFIG_LWIP_LOOPBACK: 'y' - CONFIG_LWIP_TCP: 'y' - CONFIG_LWIP_UDP: 'y' - CONFIG_LWIP_RAW: 'y' - CONFIG_LWIP_WND_SCALE: 'y' - CONFIG_LWIP_TCP_KEEPALIVE: 'y' - CONFIG_LWIP_THREADS: 'y' - CONFIG_LWIP_HEAP: 'y' - CONFIG_LWIP_SOCKET: 'y' - CONFIG_LWIP_AUTOIFACE: 'y' - CONFIG_LWIP_IPV4: 'y' - CONFIG_LWIP_DHCP: 'y' - CONFIG_LWIP_DNS: 'y' - CONFIG_LWIP_NUM_TCPCON: 64 - CONFIG_LWIP_NUM_TCPLISTENERS: 64 - CONFIG_LWIP_ICMP: 'y' - libelf: - source: https://github.com/unikraft/lib-libelf.git - version: staging - -targets: -- fc/x86_64 -- qemu/x86_64 diff --git a/library/zig/0.11.0/README.md b/library/zig/0.11.0/README.md deleted file mode 100644 index 9b9078f5..00000000 --- a/library/zig/0.11.0/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Zig 0.11.0 - -This directory contains the definition for the `unikraft.org/zig:0.11.0` image running Zig. - -To run this image, [install Unikraft's companion command-line toolchain `kraft`](https://unikraft.org/docs/cli) and then you can run: - -```console -kraft run unikraft.org/zig:0.11.0 -``` - -Once executed, it will print: - -```console -Hello, World! -``` - -You will get a simple "Hello, World!" from Zig. - -## See also - -- [How to run unikernels locally in Unikraft's Documentation](https://unikraft.org/docs/cli/running).