[Minios-devel] [UNIKRAFT/PYTHON3 PATCH v3 14/14] README.md: Update with info about building and running

[Costin Lupu <costin.lupu@xxxxxxxxx>]

From: Vlad-Andrei Badoiu <vlad_andrei.badoiu@xxxxxxxxxxxxxxx>

Signed-off-by: Vlad-Andrei Badoiu <vlad_andrei.badoiu@xxxxxxxxxxxxxxx>
Signed-off-by: Costin Lupu <costin.lupu@xxxxxxxxx>
---
 README.md | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index c9544d1..d2b4868 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,43 @@
-python3 for Unikraft
-=============================
-
+# python3 for Unikraft
 This is the port of python3 for Unikraft as external library.
 
+## 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`
+* a SIMD library, e.g. `intel-intrinsics`
+* optional extensions: `openssl`, `zlib`, `libuuid`, etc
+
+## 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=<some directory>
+```
+
+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=<some directory>,security_model=none \
+-device 
virtio-9p-pci,fsdev=myid,mount_tag=test,disable-modern=on,disable-legacy=off
+```
+
+## Running modes
+Next step is to pick a running mode. We currently support 3 running modes:
+
+1. **Python shell**. No extra parameters are needed
+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 "-f <some file in rootfs>"`
+3. **Python unit testing**. With this mode you can check what functionality is 
completely supported by the Python 3 port. The unit testing mode itself does 
support several modes:
+    * **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 test script, e.g. `-append "-B -c 
'from test import autotest' -h`.
+       * For example, you can run only one unit test with verbosity using 
`-append "-B -c 'from test import autotest' -v test_dict"`.
+       * Or you can run only the tests listed in a file using `-append "-B -c 
'from test import autotest' -f <file in rootfs>"`.
+
+## Further information
 Please refer to the `README.md` as well as the documentation in the `doc/`
 subdirectory of the main unikraft repository.
-- 
2.20.1


_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel