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

[Florian Schmidt <Florian.Schmidt@xxxxxxxxx>]

On 08/24/2018 01:11 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          | 32 +++++++++++++++++++++++++++++++-
>   doc/guides/developers-external-lib.rst |  9 +++++----
>   doc/guides/developers-internal-lib.rst | 25 +++++++++++++++----------
>   3 files changed, 51 insertions(+), 15 deletions(-)
>
> diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
> index 12e4739..458ccfc 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 '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,27 @@ 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 is only be visible and linkable internally.
remove the "be".

> +
> +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.
"To make a symbol visible to other libraries, add it to exportsyms.uk, 
with one symbol name per line."
By the way, are globs of any sort allowed?

> +
> +In case of application, this file need to have just the "main"
> +function. For a library all API functions must be present there.
If you're writing an application, you need to add "main" as the entry 
point from unikraft into this file, but most likely no other functions.
For a library, all external API functions must be listed here.

> +
> +You can change the location if this file by defining the
> +``APPNAME_EXPORTS`` variable with the path to it. This is helpful in case
> +multiple libraries are sharing the same base folder or this symbol file
> +is part of a remotely fetched archive.
_of_ this file. Also, "with the path to it" isn't 100% clear I think. 
Does it mean I have to give a full path? Can optionally five a full 
path, but can also give a relative one? Only the path or also the file name?
> +
> +
>   ============================
>   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..8cd9539 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
"...straightforward, you can...": I'd make that two sentences split by a 
semicolon or period.
> +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