Re: [Minios-devel] [UNIKRAFT PATCH v5 2/4] doc: Add section about symbol exporting

[Florian Schmidt <Florian.Schmidt@xxxxxxxxx>]

Hi,

Reviewed-by: Florian Schmidt <florian.schmidt@xxxxxxxxx>

There's just one typo which I will fix when pushing, see below.

On 09/03/2018 02:17 PM, Simon Kuenzer wrote:
> From: Yuri Volchkov <yuri.volchkov@xxxxxxxxx>
>
> This patch additionally adds some cross-links between application,
> internal library, and external library development guides.
>
> Signed-off-by: Yuri Volchkov <yuri.volchkov@xxxxxxxxx>
> Signed-off-by: Simon Kuenzer <simon.kuenzer@xxxxxxxxx>
> ---
>   doc/guides/developers-app.rst          | 36 +++++++++++++++++++++++++++++++++-
>   doc/guides/developers-external-lib.rst |  9 +++++----
>   doc/guides/developers-internal-lib.rst | 25 +++++++++++++----------
>   3 files changed, 55 insertions(+), 15 deletions(-)
>
> diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
> index 12e4739..d3e3a34 100644
> --- a/doc/guides/developers-app.rst
> +++ b/doc/guides/developers-app.rst
> @@ -13,7 +13,7 @@ and rely on Unikraft's build system to build the necessary 
> objects with
>   correct and compatible compiler and linker flags).
>   
>   In greater detail, in order for an application to work with Unikraft
> -you need to provide at least the following three files:
> +you need to provide at least the following four files:
>   
>    * **Makefile**: Used to specify where the main Unikraft repo is with
>      respect to the application's repo, as well as repos for any external
> @@ -26,6 +26,11 @@ you need to provide at least the following three files:
>    * **Config.uk**: A Kconfig-like snippet used to populate Unikraft's
>      menu with application-specific options.
>   
> + * **exportsyms.uk**: A text file where each line contains the name
> +   of one symbol that should be exported to other libraries. This file
> +   usually contains only `main` for an application that is developed/ported
> +   as a single library to Unikraft.
> +
>   The Makefile is generally short and simple and might remind you to
>   Linux kernel modules that are built off-tree. For most applications
>   the Makefile should contain no more than the following: ::
> @@ -43,6 +48,8 @@ the Makefile should contain no more than the following: ::
>   We cover the format of the other two files in turn next, followed by
>   an explanation of the build process.
>   
> +.. _lib-essential-files:
> +
>   ============================
>   Config.uk
>   ============================
> @@ -229,6 +236,8 @@ Reserved variable names in the name scope are so far: ::
>   
>     APPNAME_BASE                              - Path to source base
>     APPNAME_BUILD                             - Path to target build dir
> +  APPNAME_EXPORTS                           - Path to the list of exported 
> symbols
> +                                              (default is 
> '$(APPNAME_BASE)/exportsyms.uk')
>     APPNAME_ORIGIN                            - Path to extracted archive
>                                                 (when fetch or unarchive was 
> used)
>     APPNAME_CLEAN APPNAME_CLEAN-y             - List of files to clean 
> additional
> @@ -260,6 +269,31 @@ Reserved variable names in the name scope are so far: ::
>     APPNAME_FILENAME_VARIANT_INCLUDES         - Includes for a *specific* source
>     APPNAME_FILENAME_VARIANT_INCLUDES-y         file and variant of the library
>   
> +
> +============================
> +exportsyms.uk
> +============================
> +Unikraft provides separate namespaces for each library. This means that
> +every function and variable will only be visible and linkable internally.
> +
> +To make a symbol visible for other libraries, add it to this
> +``exportsyms.uk`` file. It is simply a flat file, with one symbol name per
> +line. Line comments may be introduced by the hash character ('#'). This
> +option may be given more than once.
> +
> +If you are writing an application, you need to add you program entry point
> +else should be there. For a library, all external API functions must be listed.
"you*r* program entry point to this file"

> +For the sake of file structure consistency, it is not recommended to
> +change the default path of this symbols file, unless it is really necessary
> +(e.g., multiple libraries are sharing the same base folder, this symbols file
> +is part of a remotely fetched archive). You can override it by defining the
> +``APPNAME_EXPORTS`` variable. The path must be either absolute (you can refer
> +with ``$(APPNAME_BASE)`` to the base directory of your application sources) or
> +relative to the Unikraft sources directory.
> +
> +
>   ============================
>   Make Targets
>   ============================
> diff --git a/doc/guides/developers-external-lib.rst 
> b/doc/guides/developers-external-lib.rst
> index 518c1fe..fb76bd8 100644
> --- a/doc/guides/developers-external-lib.rst
> +++ b/doc/guides/developers-external-lib.rst
> @@ -2,10 +2,11 @@
>   External Library Development
>   ****************************
>   Porting an external library (e.g., openssl) isn't too different from
> -porting an application: in this case, no Makefile is needed, and
> -Makefile.uk follows the same format described above except that for naming
> -``lib`` is prefixed instead of ``app`` (``lib[name]`` instead of ``app[name]``;
> -e.g., ``libnewlib`` for ``newlib``).
> +porting an :doc:`application <developers-app>`: in this case, no
> +Makefile is needed, and Makefile.uk follows the same format described
> +above except that for naming ``lib`` is prefixed instead of ``app``
> +(``lib[name]`` instead of ``app[name]``; e.g., ``libnewlib`` for
> +``newlib``).
>   
>   Another difference relates to Config.uk: You surround your settings with
>   ``menuconfig`` that enables selecting and deselecting the library. The name of
> diff --git a/doc/guides/developers-internal-lib.rst 
> b/doc/guides/developers-internal-lib.rst
> index e1d3037..80dd32c 100644
> --- a/doc/guides/developers-internal-lib.rst
> +++ b/doc/guides/developers-internal-lib.rst
> @@ -1,8 +1,8 @@
>   ****************************
>   Internal Library Development
>   ****************************
> -Unikraft libraries are no different than external ones, except for the
> -fact that
> +Unikraft libraries are no different than :doc:`external ones
> +<developers-external-lib>`, except for the fact that
>   
>   1. they are part of the main Unikraft repo and live under the
>      ``lib/name/`` directories.
> @@ -40,14 +40,19 @@ looks as follows: ::
>     ├── include
>     │   └── uk
>     │       └── [category].h
> -  └── Makefile.uk
> -
> -The ``Config.uk`` and ``Makefile.uk`` files are fairly
> -straightforward, you can refer to an existing API in the repo to see
> -what they look like. The header file contains the API itself and
> -follows a generic structure that all APIs should follow; please refer
> -to existing API header files if you'd like to see what these look
> -like (e.g., ``libukalloc``, ``libuksched``).
> +  ├── Makefile.uk
> +  └── exportsyms.uk
> +
> +
> +The ``Config.uk``, ``Makefile.uk`` and ``exportsyms.uk`` files are
> +fairly straightforward. You can refer to an existing API in the repo
> +to see what they look like. Also check the corresponding sections
> +:ref:`Application Development and Porting <lib-essential-files>`
> +
> +The header file contains the API itself
> +and follows a generic structure that all APIs should follow; please
> +refer to existing API header files if you'd like to see what these
> +look like (e.g., ``libukalloc``, ``libuksched``).
>   
>   To implement a library that complies with an API, we begin by creating
>   a similar directory structure as above, using ``uk[category][name]``
--
Dr. Florian Schmidt
フローリアン・シュミット
Research Scientist,
Systems and Machine Learning Group
NEC Laboratories Europe
Kurfürsten-Anlage 36, D-69115 Heidelberg
Tel.     +49 (0)6221 4342-265
Fax:     +49 (0)6221 4342-155
e-mail:  florian.schmidt@xxxxxxxxx
============================================================
Registered at Amtsgericht Mannheim, Germany, HRB728558

_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel