From 9c3721e7ac1b7791e7c605dc90cb1a0c7da33f39 Mon Sep 17 00:00:00 2001 From: Vlad-Andrei Badoiu Date: Wed, 16 Oct 2019 17:22:45 +0300 Subject: [PATCH] README.md: Update with info about building and running Signed-off-by: Vlad-Andrei Badoiu Signed-off-by: Costin Lupu Reviewed-by: Felipe Huici --- README.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c9544d1..da65388 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,129 @@ -python3 for Unikraft -============================= - +# python3 for Unikraft This is the port of python3 for Unikraft as external library. -Please refer to the `README.md` as well as the documentation in the `doc/` -subdirectory of the main unikraft repository. +## Build +Python 3 interpreter depends on the following libraries, that need to +be added to `Makefile` in this order: + +* `pthreads`, e.g. `pthread-embedded` +* `libc`, e.g. `newlib` +* network stack, e.g. `lwip` +* (optional) a SIMD library, e.g. `intel-intrinsics`, for optimized + BLAKE hashing +* optional extensions: `openssl`, `zlib`, `libuuid`, Expat XML parser, + `_ctypes` and decimal operations with `libmpdec`. + +## Root filesystem +### Creating the filesystem +Python 3 interpreter needs a filesystem which should contain its +standard library. Therefore, the filesystem needs to be created before +running the VM. You can do this by running the following command: + +```bash +make python-rootfs path= +``` + +It will create the filesystem in the directory you choose, by first +creating a virtual Python environment. After that it will install the +Python standard library into it. For this second step, the original +code needs to be configured and build with paths relative to the +provided root directory. These two steps are executed transparently, +all you have to do is just running the above `make` command. + +### Using the filesystem +Mounting the filesystem is a transparent operation. All you have to do +is to provide the right Qemu parameters in order for Unikraft to mount +the filesystem. We will use the 9pfs support for filesystems and for +this you will need to use the following parameters: + +```bash +-fsdev local,id=myid,path=,security_model=none \ +-device virtio-9p-pci,fsdev=myid,mount_tag=test,disable-modern=on,disable-legacy=off +``` + +You should also use `vfs.rootdev=test` to specify the 9pfs mounting +tag to Unikraft. To enable 9pfs, you'll need to select the following +menu options, all under "Library Configuration" + +* uk9p: 9p client + +* vfscore: VFS Core Interface ---> vfscore: Configuration + ---> Automatically mount a root filesysytem + ---> Default root filesystem + ---> 9PFS + +* devfs: devfs file system ---> Mount /dev during boot + +* uk library parameter + +## Running modes +The Next step is to pick a running mode. We currently support 3 running +modes: + +1. **Python shell**. No extra parameters are needed. + * You can use the `main()` function provided by the library via + `menuconfig`: + + Library Configuration ---> Python 3 ---> Provide main function + + Otherwise you will have to provide your own `main()` function + which should call `_Py_UnixMain()`. + +2. **Python script**. You can use any file available in the root + filesystem. You should use Qemu's `-append` option to pass + parameter to Python interpreter, e.g. `-append "vfs.rootdev=test -- + "`. Please notice that we are using `test` + for the 9pfs mounting tag. For brevity we will skip setting the + mounting tag in the next examples. + +3. **Python unit testing (developers only)**. With this mode you can + check what functionality is completely supported by the Python 3 + port. Please be aware that this mode is unstable and some of the + tests may block. You can work around that by using the options + provided by the unit testing framework. The unit testing mode + itself supports several submodes: + + * **Running all the tests**. You have to use the following Qemu + parameters: `-append "-- -B -c 'from test import autotest'"` + + * Check the supported options of the unit testing framework, + e.g. `-append "-- -B -c 'from test import autotest' -h"`. + + * For example, you can run a single unit test with verbosity + using `-append "-- -B -c 'from test import autotest' -v + test_dict"`. + + * Or you can run a set of tests listed in a file using `-append + "-- -B -c 'from test import autotest' -f "`. + + +### Memory usage +Some of the unit tests may require a lot of memory to run; for this +reason please allow for at least 1G of memory for unit testing (e.g., +`-m 1G` in Qemu). + +## Adding modules +For installing Python modules which have only Python code, you can use +the `pip` utility installed in the Python virtual environment you +created using the steps above. + +```bash + $ . bin/activate + $ pip install mymodule +``` + +However, some of the Python modules need some native support, +e.g. some C code which should be compiled and registered at run +time. You need to add the source files of the native library to +`Makefile.uk.` for compiling them. For runtime registration, you need +to add a new entry in the `modules_config.c` file. + +Note that this port already supports a few such modules: `openssl`, +`zlib` and `libuuid` as of this writing. To enable them select them in +the menu under: + +Library Configuration ---> Python 3 ---> Extensions + +## Further information +Please refer to the `README.md` as well as the documentation in the +`doc/` subdirectory of the main unikraft repository. -- 2.39.5