[Minios-devel] [UNIKRAFT PATCH] doc: Update kraft documentation with new flags and tutorials.

[Alexander Jung <a.jung@xxxxxxxxxxx>]

Signed-off-by: Alexander Jung <a.jung@xxxxxxxxxxx>
---
 doc/guides/kraft.rst | 71 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 63 insertions(+), 8 deletions(-)

diff --git a/doc/guides/kraft.rst b/doc/guides/kraft.rst
index b6c2696..6087e7c 100644
--- a/doc/guides/kraft.rst
+++ b/doc/guides/kraft.rst
@@ -176,6 +176,7 @@ Quick Unikraft project creation
     -P, --paused                   Run the application in paused state.
     -g, --gdb INTEGER              Run a GDB server for the guest on specified
                                    port.
+    -d, --dbg                      Use unstriped unikernel.
     -n, --virtio-nic TEXT          Attach a NAT-ed virtio-NIC to the guest.
     -b, --bridge TEXT              Attach a NAT-ed virtio-NIC an existing
                                    bridge.
@@ -228,6 +229,7 @@ Configuring a Unikraft application
   Options:
     -p, --plat [linuxu|kvm|xen]    Target platform.
     -m, --arch [x86_64|arm|arm64]  Target architecture.
+    -F, --force                    Force writing new configuration.
     -k, --menuconfig               Use Unikraft's ncurses Kconfig editor.
     -h, --help                     Show this message and exit.
 
@@ -263,6 +265,7 @@ Running a Unikraft application
     -X, --background               Run in background.
     -P, --paused                   Run the application in paused state.
     -g, --gdb INTEGER              Run a GDB server for the guest at PORT.
+    -d, --dbg                      Use unstriped unikernel.
     -n, --virtio-nic TEXT          Attach a NAT-ed virtio-NIC to the guest.
     -b, --bridge TEXT              Attach a NAT-ed virtio-NIC an existing
                                    bridge.
@@ -272,13 +275,6 @@ Running a Unikraft application
     -M, --memory INTEGER           Assign MB memory to the guest.
     -s, --cpu-sockets INTEGER      Number of guest CPU sockets.
     -c, --cpu-cores INTEGER        Number of guest cores per socket.
-    --with-dnsmasq                 Start a Dnsmasq server.
-    --ip-range TEXT                Set the IP range for Dnsmasq.  [default:
-                                   172.88.0.1,172.88.0.254]
-    --ip-netmask TEXT              Set the netmask for Dnsmasq.  [default:
-                                   255.255.0.0]
-    --ip-lease-time TEXT           Set the IP lease time for Dnsmasq.  
[default:
-                                   12h]
     -h, --help                     Show this message and exit.
 
 .. _advanced_usage:
@@ -312,4 +308,63 @@ core source code and all library pools.  This is set using 
the following:
 | ``UK_APPS``            | ``$UK_WORKDIR/apps``     | Applications and 
templates.               |
 
+------------------------+--------------------------+-------------------------------------------+
 | ``KRAFTCONF``          | ``~/.kraftrc``           | The location of kraft's 
preferences file. |
-+------------------------+--------------------------+-------------------------------------------+
\ No newline at end of file
++------------------------+--------------------------+-------------------------------------------+
+
+Workflow when working on Unikraft internals 
+-------------------------------------------
+
+During phases of development which require modifying the Unikraft core source
+code or an auxiliary library for the target application, ``kraft``'s runtime
+can be altered to facilitate varying developer requirements.
+
+In the following example, both the Unikraft core source code and an additional
+library, ``mylib``, have are utilized for an application.   However, their
+source has been modified and point to external locations.  This is useful if 
you
+are doing local development or wish to work with private repositories:
+
+::
+
+  specification: '0.4'
+
+  unikraft: file:///home/developer/repos/unikraft/unikraft@3a8150d
+
+  libraries:
+    mylib:
+      version: devel/new-feature
+      source: git://git.example.com/lib-mylib
+
+
+The ``kraft`` tool works with these remote and local Git repositories in order
+to handle version control.  However, wen using the ``kraft`` tool itself in
+during the ``configure`` and ``build`` steps, it is handy to stop it it from
+automatically running ``git checkout`` on these repositories.  This is
+particularly useful when the source tree of the Unikraft core or any other
+library has a dirty working tree.
+
+To ignore warnings and proceed with a command, use the global flag ``-C``:
+
+::
+
+  kraft -Cv configure
+
+To prevent ``kraft`` from checking out repositories entirely, use the global
+flag ``-X``:
+
+::
+
+  kraft -Xv build
+
+Debugging Unikraft applications
+-------------------------------
+
+Running and debugging unikernels can be accomplished largely with the use of
+`gdb <https://www.gnu.org/software/gdb/>`_.  Unikraft will build an un-stripped
+binary with debugging features enabled.  This can be toggled with the
+``-d|--dbg`` flag on ``kraft run``.  To start gdb itself, include the
+``-g|--gdb PORT`` flag during the same run stage.  Additionally, it is often
+useful to start the guest in a paused stage, accomplished with the
+``-P|--paused`` flag:
+
+::
+
+  kraft run -p kvm --gdb 4123 --dbg
\ No newline at end of file
-- 
2.24.1


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