We update all pages of the documentationa and include additional
content such as a tutorial and links to Unikraft resources. This is
part of an effort to consolidate all such information, which is now
spread across a set of sites, in a single location: this guide, which
should be available at docs.unikraft.org .
Signed-off-by: Felipe Huici <felipe.huici@xxxxxxxxx>
---
README.md | 16 +-
doc/guides/_static | 0
doc/guides/conf.py | 6 +-
doc/guides/contribute.rst | 16 +-
doc/guides/developers-app.rst | 8 +-
doc/guides/developers-debugging.rst | 75 ++++---
doc/guides/developers-external-plat.rst | 4 +-
doc/guides/intro.rst | 14 +-
doc/guides/users-downloads.rst | 5 +
doc/guides/users-gettingstarted.rst | 135 +++++++++++
doc/guides/users-resources.rst | 8 +
doc/guides/users-tutorial.rst | 286 ++++++++++++++++++++++++
doc/guides/users.rst | 112 +---------
13 files changed, 525 insertions(+), 160 deletions(-)
create mode 100644 doc/guides/_static
create mode 100644 doc/guides/users-downloads.rst
create mode 100644 doc/guides/users-gettingstarted.rst
create mode 100644 doc/guides/users-resources.rst
create mode 100644 doc/guides/users-tutorial.rst
diff --git a/README.md b/README.md
index 328f001f..4459bcae 100644
--- a/README.md
+++ b/README.md
@@ -31,21 +31,21 @@ time-consuming, expert work that is required today to build
such
images.
For more information information about Unikraft, including user and
-developer guides, please refer to the `docs/guides` directory.
+developer guides, please refer to the `docs/guides` directory or point
+your browser to the Unikraft
+[documentation](http://docs.unikraft.org/)
-Open Projects
+Contributing
-----------------
If you're interested in contributing please take a look at the list of
[open projects](https://github.com/unikraft/unikraft/issues). If one
-of these interests you please drop us a line via the mailing list (see
-below).
+of these interests you please drop us a line via the mailing list or
+directly at unikraft@xxxxxxxxxxxxxxxxxx .
Further Resources
-----------------
-* [Sources at
Xenbits](http://xenbits.xen.org/gitweb/?a=project_list;pf=unikraft)
-* [Project Wiki](https://wiki.xenproject.org/wiki/Category:Unikraft)
-* [Unikraft Team](https://www.xenproject.org/developers/teams/unikraft.html)
+* [Unikraft Core
Team](https://www.xenproject.org/developers/teams/unikraft.html)
* [Mailing List
Archive](https://lists.xenproject.org/archives/html/minios-devel)
* [Mailing List
Subscription](mailto:minios-devel-request@xxxxxxxxxxxxxxxxxxxx)
-* [Research Project at NEC Labs
Europe](http://sysml.neclab.eu/projects/unikraft/)
+* [Patchwork](https://patchwork.unikraft.org/project/unikraft/list/)
diff --git a/doc/guides/_static b/doc/guides/_static
new file mode 100644
index 00000000..e69de29b
diff --git a/doc/guides/conf.py b/doc/guides/conf.py
index 5f7259e8..55eeb7be 100644
--- a/doc/guides/conf.py
+++ b/doc/guides/conf.py
@@ -49,8 +49,8 @@ master_doc = 'index'
# General information about the project.
project = u'Unikraft'
-copyright = u'2017, NEC Europe Ltd.'
-author = u'Simon Kuenzer, Felipe Huici, Florian Schmidt'
+copyright = u'2019, NEC Laboratories Europe GmbH'
+author = u'Simon Kuenzer, Felipe Huici'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -226,7 +226,7 @@ latex_elements = {
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Unikraft.tex', u'Unikraft Documentation',
- u'Simon Kuenzer, Felipe Huici, Florian Schmidt', 'manual'),
+ u'Simon Kuenzer, Felipe Huici', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
diff --git a/doc/guides/contribute.rst b/doc/guides/contribute.rst
index 10aefd1f..62e160d5 100644
--- a/doc/guides/contribute.rst
+++ b/doc/guides/contribute.rst
@@ -1,10 +1,14 @@
****************************
Contribute to Unikraft
****************************
+If you would like to contribute code to Unikraft, the very first
+starting point is the project's ``CONTRIBUTING.md``, which contains
+information about how (and where) to submit patches and how the review
+process works. Please also refer to the ``MAINTAINERS.md`` file.
-If you would like to get ideas regarding possible contributions to Unikraft,
-we (normally) keep an up-to-date list on the project's wiki (see
-``README.md`` for the URL). Please browse through it and don't
-hesitate to contact us regarding any questions you may have.
-Also have a look to the project's ``CONTRIBUTING.md`` and ``MAINTAINERS.md``
-file.
+If you are looking for ideas regarding possible contributions to
+Unikraft, we (normally) keep an up-to-date list of open projects,
+enhancements and bugs on the project's github main repo:
+https://github.com/unikraft/unikraft/issues . Please browse through
+it and don't hesitate to contact us regarding any questions you may
+have at unikraft@xxxxxxxxxxxxxxxxxx .
diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
index c9e4a6eb..d288bb61 100644
--- a/doc/guides/developers-app.rst
+++ b/doc/guides/developers-app.rst
@@ -1,6 +1,6 @@
-****************************
+************************************
Application Development and Porting
-****************************
+************************************
Porting an application to Unikraft should be for the most part
relatively painless given that the available Unikraft libraries
provide all of the application's dependencies. In most cases, the
@@ -400,7 +400,7 @@ charp C strings.
======== ========================
Register a library parameter with Unikraft
------------------------------------------
+--------------------------------------------
In order for a library to configure options at execution time, it needs
to select the `uklibparam` library while configuring the Unikraft build.
The library should also be registered with the `uklibparam` library using
@@ -459,7 +459,7 @@ helper function:
.. code-block:: c
- static const char \*test_string = "Hello World";
+ static const char *test_string = "Hello World";
UK_LIB_PARAM_STR(test_string);
We can override the default value using the following command:
diff --git a/doc/guides/developers-debugging.rst
b/doc/guides/developers-debugging.rst
index ae5a447e..49207397 100644
--- a/doc/guides/developers-debugging.rst
+++ b/doc/guides/developers-debugging.rst
@@ -55,11 +55,26 @@ in a paused state (`-S` parameter): ::
qemu-system-x86_64 -s -S -cpu host -enable-kvm -m 128 -nodefaults -no-acpi -display none -serial stdio -device isa-debug-exit -kernel build/helloworld_kvm-x86_64 -append verbose
-and connect gdb by using the debug image with: ::
+Note that the `-s` parameter is shorthand for `-gdb tcp::1234`. Now
+connect gdb by using the debug image with: ::
gdb --eval-command="target remote :1234" build/helloworld_kvm-x86_64.dbg
-You can initiate qemu to start the guest's execution by typing `c` within gdb.
+Unless you're debugging early boot code (until ``_libkvmplat_start32``),
you'll need to set a hardware break point: ::
+
+ hbreak [location]
+ run
+
+We'll now need to set the right CPU architecture: ::
+
+ disconnect
+ set arch i386:x86-64:intel
+
+And reconnect: ::
+
+ tar remote localhost:1234
+
+You can now run ``continue`` and debug as you would normally.
For Xen the process is slightly more complicated and depends on Xen's
gdbsx tool. First you'll need to make sure you have the tool on your
@@ -91,8 +106,8 @@ Trace points
----------------------------
Dependencies
----------------------------
-The ``support/scripts/uk_trace/trace.py`` depends on python modules
-click and tabulate. You can install them by running: ::
+The file ``support/scripts/uk_trace/trace.py`` depends on the click
+and tabulate Python modules; you can install them by running: ::
sudo apt-get install python3-click python3-tabulate
@@ -106,29 +121,29 @@ Or, you can install trace.py into a local virtual environment: ::
deactivate
cd -
-All the dependencies will be installed in the 'env' folder, not to
+All the dependencies will be installed in the 'env' folder, not
your machine. You do not have to enter your virtual environment, you
can call the installed script directly: ::
env/bin/uk-trace --help
-Because of ``--editable`` flag, any modifications made to
+Because of the ``--editable`` flag, any modifications made to
``support/scripts/uk_trace/trace.py`` will be reflected in the
installed file.
----------------------------
-Reading tracepoints
+Reading Tracepoints
----------------------------
Tracepoints are provided by ``libukdebug``. To make Unikraft collect
-tracing data enable the option ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` in your
+tracing data, enable the option ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` in your
config (via ``make menuconfig``).
Because tracepoints can noticeably affect performance, selective
-enabling is implemented. Option ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` just
-enables the functionality, but all the tracepoints are compiled into
-nothing by default (have no effect). If you would like one library to
-collect tracing data, add to it's Makefile.uk
+enabling is implemented. The ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` option
+just enables the functionality, but all the tracepoints are compiled
+into nothing by default (i.e., they have no effect). If you would like
+a library to collect tracing data, add the following to its Makefile.uk: ::
.. code-block:: make
@@ -140,40 +155,40 @@ If you need just the information about tracepoints in one file, define
If you wish to enable **ALL** existing tracepoints, enable
``CONFIG_LIBUKDEBUG_ALL_TRACEPOINTS`` in menuconfig.
-When tracing is enabled, unikraft will write samples into internal
-trace buffer. Currently it is not a circular buffer, as soon as it
-overflows, unikraft will stop collecting data.
+When tracing is enabled, Unikraft will write samples into an internal
+trace buffer. Currently this is not a circular buffer, so as soon as
+it overflows, Unikraft will stop collecting data.
To read the collected data you have 2 options:
-1. Inside gdb
+1. Use gdb
-2. Using trace.py
+2. Use trace.py
For the first option, you need the 'uk-gdb.py' helper loaded into the
-gdb session. To make this happen all you need to do is to add the
+gdb session. To make this happen all you need to do is add the
following line into ~/.gdbinit: ::
add-auto-load-safe-path /path/to/your/build/directory
-With this, gdb will load helper automatically, each time you start gdb
-with a *.dbg image. For example ::
+With this, gdb will load the helper automatically each time you start gdb
+with a \*.dbg image. For example ::
gdb helloworld/build/helloworld_kvm-x86_64.dbg
-Now you can print tracing log by issuing command ``uk
+Now you can print the tracing log by issuing the command ``uk
trace``. Alternatively, you can save all trace data into a binary file
with ``uk trace save <filename>``. This tracefile can be processed
later offline using the trace.py script: ::
support/scripts/uk_trace/trace.py list <filename>
-Which brings us to the second option. Trace.py can run gdb and fetch
+Which brings us to the second option: trace.py can run gdb and fetch
the tracefile for you. Just run: ::
support/scripts/uk_trace/trace.py fetch <your_unikraft_image>.dbg
-.. note:: The *.dbg image is required, as it have offline data needed
+.. note:: The \*.dbg image is required, as it have offline data needed
for parsing the trace buffer.
----------------------------
@@ -193,13 +208,13 @@ Bellow is a snippet for using tracepoints:
return 0;
}
-Macro ``UK_TRACEPOINT(trace_name, fmt, type1, type2, ... typeN)``
-generates a static function `trace_name()`, accepting N parameters, of
-types **type1**, **type2** and so on. Up to 7 parameters supported. The
+The macro ``UK_TRACEPOINT(trace_name, fmt, type1, type2, ... typeN)``
+generates a static function `trace_name()`, accepting N parameters of
+types **type1**, **type2** and so on. Up to 7 parameters are supported. The
**fmt** is a printf-style format which will be used to form a message
corresponding to the trace sample.
-The **fmt** is static and stored offline. Only parameters values are
+The **fmt** is static and stored offline. Only parameter values are
saved on the trace buffer. It is the job of the offline parser to
match them together and print out resulting messages.
@@ -210,13 +225,13 @@ place in your code.
----------------------------
Troubleshooting
----------------------------
-If you are getting a message::
+If you are getting the message::
Error getting the trace buffer. Is tracing enabled?
This might be because:
-1. Because you indeed need to enable tracing
+1. You indeed need to enable tracing.
2. Not a single tracepoint has been called, and dead-code elimination
- removed (rightfully) the tracing functionality
+ removed (rightfully) the tracing functionality.
diff --git a/doc/guides/developers-external-plat.rst
b/doc/guides/developers-external-plat.rst
index 7021ab28..ac4f5368 100644
--- a/doc/guides/developers-external-plat.rst
+++ b/doc/guides/developers-external-plat.rst
@@ -1,6 +1,6 @@
-****************************
+******************************
External Platform Development
-****************************
+******************************
External platform development is exactly like developing an internal
platform, so please refer to that section of the developer's
guide. The only exceptions are that points 5, 7, and 8 in that guide do not
diff --git a/doc/guides/intro.rst b/doc/guides/intro.rst
index 19101934..8dcad4ab 100644
--- a/doc/guides/intro.rst
+++ b/doc/guides/intro.rst
@@ -27,13 +27,13 @@ Unikraft, you get support for these platforms and
architectures for
***********************
Unikraft Libraries
***********************
-Unikraft libraries are grouped into two large groups: core libraries,
-and external libraries. Core libraries generally provide functionality
-typically found in operating systems. Such libraries are grouped into
-categories such as memory allocators, schedulers, filesystems, network
-stacks and drivers, among others. Core libraries are part of the main
-Unikraft repo which also contains the build tool and configuration
-menu.
+Unikraft libraries are grouped into two large groups: core (or
+internal) libraries, and external libraries. Core libraries generally
+provide functionality typically found in operating systems. Such
+libraries are grouped into categories such as memory allocators,
+schedulers, filesystems, network stacks and drivers, among
+others. Core libraries are part of the main Unikraft repo which also
+contains the build tool and configuration menu.
External libraries consist of existing code not specifically meant for
Unikraft. This includes standard libraries such as libc or openssl, but
diff --git a/doc/guides/users-downloads.rst b/doc/guides/users-downloads.rst
new file mode 100644
index 00000000..901598fd
--- /dev/null
+++ b/doc/guides/users-downloads.rst
@@ -0,0 +1,5 @@
+************************************
+Downloads
+************************************
+All the Unikraft repos and sources can be found on `Github
+<https://github.com/unikraft>`_
diff --git a/doc/guides/users-gettingstarted.rst
b/doc/guides/users-gettingstarted.rst
new file mode 100644
index 00000000..44e18c53
--- /dev/null
+++ b/doc/guides/users-gettingstarted.rst
@@ -0,0 +1,135 @@
+.. _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-resources.rst b/doc/guides/users-resources.rst
new file mode 100644
index 00000000..bdfe530c
--- /dev/null
+++ b/doc/guides/users-resources.rst
@@ -0,0 +1,8 @@
+************************************
+Additional Resources
+************************************
+Below is a short list of additional resources related to Unikraft:
+
+ * `Unikraft team <https://www.xenproject.org/developers/teams/unikraft/>`_
+ * `Mailing list subscription
<https://lists.xenproject.org/cgi-bin/mailman/listinfo/minios-devel>`_
+ * `Mailing list archives
<https://lists.xenproject.org/archives/html/minios-devel/>`_
diff --git a/doc/guides/users-tutorial.rst b/doc/guides/users-tutorial.rst
new file mode 100644
index 00000000..0a7c615d
--- /dev/null
+++ b/doc/guides/users-tutorial.rst
@@ -0,0 +1,286 @@
+************************************
+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 3c55653d..0500b8fa 100644
--- a/doc/guides/users.rst
+++ b/doc/guides/users.rst
@@ -1,103 +1,15 @@
####################
User's Guide
####################
-To begin using Unikraft you'll need to have gcc, make and git
-installed. First clone the Unikraft main repo: ::
-
- git clone http://xenbits.xen.org/git-http/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 at
-http://xenbits.xen.org/gitweb/?a=project_list;pf=unikraft/libs .
-Each external library has its own separate repo, so you'll need to clone each
-one separately.
-
-Likewise, if you will be using any external platforms, please clone those too.
-You can see a list of available external platforms at
-http://xenbits.xen.org/gitweb/?a=project_list;pf=unikraft/plats .
-
-Finally, you'll need to create a Unikraft application. 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://xenbits.xen.org/git-http/unikraft/apps/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 will be using 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 will use 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)
-
-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
-
-And that's it! We'll be posting further Unikraft application repos at
-::
-
- http://xenbits.xen.org/gitweb/?a=project_list;pf=unikraft/apps
-
-For more information regarding porting and developing apps (and
-libraries) in Unikraft please read the developer's guide.
+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
_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel
