[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Minios-devel] [UNIKRAFT PATCH v2] Re-organize advanced user's guide into a single tutrial.



Thanks a lot for your work! As discussed offline, I will remove the unreferenced "doc/guides/users-downloads.rst" file with this commit, too.

Thanks!

Reviewed-by: Simon Kuenzer <simon.kuenzer@xxxxxxxxxxx>

On 02.02.20 11:06, Alexander Jung wrote:
This commit moves the tutorial and getting started pages into
one "unikraft intrinsic" page as there was plenty of overlap.

This commit also fixes a broken user guide with a previously
malformed commit.

Signed-off-by: Alexander Jung <a.jung@xxxxxxxxxxx>
---
  doc/guides/users-advanced.rst       | 322 +++++++++++++++++++++++++---
  doc/guides/users-gettingstarted.rst | 135 ------------
  doc/guides/users-tutorial.rst       | 286 ------------------------
  doc/guides/users.rst                |  17 +-
  4 files changed, 291 insertions(+), 469 deletions(-)
  delete mode 100644 doc/guides/users-gettingstarted.rst
  delete mode 100644 doc/guides/users-tutorial.rst

diff --git a/doc/guides/users-advanced.rst b/doc/guides/users-advanced.rst
index e0dbb54..ec58701 100644
--- a/doc/guides/users-advanced.rst
+++ b/doc/guides/users-advanced.rst
@@ -1,27 +1,41 @@
-===================
+*******************
  Unikraft Intrinsics
-===================
+*******************
The Unikraft build system relies on knowing the search paths or both the
  Unikraft core source code and any additional libraries.   By setting these
  directories, you can create a simple ``Makefile`` which acts as proxy into the
  main build system.
+For this tutorial you will need a Linux host running Xen and/or KVM in
+order to run Unikraft images. Please check the manual of your Linux
+distribution regarding how to install these environments. This
+tutorial expects that you have the essential build and debugging tools
+installed. In addition, for Xen you will need to have the ``xl`` toolstack
+installed and running, and for KVM ``qemu``.
+
  To begin using Unikraft you'll need to have the following dependencies
  installed: ::
apt-get install -y --no-install-recommends build-essential libncurses-dev flex git wget bison unzip -Once these are installed, you can clone the Unikraft main repo: ::
+Optionally, if you want to use the Python front-end to Unikraft's
+menu, please also run ::
- git clone http://github.com/unikraft/unikraft.git
+  apt-get install gtk+-2.0 gmodule-2.0 libglade-2.0
-If you'll be using Unikraft external libraries, this would be the time
-to clone those too.  You can see a list of available libraries on `Github 
<https://github.com/unirkaft>`_
-with the prefix ``lib-``.  You will need to clone each one separately.
+===========================
+Cloning Repositories
+===========================
-We recommend the following directory structure for the Unikraft source code and
-any additional libraries:  ::
+You can easily build Unikraft unikernels on your Linux host. If you
+have all tools and libraries installed to compile a Linux kernel you
+are ready to do this with Unikraft too.
+
+A Unikraft build consists mostly of a combination of multiple
+repositories. We differentiate them into: (1) Unikraft, (2) external
+libraries, (3) application.  The build system assumes these to be
+structured as follows: ::
├── unikraft/
    ├── apps/
@@ -33,6 +47,31 @@ any additional libraries:  ::
       ├── ...
       └── lib-N/
+Once your dependencies have been installed and the directory structure set, you
+can clone the Unikraft main repo: ::
+
+  git clone http://github.com/unikraft/unikraft.git
+
+If you'll be using Unikraft external libraries, this would be the time
+to clone those too.  You can see a list of available libraries on `Github 
<https://github.com/unirkaft>`_
+with the prefix ``lib-``.  You will need to clone each one separately.
+
+* Unikraft base repository directly under your workspace root
+   * `Unikraft repo <https://github.com/unikraft/unikraft.git>`_
+* External libraries into a `libs` subdirectory:
+       * `newlib repo <https://github.com/unikraft/lib-newlib.git>`_
+       * `lwip repo <https://github.com/unikraft/lib-lwip.git>`_
+* Applications into an `apps` subdirectory:
+       * `helloworld repo <https://github.com/unikraft/app-helloworld.git>`_
+       * `httpreply repo <https://github.com/unikraft/app-httpreply.git>`_
+
+===========================
+Your First Unikernel
+===========================
+
+Makefile entrypoint
+-------------------
+
  Once this is in place, you can create a ``Makefile`` inside your application
  directory which uses these locations and uses the special Make target
  ``$(MAKECMDGOALS)`` which returns the target used when calling ``make``: ::
@@ -51,40 +90,51 @@ Now edit the Makefile in your application directory.  In 
particular, set the
  ``UK_ROOT`` and ``UK_LIBS`` variables to point to the directories where you
  cloned the repos above.
-Application structure
----------------------
-
-To get quickly started, the easiest is to clone the hello world app (once 
again,
-each Unikraft app has its own repo): ::
-
-  git clone http://github.com/unikraft/app-helloworld.git
+If your app uses external libraries, set the ``LIBS`` variable to
+reflect this. For instance : ::
-where your app is located at ``apps/helloworld``, you would set
-those variables as follows: ::
-
-  UK_ROOT ?= $(PWD)/../../unikraft
-  UK_LIBS ?= $(PWD)/../../libs
+  LIBS := $(UK_LIBS)/lib1:$(UK_LIBS)/lib2:$(UK_LIBS)/libN
-Finally, if your app will be using external libraries, set the ``LIBS``
-variable to reflect this. For instance : ::
+Finally, if your app uses external platforms, set the ``PLATS``
+variable: ::
- LIBS := $(UK_LIBS)/lib-1:$(UK_LIBS)/lib-2:$(UK_LIBS)/lib-N
+  PLATS ?= $(UK_PLATS)/plat1:$(UK_PLATS)/plat2:$(UK_PLATS)/platN
.. note:: - The list of libraries must be colon-separated (``:``).
+  The list of libraries and platforms must be colon-separated (``:``).
+
+Also make sure that you hand-over these platforms with the
+``P=`` parameter to the sub make call in your main ``Makefile``: ::
+
+  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) fetch
+  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) prepare
+  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS)
With all of this in place, we're now ready to start configuring the
-application image via Unikraft's menu.  To access it, from within the
+application image via Unikraft's menu. To access it, from within the
  app's directory simply type ::
make menuconfig +
+Application configuration
+-------------------------
+
  The menu system is fairly self-explanatory and will be familiar to
  anyone who has configured a Linux kernel before. Select the options
  you want, the libraries you'll like to include and don't forget to
-select at least one platform (e.g., KVM, Xen or Linux user-space --
-the latter is quite useful for quick testing and debugging).
+select at least one platform (e.g., an external one, KVM, Xen, or
+Linux user-space -- the latter is quite useful for quick testing and
+debugging).  Under ``Platform Configuration`` option, you can make the
+following changes:
+
+* select ``Xen guest image``
+* select ``KVM guest``
+* select ``Linux user space``
+
+Under ``Library configuration`` we also need to choose a scheduler:
+select ``ukschedcoop``.
Finally, quit the menu while saving the configuration changes you've
  made and build your application by just typing ``make``. Unikraft will
@@ -92,11 +142,219 @@ then build each library in turn as well as the source 
files for your
  application, producing one image in the ``./build`` directory for each
  platform type you selected.
+-------------------
+Building
+-------------------
+Save your configuration and build the image by typing ``make``. The
+build system will create three binaries, one for each platform: ::
+
+  $ ls -sh build/
+   [...]
+   88K helloworld_kvm-x86_64
+   40K helloworld_linuxu-x86_64
+   72K helloworld_xen-x86_64
+   [...]
+
+----------
+Running
+----------
+
  Running the image will depend on which platform you targeted. For
  Linux user-space, for instance, the image is just a standard ELF, so
-you can simply run it with ::
+you can simply execute on any Linux environment: ::
+
+  $ ./build/helloworld_linuxu-x86_64
+  Welcome to  _ __             _____
+  __ _____  (_) /__ _______ _/ _/ /_
+  / // / _ \/ /  '_// __/ _ `/ _/ __/
+  \_,_/_//_/_/_/\_\/_/  \_,_/_/ \__/
+                    Titan 0.2~10ce3f2
+  Hello world!
+
+You can execute the KVM image (``helloworld_kvm-x86_64``) on the KVM host: ::
+
+  $ qemu-system-x86_64 -nographic -vga none -device sga -m 4 -kernel
+  build/helloworld_kvm-x86_64
+
+For Xen you first need to create a VM configuration (save it under
+``helloworld.cfg``): ::
+
+  name          = 'helloworld'
+  vcpus         = '1'
+  memory        = '4'
+  kernel        = 'build/helloworld_xen-x86_64'
+
+Start the virtual machine with: ::
+
+  $ xl create -c helloworld.cfg
+
+---------------------------------
+Modifying the Application
+---------------------------------
+
+After ``Hello world!`` is printed, the unikernel shuts down right
+away. We do not have a chance to see that a VM was actually created,
+so let's modify the source code. Open ``main.c`` in your favorite
+editor (``nano``, ``vim``, ``emacs``) and add the following busy loop
+inside the ``main`` function:
+
+.. code-block:: c
+               
+   for (;;);
+
+Rebuild the images with ``make`` and execute them. The shell prompt
+should not return. With a second shell you can check that the
+unikernel is still executing:
+
+* Use ``top`` or ``htop`` for Linux and KVM.
+* Use ``xl top`` in Xen.
+
+**Note**: You can terminate the KVM and Linux unikernel with
+ ``CTRL`` + ``C``, and on Xen with ``CTRL`` + ``]``.
+
+
+===========================
+External Libraries
+===========================
+
+The ``helloworld`` application uses a very minimalistic ``libc``
+implementation of libc functionality called ``nolibc`` which is part
+of the Unikraft base, and so it is an "internal" library. Internal
+libraries are located within the ``lib`` directory of Unikraft.
+
+In order to enhance the functionality provided by Unikraft, "external"
+libraries can be added to the build. In the following we want to swap
+``nolibc`` with `newlib <https://github.com/unikraft/lib-newlib>`_, a
+standard libc implementation that you can find in various Linux
+distributions and embedded environments.
+
+We need to add newlib to the library includes. Edit the ``Makefile``
+of the ``helloworld`` application and put the text below in it. Please
+type ``make properclean`` before; this will delete the build directory
+(but not your configuration) and will force a full rebuild later. ::
+
+  diff --git a/Makefile b/Makefile
+  --- a/Makefile
+  +++ b/Makefile
+  @@ -1,6 +1,6 @@
+   UK_ROOT ?= $(PWD)/../../unikraft
+   UK_LIBS ?= $(PWD)/../../libs
+  -LIBS :=
+  +LIBS := $(UK_LIBS)/newlib
+
+   all:
+          @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS)
+
+Run ``make menuconfig``; ``newlib`` should now appear in the ``Library
+Configuration`` menu. Select it, save and exit the menu, and type
+``make``. Unikraft's build system will download newlib's sources and
+build it together with all the other Unikraft libraries and
+application. Our ``newlib`` repository consists only of glue code that
+is needed to port ``newlib`` to Unikraft.
+
+You will notice that the unikernels are now bigger than before. Try to
+run them again.
+
+
+=========================
+Code Your Own Library
+=========================
+Let's add some functionality to our unikernel. Create a directory
+``libs/mylib``, this will be the root folder of your library.
+
+As mentioned earlier, Unikraft uses Linux's kconfig system. In order
+to make your library selectable in the "menuconfig", create the file
+``Config.uk`` with the following content: ::
+
+  config LIBMYLIB
+             bool "mylib: My awesome lib"
+             default n
+
+To test if it worked, we need to tell Unikraft's build system to pick
+this library. Go back to your ``helloworld`` application and edit it
+its ``Makefile``. Earlier we added newlib to the ``LIBS`` variable,
+let's now add the new library: ::
+
+  LIBS := $(UK_LIBS)/newlib:$(UK_LIBS)/mylib
+
+Now if you run ``make menuconfig`` you should see your library under
+the "Library Configuration" sub-menu: ::
+
+  [ ] mylib: My awesome lib
+
+Select it, exit the configuration menu, and save the changes. If you
+run ``make`` right now, the build will produce an error about a
+missing ``Makefile.uk``: ::
+
+  make[1]: *** No rule to make target '/root/demo/libs/mylib/Makefile.uk'.  
Stop.
+
+Go back to your library directory and create one with the following
+content: ::
+
+  # Register your lib to Unikraft's build system
+  $(eval $(call addlib_s,libmylib,$(CONFIG_LIBMYLIB)))
+
+  # Add library source code to compilation
+  LIBMYLIB_SRCS-y += $(LIBMYLIB_BASE)/mylib.c
+
+  # Extend the global include paths with library's folder
+  CINCLUDES-$(CONFIG_LIBMYLIB) += -I$(LIBMYLIB_BASE)/include
+
+And finally the library code ``mylib.c``:
+
+.. code-block:: c
+               
+  #include <stdio.h>
+
+  void libmylib_api_func(void)
+  {
+          printf("Hello from my awesome lib!\n");
+  }
+
+Now in your helloworld's ``main.c`` add a call to
+``libmylib_api_func()``.
+
+
+=========================
+Socket Example
+=========================
+As a last task, we are going to build a small webserver that replies
+with a single page. The server uses ``lwip`` for creating a socket and
+to accept incoming connections. Go to the ``httpreply`` application
+directory. Have a look at ``main.c``: it is a really short program and
+looks similar to what you would write as a user-space Linux
+program. Its dependencies are defined within ``Config.uk``. Having
+this, there is actually not much left to configure. Any mandatory
+options are locked in ``make menuconfig``. All we need to do is select
+our target platforms, select network drivers, save the config, and
+type ``make``.
+
+For now, we support virtio for networking only (but more functionality
+is coming). You can enable the driver by going to the KVM platform
+configuration and selecting ``Virtio PCI device support`` and ``Virtio
+Net device``.
+
+The image can be started on the KVM host. Replace ``br0`` with the
+name of your local bridge on your system and make sure you have a DHCP
+server listening there (e.g., ``dnsmasq``): ::
+
+  $ qemu-system-x86_64 -nographic -vga none -device sga -m 8 -netdev 
bridge,id=en0,br=br0 -device virtio-net-pci,netdev=en0 -kernel 
build/httpreply_kvm-x86_64
+
+Please also ensure that you have built your image with the lwip menu
+option "DHCP client" enabled. This unikernel is requesting an IPv4
+address via DHCP. In case you enabled ``ICMP`` in the ``lwip``
+configuration, you should also be able to ping the host from a second
+terminal (replace the IP with yours): ::
+
+  $ ping 192.168.1.100
+
+For debugging, you can also try to enable ``Debug messages`` in
+``lwip``. With this you can now have a deeper look in the network
+stack.
+
+If networking is working well, you can use the text-based browser
+``lynx`` (or any other that you like) to see the web page served on a
+second terminal (replace the IP with yours): ::
- ./build/helloworld_linuxu-x86_64
+  $ lynx 192.168.1.100:8123
-For more information regarding porting and developing apps (and
-libraries) in Unikraft please read the developer's guide.
diff --git a/doc/guides/users-gettingstarted.rst 
b/doc/guides/users-gettingstarted.rst
deleted file mode 100644
index 44e18c5..0000000
--- a/doc/guides/users-gettingstarted.rst
+++ /dev/null
@@ -1,135 +0,0 @@
-.. _rst_users_getting_started:
-
-************************************
-Getting Started
-************************************
-
-To begin using Unikraft you'll need a few packages. On Ubuntu/Debian
-distributions run the command ::
-
-  apt-get install bison flex build-essential python3 libncurses5-dev 
libncursesw5
-
-Optionally, if you want to use the Python front-end to Unikraft's
-menu, please also run ::
-
-  apt-get install gtk+-2.0 gmodule-2.0 libglade-2.0
-
-With this in place, we are ready to begin cloning Unikraft
-repos. First, start by cloning the main Unikraft repo: ::
-
-  git clone https://github.com/unikraft/unikraft.git
-
-If you are thinking of using Unikraft external libraries, this would
-be the time to clone those too. You can see a list of available
-libraries at (any repo whose name has a ``lib-`` prefix): ::
-
-  https://github.com/unikraft
-
-As you can see, Each external library has its own separate repo, so
-you'll need to clone each one separately. Likewise, if you are
-planning on using any external platforms, please clone those too. You
-can see a list of available external platforms at the same link as for
-the libraries; the platform repos have a ``plat-`` prefix.
-
-Finally, you'll need to create a Unikraft application. To quickly get
-started, the easiest is to clone the hello world app (once again, each
-Unikraft app has its own repo, this time with a ``app-`` prefix): ::
-
-  git clone https://github.com/unikraft/app-helloworld.git
-
-Now edit the Makefile in the app directory. In particular, set the
-``UK_ROOT``, ``UK_LIBS``, and ``UK_PLATS`` variables to point to the
-directories where you cloned the repos above. For instance, assuming
-the following directory structure ::
-
-  ├── unikraft
-  ├── apps
-  │  ├── helloworld
-  │  ├── app1
-  │  ├── app2
-  │  ...
-  │  ├── appN
-  ├── libs
-  │  ├── lib1
-  │  ├── lib2
-  │  ...
-  │  └── libN
-  └── plats
-     ├── plat1
-     ├── plat2
-     ...
-     └── platN
-
-where your app is located at ``apps/helloworld``, you would set
-the variables as follows: ::
-
-  UK_ROOT  ?= $(PWD)/../../unikraft
-  UK_LIBS  ?= $(PWD)/../../libs
-  UK_PLATS ?= $(PWD)/../../plats
-
-If your app uses external libraries, set the ``LIBS`` variable to
-reflect this. For instance : ::
-
-  LIBS := $(UK_LIBS)/lib1:$(UK_LIBS)/lib2:$(UK_LIBS)/libN
-
-Note that the list has to be colon-separated.
-
-Finally, if your app uses external platforms, set the ``PLATS``
-variable: ::
-
-  PLATS ?= $(UK_PLATS)/plat1:$(UK_PLATS)/plat2:$(UK_PLATS)/platN
-
-Also make sure that you hand-over these platforms with the
-``P=`` parameter to the sub make call in your main ``Makefile``: ::
-
-  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) fetch
-  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) prepare
-  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS)
-
-With all of this in place, we're now ready to start configuring the
-application image via Unikraft's menu. To access it, from within the
-app's directory simply type ::
-
-  make menuconfig
-
-The menu system is fairly self-explanatory and will be familiar to
-anyone who has configured a Linux kernel before. Select the options
-you want, the libraries you'll like to include and don't forget to
-select at least one platform (e.g., an external one, KVM, Xen, or
-Linux user-space -- the latter is quite useful for quick testing and
-debugging).
-
-Finally, quit the menu while saving the configuration changes you've
-made and build your application by just typing ``make``. Unikraft will
-then build each library in turn as well as the source files for your
-application, producing one image in the ``./build`` directory for each
-platform type you selected.
-
-Running the image will depend on which platform you targeted. For
-Linux user-space, for instance, the image is just a standard ELF, so
-you can simply run it with ::
-
-  ./build/helloworld_linuxu-x86_64
-
-For KVM, the following QEMU line should do the trick: ::
-
-  qemu-system-x86_64 -cpu host -enable-kvm -m 128 -nodefaults -no-acpi 
-display none -serial stdio -device isa-debug-exit -kernel 
build/helloworld_kvm-x86_64
-
-For Xen, create a ``helloworld.xen`` file as follows::
-
-  kernel = "path_to_build_dir/build/helloworld_xen-x86_64"
-  memory = "8"
-  vcpus = "1"
-  name = "helloworld"
-
-  on_poweroff = "preserve"
-  on_crash = "preserve"
-  on_reboot = "preserve"
-
-and instantiate the Xen virtual machine with: ::
-
-  xl create -c helloworld.xen
-
-That's it! For more information regarding porting and developing
-apps (and libraries and platforms) in Unikraft please read the
-developer's guide.
diff --git a/doc/guides/users-tutorial.rst b/doc/guides/users-tutorial.rst
deleted file mode 100644
index 0a7c615..0000000
--- a/doc/guides/users-tutorial.rst
+++ /dev/null
@@ -1,286 +0,0 @@
-************************************
-Tutorial
-************************************
-
-For this tutorial you will need a Linux host running Xen and/or KVM in
-order to run Unikraft images. Please check the manual of your Linux
-distribution regarding how to install these environments. This
-tutorial expects that you have the essential build and debugging tools
-installed (see :ref:`rst_users_getting_started`). In addition, for
-Xen you will need to have the ``xl`` toolstack installed and running,
-and for KVM ``qemu``
-
-===========================
-Cloning Repositories
-===========================
-You can easily build Unikraft Unikernels on your Linux host. If you
-have all tools and libraries installed to compile a Linux kernel you
-are ready to do this with Unikraft too.
-
-A Unikraft build consists mostly of a combination of multiple
-repositories. We differentiate them into: (1) Unikraft, (2) external
-libraries, (3) application.  The build system assumes these to be
-structured as follows: ::
-
-  my-workspace/
-  ├── apps/
-  │   └── helloworld/
-  │   └── httpreply/
-  ├── libs/
-  │   ├── lwip/
-  │   └── newlib/
-  └── unikraft/
-
-Clone the following repositories with git ::
-
-  git clone [URL] [DESTINATION PATH]
-
-* Unikraft base repository directly under your workspace root
-   * `Unikraft repo <https://github.com/unikraft/unikraft.git>`_
-* External libraries into a `libs` subdirectory:
-       * `newlib repo <https://github.com/unikraft/lib-newlib.git>`_
-       * `lwip repo <https://github.com/unikraft/lib-lwip.git>`_
-* Applications into an `apps` subdirectory:
-       * `helloworld repo <https://github.com/unikraft/app-helloworld.git>`_
-       * `httpreply repo <https://github.com/unikraft/app-httpreply.git>`_
-
-Make sure that the directory structure under your workspace is exactly
-the same as shown in the overview ahead.
-
-===========================
-Your First Unikernel
-===========================
-
--------------------
-Configuring
--------------------
-After you cloned the repos, go to the ``helloworld`` application and
-run ``make menuconfig`` to configure the build. Unikraft uses the same
-configuration system as the Linux kernel (Kconfig). We will build
-Unikraft images for Xen, KVM, and Linux, so the first step is to go to
-the ``Platform Configuration`` option and make the following changes:
-
-* select ``Xen guest image``
-* select ``KVM guest``
-* select ``Linux user space``
-
-Under ``Library configuration`` we also need to choose a scheduler:
-select ``ukschedcoop``.
-
--------------------
-Building
--------------------
-Save your configuration and build the image by typing ``make``. The
-build system will create three binaries, one for each platform: ::
-
-  $ ls -sh build/
-   [...]
-   88K helloworld_kvm-x86_64
-   40K helloworld_linuxu-x86_64
-   72K helloworld_xen-x86_64
-   [...]
-
--------------------
-Running
--------------------
-
-Let's execute the unikernel.
-
-* The easiest is to run the one built as a Linux user space
-  application. It should execute on any Linux environment: ::
-
-   $ ./build/helloworld_linuxu-x86_64
-   Welcome to  _ __             _____
-    __ _____  (_) /__ _______ _/ _/ /_
-   / // / _ \/ /  '_// __/ _ `/ _/ __/
-   \_,_/_//_/_/_/\_\/_/  \_,_/_/ \__/
-                     Titan 0.2~10ce3f2
-   Hello world!
-
-* You can execute the KVM image (``helloworld_kvm-x86_64``) on the KVM
-  host: ::
-
-   $ qemu-system-x86_64 -nographic -vga none -device sga -m 4 -kernel
-   build/helloworld_kvm-x86_64
-
-* For Xen you first need to create a VM configuration (save it under
-  ``helloworld.cfg``): ::
-
-   name          = 'helloworld'
-   vcpus         = '1'
-   memory        = '4'
-   kernel        = 'build/helloworld_xen-x86_64'
-
-Start the virtual machine with: ::
-
-  $ xl create -c helloworld.cfg
-
----------------------------------
-Modifying the Application
----------------------------------
-After ``Hello world!`` is printed, the unikernel shuts down right
-away. We do not have a chance to see that a VM was actually created,
-so let's modify the source code. Open ``main.c`` in your favorite
-editor (``nano``, ``vim``, ``emacs``) and add the following busy loop
-inside the ``main`` function:
-
-.. code-block:: c
-               
-   for (;;);
-
-Rebuild the images with ``make`` and execute them. The shell prompt
-should not return. With a second shell you can check that the
-unikernel is still executing:
-
-* Use ``top`` or ``htop`` for Linux and KVM.
-* Use ``xl top`` in Xen.
-
-**Note**: You can terminate the KVM and Linux unikernel with
- ``CTRL`` + ``C``, and on Xen with ``CTRL`` + ``]``.
-
-
-===========================
-External Libraries
-===========================
-
-The ``helloworld`` application uses a very minimalistic ``libc``
-implementation of libc functionality called ``nolibc`` which is part
-of the Unikraft base, and so it is an "internal" library. Internal
-libraries are located within the ``lib`` directory of Unikraft.
-
-In order to enhance the functionality provided by Unikraft, "external"
-libraries can be added to the build. In the following we want to swap
-``nolibc`` with `newlib <https://github.com/unikraft/lib-newlib>`_, a
-standard libc implementation that you can find in various Linux
-distributions and embedded environments.
-
-We need to add newlib to the library includes. Edit the ``Makefile``
-of the ``helloworld`` application and put the text below in it. Please
-type ``make properclean`` before; this will delete the build directory
-(but not your configuration) and will force a full rebuild later. ::
-
-  diff --git a/Makefile b/Makefile
-  --- a/Makefile
-  +++ b/Makefile
-  @@ -1,6 +1,6 @@
-   UK_ROOT ?= $(PWD)/../../unikraft
-   UK_LIBS ?= $(PWD)/../../libs
-  -LIBS :=
-  +LIBS := $(UK_LIBS)/newlib
-
-   all:
-          @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS)
-
-Run ``make menuconfig``; ``newlib`` should now appear in the ``Library
-Configuration`` menu. Select it, save and exit the menu, and type
-``make``. Unikraft's build system will download newlib's sources and
-build it together with all the other Unikraft libraries and
-application. Our ``newlib`` repository consists only of glue code that
-is needed to port ``newlib`` to Unikraft.
-
-You will notice that the unikernels are now bigger than before. Try to
-run them again.
-
-
-=========================
-Code Your Own Library
-=========================
-Let's add some functionality to our unikernel. Create a directory
-``libs/mylib``, this will be the root folder of your library.
-
-As mentioned earlier, Unikraft uses Linux's kconfig system. In order
-to make your library selectable in the "menuconfig", create the file
-``Config.uk`` with the following content: ::
-
-  config LIBMYLIB
-             bool "mylib: My awesome lib"
-             default n
-
-To test if it worked, we need to tell Unikraft's build system to pick
-this library. Go back to your ``helloworld`` application and edit it
-its ``Makefile``. Earlier we added newlib to the ``LIBS`` variable,
-let's now add the new library: ::
-
-  LIBS := $(UK_LIBS)/newlib:$(UK_LIBS)/mylib
-
-Now if you run ``make menuconfig`` you should see your library under
-the "Library Configuration" sub-menu: ::
-
-  [ ] mylib: My awesome lib
-
-Select it, exit the configuration menu, and save the changes. If you
-run ``make`` right now, the build will produce an error about a
-missing ``Makefile.uk``: ::
-
-  make[1]: *** No rule to make target '/root/demo/libs/mylib/Makefile.uk'.  
Stop.
-
-Go back to your library directory and create one with the following
-content: ::
-
-  # Register your lib to Unikraft's build system
-  $(eval $(call addlib_s,libmylib,$(CONFIG_LIBMYLIB)))
-
-  # Add library source code to compilation
-  LIBMYLIB_SRCS-y += $(LIBMYLIB_BASE)/mylib.c
-
-  # Extend the global include paths with library's folder
-  CINCLUDES-$(CONFIG_LIBMYLIB) += -I$(LIBMYLIB_BASE)/include
-
-And finally the library code ``mylib.c``:
-
-.. code-block:: c
-               
-  #include <stdio.h>
-
-  void libmylib_api_func(void)
-  {
-          printf("Hello from my awesome lib!\n");
-  }
-
-Now in your helloworld's ``main.c`` add a call to
-``libmylib_api_func()``.
-
-
-=========================
-Socket Example
-=========================
-As a last task, we are going to build a small webserver that replies
-with a single page. The server uses ``lwip`` for creating a socket and
-to accept incoming connections. Go to the ``httpreply`` application
-directory. Have a look at ``main.c``: it is a really short program and
-looks similar to what you would write as a user-space Linux
-program. Its dependencies are defined within ``Config.uk``. Having
-this, there is actually not much left to configure. Any mandatory
-options are locked in ``make menuconfig``. All we need to do is select
-our target platforms, select network drivers, save the config, and
-type ``make``.
-
-For now, we support virtio for networking only (but more functionality
-is coming). You can enable the driver by going to the KVM platform
-configuration and selecting ``Virtio PCI device support`` and ``Virtio
-Net device``.
-
-The image can be started on the KVM host. Replace ``br0`` with the
-name of your local bridge on your system and make sure you have a DHCP
-server listening there (e.g., ``dnsmasq``): ::
-
-  $ qemu-system-x86_64 -nographic -vga none -device sga -m 8 -netdev 
bridge,id=en0,br=br0 -device virtio-net-pci,netdev=en0 -kernel 
build/httpreply_kvm-x86_64
-
-Please also ensure that you have built your image with the lwip menu
-option "DHCP client" enabled. This unikernel is requesting an IPv4
-address via DHCP. In case you enabled ``ICMP`` in the ``lwip``
-configuration, you should also be able to ping the host from a second
-terminal (replace the IP with yours): ::
-
-  $ ping 192.168.1.100
-
-For debugging, you can also try to enable ``Debug messages`` in
-``lwip``. With this you can now have a deeper look in the network
-stack.
-
-If networking is working well, you can use the text-based browser
-``lynx`` (or any other that you like) to see the web page served on a
-second terminal (replace the IP with yours): ::
-
-  $ lynx 192.168.1.100:8123
-
diff --git a/doc/guides/users.rst b/doc/guides/users.rst
index f95ad72..1e4e574 100644
--- a/doc/guides/users.rst
+++ b/doc/guides/users.rst
@@ -1,20 +1,5 @@
  ============
  User's Guide
-<<<<<<< Updated upstream
-####################
-This section of the guide provides all the information you should need
-to  get started  with and  to  use Unikraft.  If you  have never  used
-Unikraft  before, read  the getting  started page  and optionally  run
-through the tutorials.
-
-.. toctree::
-   :maxdepth: 2
-
-   users-gettingstarted
-   users-tutorial
-   users-downloads
-   users-resources
-=======
  ============
Unikraft is an extensive build system in addition to the core and external
@@ -29,4 +14,4 @@ how to use these leverage this functionality for advanced 
usage.
kraft
     users-advanced
->>>>>>> Stashed changes
+   users-resources


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

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.