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
