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