|
[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
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 Thanks & Regards Sharan 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. * [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 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. 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"; 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 + +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 + +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. +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
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |