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

[Simon Kuenzer <simon.kuenzer@xxxxxxxxx>]

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
+into this file (this is ``main`` if you use ``libukboot``). Most likely nothing
+else should be there. For a library, all external API functions must be listed.
+
+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]``
-- 
2.7.4


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