Re: [Minios-devel] [UNIKRAFT PATCH doc_edit] users.rst: Specify the directory

[Lars Kurth <lars.kurth.xen@xxxxxxxxx>]

Ray! Congrats for sending your first patch.

@Simon: it seems to me that a few things are wrong / inaccurate / slightly 
misleading in the doc
Firstly, I tripped over versions of make (>= 4.1)
We should probably specify the versions and let Ray include the change into a 
patch (as he already is working on it)
Do you know if there is a minimum version of gcc?

@Ray: 
I would make the title cleaner: e.g. "users.rst: clean up ambiguities related 
to path set-up and external libraries"

> On 18 Feb 2018, at 16:38, Ray LI <ray4opensource@xxxxxxxxx> wrote:
> 
> According to the intro part of document, add a sentence to specify where 
> ``unikraft-libs`` is from.

This will need to be changed according to what you decide (see below).

> Signed-off-by: Ray LI <ray4opensource@xxxxxxxxx>
> ---
> doc/guides/users.rst | 1 +
> 1 file changed, 1 insertion(+)
> 
> diff --git a/doc/guides/users.rst b/doc/guides/users.rst
> index 7f41a95..d0f2d4f 100644
> --- a/doc/guides/users.rst
> +++ b/doc/guides/users.rst
> @@ -38,6 +38,7 @@ those variables as follows: ::
> 
>   UK_ROOT ?= $(PWD)/../../unikraft
>   UK_LIBS ?= $(PWD)/../../unikraft-libs
> +Note that the above ``unikraft-libs`` directory is the ``lib`` directory in 
> the ``unikraft`` directory.

In essence, the guide is confusing because it explains how to build the 
HelloWorld app, but mixes in elements that are needed for a more complex app.
That's why you tripped over it.

If you look at the Makefile in the app directory, you see that UK_LIBS is only 
needed when you use external libraries (you can tell, because UK_LIBS is not 
passed to a nested make calls in line 6 & 9)
This means that to build HelloWorld, you only need to set UK_ROOT
You only need to set LIBS/UK_LIBS when you use external libraries (which the 
HelloWorld app does not need)

With this in mind, the note you proposed is actually incorrect.

There are a two ways to fix this:

* Split the confusing doc into several parts: 
   [Part 1: focus on HelloWorld only]
   [Part 2: HelloWorld + external library: the paragraph "If you’ll be using 
... one separately." should be here, so all the stuff about UK_LIBS and LIBS. I 
would probably split the graph with the directory structure and keep the part 
related to unikraft-libs in part 2 and the rest in part 1]
   [Part 3: Everything after "With all of this in place, we’re..."]
  You can make this much clearer by rearranging a few paragraphs and making 
minor modifications to sentences such that it reads nicely

* Or you could just do minimal text changes that reflect the fact that UK_LIBS 
is only sometimes needed

I will leave it up to you how you want to address this

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