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

[Simon Kuenzer <simon.kuenzer@xxxxxxxxx>]

On 03.09.2018 14:58, Florian Schmidt wrote:
> Hi,
>
> Reviewed-by: Florian Schmidt <florian.schmidt@xxxxxxxxx>
>
> There's just one typo which I will fix when pushing, see below.
Hi,

thanks a lot!

Cheers

> 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]``
_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel