|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Minios-devel] [UNIKRAFT PATCH] doc: Update documentation to consolidate information in single place
Hi Sharan,
Please see comments inline.
-- Felipe
On 04.11.19, 14:26, "Minios-devel on behalf of Sharan Santhanam"
<minios-devel-bounces@xxxxxxxxxxxxxxxxxxxx on behalf of
sharan.santhanam@xxxxxxxxx> wrote:
Hello Felipe,
Please find the comment inline:
The patch does not apply cleanly. I got these error when try to apply
the patch.
git apply --ignore-whitespace 1031.patch
1031.patch:264: trailing whitespace.
1031.patch:370: trailing whitespace.
for parsing the trace buffer.
1031.patch:484: trailing whitespace.
1031.patch:593: trailing whitespace.
1031.patch:609: trailing whitespace.
* `Mailing list subscription
<https://lists.xenproject.org/cgi-bin/mailman/listinfo/minios-devel>`_
error: patch failed: doc/guides/users.rst:1
error: doc/guides/users.rst: patch does not apply
Ok, I'll try to see what the issue is.
On 11/4/19 12:14 PM, Felipe Huici wrote:
> 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 | 15 +-
> doc/guides/_static | 0
> doc/guides/conf.py | 6 +-
> doc/guides/contribute.rst | 15 +-
> doc/guides/developers-app.rst | 8 +-
> doc/guides/developers-debugging.rst | 77 ++++---
> doc/guides/developers-external-plat.rst | 4 +-
> doc/guides/intro.rst | 14 +-
> doc/guides/users-downloads.rst | 5 +
> doc/guides/users-gettingstarted.rst | 133 +++++++++++
> doc/guides/users-resources.rst | 8 +
> doc/guides/users-tutorial.rst | 285 ++++++++++++++++++++++++
> doc/guides/users.rst | 112 +---------
> 13 files changed, 521 insertions(+), 161 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..8e39259a 100644
> --- a/README.md
> +++ b/README.md
> @@ -31,21 +31,20 @@ 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)
We could point to patch work also for the patch set and discussion.
Yes, it should be on there, I'll add it.
> * [Mailing List
Subscription](mailto:minios-devel-request@xxxxxxxxxxxxxxxxxxxx)
> -* [Research Project at NEC Labs
Europe](http://sysml.neclab.eu/projects/unikraft/)
> 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..c292d78b 100644
> --- a/doc/guides/contribute.rst
> +++ b/doc/guides/contribute.rst
> @@ -2,9 +2,12 @@
> Contribute to Unikraft
> ****************************
>
> -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 would like to get 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 .
> +
> +Also have a look to the project's ``CONTRIBUTING.md`` and
> +``MAINTAINERS.md`` file.
The CONTRIBUTING.md and MAINTAINERS.md are useful to check before
submitting a patch series.
It is better to put in separate section and not combine with the list of
issues.
Ok, though I think it should probably still be under the header of " Contribute
to Unikraft", either as sub-sections or I can at least begin by pointing out
CONTRIBUTING.md and only afterwards mentioning issues/open projects.
> 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..40d89fc7 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,41 +155,41 @@ 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
> - for parsing the trace buffer.
> +.. note:: The \*.dbg image is required, as it have offline data needed
> + for parsing the trace buffer.
>
> ----------------------------
> Adding your tracepoints
> @@ -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..c8830e90
> --- /dev/null
> +++ b/doc/guides/users-gettingstarted.rst
> @@ -0,0 +1,133 @@
> +.. _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)
Since we have a broken dependency in the fetch prepare. Wouldn't it make
it sense to add them as separate the stages in Makefile.
@make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) fetch
@make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) prepare
Yeah, might be better to document it this way until we fix the issue.
> +
> +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 -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
Why are we including -s -S
That's a copy and paste error, I'll remove that.
> +
> +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..51f8048a
> --- /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..98f944c5
> --- /dev/null
> +++ b/doc/guides/users-tutorial.rst
> @@ -0,0 +1,285 @@
> +************************************
> +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 <http://www.sourceware.org/newlib/>`_, a
Instead of the newlib origin repo shouldn't we point to github.
> +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 ``virbr0`` with the
> +name of your local bridge on your system and make sure you have a DHCP
Shouldn't we explicitly ask them to enable dhcp client option within
lwip as it not the default option?
> +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
s/br0/virbr0
> +
> +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
_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel
_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |