[Minios-devel] [UNIKRAFT PATCH v3 3/3] doc: add section about export.syms

[Yuri Volchkov <yuri.volchkov@xxxxxxxxx>]

This patch also adds a couple of cross-links between application,
internal and external lib development guides.

Signed-off-by: Yuri Volchkov <yuri.volchkov@xxxxxxxxx>
---
 doc/guides/developers-app.rst          | 26 ++++++++++++++++++++++++++
 doc/guides/developers-external-lib.rst |  9 +++++----
 doc/guides/developers-internal-lib.rst | 25 +++++++++++++++----------
 3 files changed, 46 insertions(+), 14 deletions(-)

diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
index 12e4739..4d7ba1e 100644
--- a/doc/guides/developers-app.rst
+++ b/doc/guides/developers-app.rst
@@ -43,6 +43,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
 ============================
@@ -259,6 +261,30 @@ Reserved variable names in the name scope are so far: ::
   APPNAME_FILENAME_VARIANT_FLAGS-y            and variant of the library
   APPNAME_FILENAME_VARIANT_INCLUDES         - Includes for a *specific* source
   APPNAME_FILENAME_VARIANT_INCLUDES-y         file and variant of the library
+  APPNAME_EXPORT_SYMS_SUFFIX                - add suffix to the default 
'export.syms'
+
+============================
+export.syms
+============================
+
+Unikraft provides a separate namespace for each
+application/library. Meaning even if a function/variable is not
+defined as a **static**, it would not be visible for other
+applications/libraries. However this does not affect files within the
+application itself - normal rules apply inside one namespace.
+
+To make symbol visibility go beyond the namespace, add it to the
+export.syms 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.
+
+In case of application, this file need to have just the "main"
+function. For a library all API functions must be present there.
+
+The name of this file could be altered by defining a variable
+APPNAME_EXPORT_SYMS_SUFFIX. This is helpful in case multiple libraries
+are sharing one base folder.
+
 
 ============================
 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..928a358 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
+  └── export.syms
+
+
+The ``Config.uk``, ``Makefile.uk`` and ``export.syms`` 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.17.1


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