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

[Felipe Huici <Felipe.Huici@xxxxxxxxx>]

Hi Costin, Vlad,

There are a couple of things that can be improved in terms of 
documentation/README.md:

* Being more explicit about exactly which menu options are needed to have 9pfs 
actually working -- this is far from obvious.
* Ditto for extensions. Although this is certainly easier to sort out, we might 
as well make it explicit.

As part of the review process I've already done all the necessary edits to the 
file. If you agree, I can add these on upstreaming, so I'll give this patch a 
reviewed-by as is.

-- Felipe

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

On 13.10.19, 17:28, "Costin Lupu" <costin.lupu@xxxxxxxxx> wrote:

    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 | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
     1 file changed, 84 insertions(+), 3 deletions(-)
    
    diff --git a/README.md b/README.md
    index c9544d1..16196d1 100644
    --- a/README.md
    +++ b/README.md
    @@ -1,7 +1,88 @@
    -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`, 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