-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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>
- Loading branch information
Showing
8 changed files
with
1,139 additions
and
31 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
/.config | ||
/fs0/nginx/logs/ | ||
/build/ | ||
/.unikraft/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
$(eval $(call addlib,apppython3)) | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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-libuuid 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. |
Oops, something went wrong.