Add Makefile, configuration files and scripts

Update the README with instructions on setting up, configuring, building and running the Python3 app with Unikraft. As part of it, add Makefile files, configuration files and scripts; they are referenced in the `README.md` file. Current instructions cover the use of QEMU/KVM platform (both on x86_64 and on AArch64) and GCC. Firecraker/KVM, Xen, Linux platforms and Clang are not yet documented. Signed-off-by: Stefan Jumarea <stefanjumarea02@gmail.com>
unikraft · Jul 1, 2023 · 4f31315 · 4f31315
1 parent e1becef
commit 4f31315
Show file tree

Hide file tree

Showing 8 changed files with 1,139 additions and 31 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+/.config
+/fs0/nginx/logs/
+/build/
+/.unikraft/
diff --git a/Makefile b/Makefile
@@ -0,0 +1,10 @@
+UK_ROOT ?= $(PWD)/.unikraft/unikraft
+UK_LIBS ?= $(PWD)/.unikraft/libs
+LIBS := $(UK_LIBS)/musl:$(UK_LIBS)/lwip:$(UK_LIBS)/python3:$(UK_LIBS)/libuuid
+
+all:
+	@$(MAKE) -C $(UK_ROOT) A=$(PWD) L=$(LIBS)
+
+$(MAKECMDGOALS):
+	@$(MAKE) -C $(UK_ROOT) A=$(PWD) L=$(LIBS) $(MAKECMDGOALS)
+
diff --git a/Makefile.uk b/Makefile.uk
@@ -0,0 +1,2 @@
+$(eval $(call addlib,apppython3))
+
diff --git a/README.md b/README.md
@@ -1,49 +1,305 @@
-# Python 3 on Unikraft
+# Python3 on Unikraft
 
-This application prints "Hello, world!" using python3.
+This application starts a Python3 web application with Unikraft.
+Follow the instructions below to set up, configure, build and run Python3.
 
