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

[Felipe Huici <Felipe.Huici@xxxxxxxxx>]

Hi Costin, Vlad, this looks ok, thanks.

Reviewed-by: Felipe Huici <felipe.huici@xxxxxxxxx>

On 16.10.19, 16:23, "Costin Lupu" <costin.lupu@xxxxxxxxx> wrote:

    Signed-off-by: Vlad-Andrei Badoiu <vlad_andrei.badoiu@xxxxxxxxxxxxxxx>
    Signed-off-by: Costin Lupu <costin.lupu@xxxxxxxxx>
    ---
     README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
     1 file changed, 85 insertions(+), 3 deletions(-)
    
    diff --git a/README.md b/README.md
    index c9544d1..1eae7b6 100644
    --- a/README.md
    +++ b/README.md
    @@ -1,7 +1,89 @@
    -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`
    +* (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=<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
    +```
    +
    +You should also use `vfs.rootdev=test` to specify the 9pfs mounting tag to
    +Unikraft. Please make sure you have 9pfs support enabled via `menuconfig`.
    +
    +## Running modes
    +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`. 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 -- -f <some file in 
rootfs>"`.
    +   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 does support 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 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>"`.
    +
    +### Memory usage
    +Some of the unit tests may require a lot of memory during their running. 
For
    +this reason it is safe to use at least 1G of memory for unit testing.
    +
    +## 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
    +<my-python-rootfs> $ . bin/activate
    +<my-python-rootfs> $ 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. 
You
    +can use as examples the `openssl`, `zlib` or `libuuid` extensions.
    +
    +## 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