[Minios-devel] [UNIKRAFT PATCH v2 2/2] doc: Introduce external platforms

[Simon Kuenzer <simon.kuenzer@xxxxxxxxx>]

Adds documentation about external platforms.

Signed-off-by: Simon Kuenzer <simon.kuenzer@xxxxxxxxx>
---
 doc/guides/developers-app.rst                 | 12 +++--
 doc/guides/developers-external-plat.rst       |  7 +++
 ...tform.rst => developers-internal-plat.rst} | 10 ++--
 doc/guides/developers.rst                     |  3 +-
 doc/guides/users.rst                          | 50 ++++++++++++++-----
 5 files changed, 58 insertions(+), 24 deletions(-)
 create mode 100644 doc/guides/developers-external-plat.rst
 rename doc/guides/{developers-platform.rst => developers-internal-plat.rst} 
(94%)

diff --git a/doc/guides/developers-app.rst b/doc/guides/developers-app.rst
index 0aafee3f..c9e4a6eb 100644
--- a/doc/guides/developers-app.rst
+++ b/doc/guides/developers-app.rst
@@ -38,15 +38,17 @@ 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: ::
 
-  UK_ROOT ?= $(PWD)/../../unikraft
-  UK_LIBS ?= $(PWD)/../../libs
-  LIBS := $(UK_LIBS)/lib1:$(UK_LIBS)/lib2:$(UK_LIBS)/libN
+  UK_ROOT  ?= $(PWD)/../../unikraft
+  UK_LIBS  ?= $(PWD)/../../libs
+  UK_PLATS ?= $(PWD)/../../plats
+  LIBS  := $(UK_LIBS)/lib1:$(UK_LIBS)/lib2:$(UK_LIBS)/libN
+  PLATS ?=
 
   all:
-          @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS)
+          @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS)
 
   $(MAKECMDGOALS):
-         @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) $(MAKECMDGOALS)
+         @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS) $(MAKECMDGOALS)
 
 We cover the format of the other two files in turn next, followed by
 an explanation of the build process.
diff --git a/doc/guides/developers-external-plat.rst 
b/doc/guides/developers-external-plat.rst
new file mode 100644
index 00000000..7021ab28
--- /dev/null
+++ b/doc/guides/developers-external-plat.rst
@@ -0,0 +1,7 @@
+****************************
+External Platform Development
+****************************
+External platform development is exactly like developing an internal
+platform, so please refer to that section of the developer's
+guide. The only exceptions are that points 5, 7, and 8 in that guide do not
+apply to an external library.
diff --git a/doc/guides/developers-platform.rst 
b/doc/guides/developers-internal-plat.rst
similarity index 94%
rename from doc/guides/developers-platform.rst
rename to doc/guides/developers-internal-plat.rst
index b9411ea8..0fd1e758 100644
--- a/doc/guides/developers-platform.rst
+++ b/doc/guides/developers-internal-plat.rst
@@ -1,6 +1,6 @@
-****************************
-Platform Library Development
-****************************
+*****************************
+Internal Platform Development
+*****************************
 Platforms (e.g., Xen, KVM, Linux user-space, etc.) are also
 treated as libraries in Unikraft but there are a few differences:
 
@@ -19,8 +19,8 @@ treated as libraries in Unikraft but there are a few 
differences:
    ``UK_PLAT_PLATNAME_DEF_LDS`` variable in the Makefile.uk of the platform
    library. The default linker script is also added as a source file to the
    platform library to be built. If the default linker script is not provided,
-   then Unikraft would rely on the default linker script provided by the 
compiler
-   tool chain.
+   then Unikraft would rely on the default linker script provided by the
+   compiler tool chain.
 
 5. You need to place all platform files in the Unikraft repo under
    ``plat/platname/``.
diff --git a/doc/guides/developers.rst b/doc/guides/developers.rst
index 59e1161a..9a68a391 100644
--- a/doc/guides/developers.rst
+++ b/doc/guides/developers.rst
@@ -11,6 +11,7 @@ any external libraries and applications you might want to 
work with.
    developers-app
    developers-external-lib
    developers-internal-lib