-To configure, build and run this application you need to have [kraft](https://github.com/unikraft/kraft) installed.
+## Requirements
 
-Configure the application:
-```
-kraft configure
-```
+In order to set up, configure, build and run Python3 on Unikraft, the following packages are required:
 
-Build the application:
-```
-kraft build
-```
+* `build-essential` / `base-devel` / `@development-tools` (the meta-package that includes `make`, `gcc` and other development-related packages)
+* `sudo`
+* `flex`
+* `bison`
+* `git`
+* `wget`
+* `uuid-runtime`
+* `qemu-system-x86`
+* `qemu-kvm`
+* `sgabios`
+* `gcc-aarch64-linux-gnu`
+
+GCC >= 8 is required to build Python3 on Unikraft.
 
-And finally, run the application:
+On Ubuntu/Debian or other `apt`-based distributions, run the following command to install the requirements:
+
+```console
+$ apt-get install -y --no-install-recommends \
+  build-essential \
+  sudo \
+  gcc-aarch64-linux-gnu \
+  libncurses-dev \
+  libyaml-dev \
+  flex \
+  bison \
+  git \
+  wget \
+  uuid-runtime \
+  qemu-kvm \
+  qemu-system-x86 \
+  sgabios
 ```
-kraft run -M 1024 " -- helloworld.py"
+
+## Set Up
+
+The following repositories are required for Python3:
+
+* The application repository (this repository): [`app-python3`](https://github.com/unikraft/app-python3)
+* The Unikraft core repository: [`unikraft`](https://github.com/unikraft/unikraft)
+* Library repositories:
+  * The Python3 "library" repository: [`lib-python3`](https://github.com/unikraft/lib-python3)
+  * The standard C library: [`lib-musl`](https://github.com/unikraft/lib-musl)
+  * The networking stack library: [`lib-lwip`](https://github.com/unikraft/lib-lwip)
+  * The uuid library: [`lib-libuuid`](https://github.com/unikraft/lib-libuuid)
+
+Follow the steps below for the setup:
+
+  1. First clone the [`app-python3` repository](https://github.com/unikraft/app-python3) in the `python3/` directory:
+
+     ```console
+     $ git clone https://github.com/unikraft/app-python3 python3
+     ```
+
+     Enter the `python3/` directory:
+
+     ```console
+     $ cd python3/
+
+     $ ls -F
+     build  config-qemu-aarch64  config-qemu-x86_64  kraft.yaml  Makefile  Makefile.uk  minrootfs.tgz  README.md  run-qemu-aarch64  run-qemu-x86_64
+     ```
+
+  1. While inside the `python3/` directory, create the `fs0/` directory and extract the contents of `minrootfs.tgz`:
+
+     ```console
+     $ mkdir fs0/
+     $ cd fs0/
+     $ tar xvf ../minrootfs.tgz
+     $ cd ..
+     ```
+
+  1. While inside the `python3/` directory, create the `.unikraft/` directory:
+
+     ```console
+     $ mkdir .unikraft
+     ```
+
+     Enter the `.unikraft/` directory:
+
+     ```console
+     $ cd .unikraft/
+     ```
+
+  1. While inside the `.unikraft` directory, clone the [`unikraft` repository](https://github.com/unikraft/unikraft):
+
+     ```console
+     $ git clone https://github.com/unikraft/unikraft unikraft
+     ```
+
+  1. While inside the `.unikraft/` directory, create the `libs/` directory:
+
+     ```console
+     $ mkdir libs
+     ```
+
+  1. While inside the `.unikraft/` directory, clone the library repositories in the `libs/` directory:
+
+     ```console
+     $ git clone https://github.com/unikraft/lib-python3 libs/python3
+
+     $ git clone https://github.com/unikraft/lib-musl libs/musl
+
+     $ git clone https://github.com/unikraft/lib-lwip libs/lwip
+
+     $ git clone https://github.com/unikraft/lib-lwip libs/libuuid
+     ```
+
+  1. Get back to the application directory:
+
+     ```console
+     $ cd ../
+     ```
+
+     Use the `tree` command to inspect the contents of the `.unikraft/` directory.
+     It should print something like this:
+
+     ```console
+     $ tree -F -L 2 .unikraft/
+     .unikraft/
+     |-- libs/
+     |   |-- lwip/
+     |   |-- musl/
+     |   |-- libuuid/
+     |   `-- python3/
+     `-- unikraft/
+         |-- arch/
+         |-- Config.uk
+         |-- CONTRIBUTING.md
+         |-- COPYING.md
+         |-- include/
+         |-- lib/
+         |-- Makefile
+         |-- Makefile.uk
+         |-- plat/
+         |-- README.md
+         |-- support/
+         `-- version.mk
+
+     10 directories, 7 files
+     ```
+
+## Configure
+
+Configuring, building and running a Unikraft application depends on our choice of platform and architecture.
+Currently, supported platforms are QEMU (KVM), Xen and linuxu.
+QEMU (KVM) is known to be working, so we focus on that.
+
+Supported architectures are x86_64 and AArch64.
+
+Use the corresponding the configuration files (`config-...`), according to your choice of platform and architecture.
+
+### QEMU x86_64
+
+Use the `config-qemu-x86_64` configuration file together with `make defconfig` to create the configuration file:
+
+```console
+$ UK_DEFCONFIG=$(pwd)/config-qemu-x86_64 make defconfig
 ```
 
-If you want to have more control, you can configure and run the application manually.
+This results in the creation of the `.config` file:
 
-To configure it with the desired features:
+```console
+$ ls .config
+.config
 ```
-make menuconfig
+
+The `.config` file will be used in the build step.
+
+### QEMU AArch64
+
+Use the `config-qemu-aarch64` configuration file together with `make defconfig` to create the configuration file:
+
+```console
+$ UK_DEFCONFIG=$(pwd)/config-qemu-aarch64 make defconfig
 ```
 
-Build the application:
+Similar to the x86_64 configuration, this results in the creation of the `.config` file that will be used in the build step.
+
+## Build
+
+Building uses as input the `.config` file from above, and results in a unikernel image as output.
+The unikernel output image, together with intermediary build files, are stored in the `build/` directory.
+
+### Clean Up
+
+Before starting a build on a different platform or architecture, you must clean up the build output.
+This may also be required in case of a new configuration.
+
+Cleaning up is done with 3 possible commands:
+
+* `make clean`: cleans all actual build output files (binary files, including the unikernel image)
+* `make properclean`: removes the entire `build/` directory
+* `make distclean`: removes the entire `build/` directory **and** the `.config` file
+
+Typically, you would use `make properclean` to remove all build artifacts, but keep the configuration file.
+
+### QEMU x86_64
+
+Building for QEMU x86_64 assumes you did the QEMU x86_64 configuration step above.
+Build the Unikraft Python3 image for QEMU AArch64 by using the command below:
+
+```console
+$ make -j $(nproc)
+[...]
+  LD      python3_qemu-x86_64.dbg
+  UKBI    python3_qemu-x86_64.dbg.bootinfo
+  SCSTRIP python3_qemu-x86_64
+  GZ      python3_qemu-x86_64.gz
+make[1]: Leaving directory '/media/stefan/projects/unikraft/scripts/workdir/apps/app-python3/.unikraft/unikraft'
 ```
-make
+
+At the end of the build command, the `python3_qemu-x86_64` unikernel image is generated.
+This image is to be used in the run step.
+
+### QEMU AArch64
+
+If you had configured and build a unikernel image for another platform or architecture (such as x86_64) before, then:
+
+1. Do a cleanup step with `make properclean`.
+
+1. Configure for QEMU AAarch64, as shown above.
+
+1. Follow the instructions below to build for QEMU AArch64.
+
+Building for QEMU AArch64 assumes you did the QEMU AArch64 configuration step above.
+Build the Unikraft Python3 image for QEMU AArch64 by using the same command as for x86_64:
+
+```console
+$ make -j $(nproc)
+[...]
+  LD      python3_qemu-arm64.dbg
+  UKBI    python3_qemu-arm64.dbg.bootinfo
+  SCSTRIP python3_qemu-arm64
+  GZ      python3_qemu-arm64.gz
+make[1]: Leaving directory '/media/stefan/projects/unikraft/scripts/workdir/apps/app-python3/.unikraft/unikraft'
 ```
 
-Run the application:
-- Create a sub-directory named `fs0/` in the application directory and extract the contents of `minrootfs.tgz` there.
-- If you built the application for `kvm`:
+Similarly to x86_64, at the end of the build command, the `python3_qemu-arm64` unikernel image is generated.
+This image is to be used in the run step.
+
+## Run
+
+Run the resulting image with the `run-...` scripts.
+
+### QEMU x86_64
+
+To run the QEMU x86_64 build, use `run-qemu-x86_64.sh`:
+
+```console
+$ ./run-qemu-x86_64.sh
+en1: Added
+en1: Interface is up
+Powered by
+o.   .o       _ _               __ _
+Oo   Oo  ___ (_) | __ __  __ _ ' _) :_
+oO   oO ' _ `| | |/ /  _)' _` | |_|  _)
+oOo oOO| | | | |   (| | | (_) |  _) :_
+ OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)
+                  Atlas 0.13.1~5eb820bd
+en1: Set IPv4 address 10.0.2.15 mask 255.255.255.0 gw 10.0.2.2
+Python 3.7.4 (default, Jul  1 2023, 16:22:09) 
+[GCC 9.4.0] on unknown
+Type "help", "copyright", "credits" or "license" for more information.
+>>> print("Hello, World!")
+Hello, World!
+>>>
 ```
-sudo qemu-system-x86_64 \
-	     -fsdev local,id=myid,path=$(pwd)/fs0,security_model=none \
-	     -device virtio-9p-pci,fsdev=myid,mount_tag=fs0,disable-modern=on,disable-legacy=off \
-	     -kernel build/python3_kvm-x86_64 \
-	     -append "-- helloworld.py" \
-	     -enable-kvm \
-	     -m 1G \
-	     -nographic
+
+To close the QEMU Python3 application, use the `Ctrl+a x` keyboard shortcut;
+that is press the `Ctrl` and `a` keys at the same time and then, separately, press the `x` key.
+
+### QEMU AArch64
+
+To run the AArch64 build, use `run-qemu-aarch64.sh`:
+
+```console
+$ ./run-qemu-aarch64.sh
+en1: Added
+en1: Interface is up
+Powered by
+o.   .o       _ _               __ _
+Oo   Oo  ___ (_) | __ __  __ _ ' _) :_
+oO   oO ' _ `| | |/ /  _)' _` | |_|  _)
+oOo oOO| | | | |   (| | | (_) |  _) :_
+ OoOoO ._, ._:_:_,\_._,  .__,_:_, \___)
+                  Atlas 0.13.1~5eb820bd
+en1: Set IPv4 address 10.0.2.15 mask 255.255.255.0 gw 10.0.2.2
+Python 3.7.4 (default, Jul  1 2023, 16:22:09) 
+[GCC 9.4.0] on unknown
+Type "help", "copyright", "credits" or "license" for more information.
+>>> print("Hello, World!")
+Hello, World!
+>>>
 ```
 
-For more information about `kraft` type ```kraft -h``` or read the
-[documentation](http://docs.unikraft.org).
+Similarly, to close the QEMU Python3 server, use the `Ctrl+a x` keyboard shortcut.