-   developers-platform
+   developers-internal-plat
+   developers-external-plat
    developers-debugging
 
diff --git a/doc/guides/users.rst b/doc/guides/users.rst
index d590efc7..3c55653d 100644
--- a/doc/guides/users.rst
+++ b/doc/guides/users.rst
@@ -12,6 +12,10 @@ 
http://xenbits.xen.org/gitweb/?a=project_list;pf=unikraft/libs .
 Each external library has its own separate repo, so you'll need to clone each
 one separately.
 
+Likewise, if you will be using any external platforms, please clone those too.
+You can see a list of available external platforms at
+http://xenbits.xen.org/gitweb/?a=project_list;pf=unikraft/plats .
+
 Finally, you'll need to create a Unikraft application. To get quickly
 started, the easiest is to clone the hello world app (once again, each
 Unikraft app has its own repo): ::
@@ -19,33 +23,52 @@ Unikraft app has its own repo): ::
   git clone http://xenbits.xen.org/git-http/unikraft/apps/helloworld.git
 
 Now edit the Makefile in the app directory. In particular, set the
-``UK_ROOT`` and ``UK_LIBS`` variables to point to the directories where you
-cloned the repos above. For instance, assuming the following directory
-structure ::
+``UK_ROOT``, ``UK_LIBS``, and ``UK_PLATS`` variables to point to the
+directories where you cloned the repos above. For instance, assuming
+the following directory structure ::
 
   ├── unikraft
   ├── apps
   │  ├── helloworld
   │  ├── app1
   │  ├── app2
-  └── libs
-     ├── lib1
-     ├── lib2
-     └── libN
+  │  ...
+  │  ├── appN
+  ├── libs
+  │  ├── lib1
+  │  ├── lib2
+  │  ...
+  │  └── libN
+  └── plats
+     ├── plat1
+     ├── plat2
+     ...
+     └── platN
 
 where your app is located at ``apps/helloworld``, you would set
-those variables as follows: ::
+the variables as follows: ::
 
-  UK_ROOT ?= $(PWD)/../../unikraft
-  UK_LIBS ?= $(PWD)/../../libs
+  UK_ROOT  ?= $(PWD)/../../unikraft
+  UK_LIBS  ?= $(PWD)/../../libs
+  UK_PLATS ?= $(PWD)/../../plats
 
-Finally, if your app will be using external libraries, set the ``LIBS``
+If your app will be using external libraries, set the ``LIBS``
 variable to reflect this. For instance : ::
 
   LIBS := $(UK_LIBS)/lib1:$(UK_LIBS)/lib2:$(UK_LIBS)/libN
 
 Note that the list has to be colon-separated.
 
+Finally, if your app will use external platforms, set the ``PLATS``
+variable: ::
+
+  PLATS ?= $(UK_PLATS)/plat1:$(UK_PLATS)/plat2:$(UK_PLATS)/platN
+
+Also make sure that you hand-over these platforms with the
+``P=`` parameter to the sub make call in your main ``Makefile``: ::
+
+  @make -C $(UK_ROOT) A=$(PWD) L=$(LIBS) P=$(PLATS)
+
 With all of this in place, we're now ready to start configuring the
 application image via Unikraft's menu. To access it, from within the
 app's directory simply type ::
@@ -55,8 +78,9 @@ app's directory simply type ::
 The menu system is fairly self-explanatory and will be familiar to
 anyone who has configured a Linux kernel before. Select the options
 you want, the libraries you'll like to include and don't forget to
-select at least one platform (e.g., KVM, Xen or Linux user-space --
-the latter is quite useful for quick testing and debugging).
+select at least one platform (e.g., an external one, KVM, Xen, or
+Linux user-space -- the latter is quite useful for quick testing and
+debugging).
 
 Finally, quit the menu while saving the configuration changes you've
 made and build your application by just typing ``make``. Unikraft will
-- 
2.20.1


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