README: Update description of Musl support

The contents of the README.md file are not up-to-date. Replace them with
a short description of Musl, and point out that Musl is the default
Unikraft libc.

Signed-off-by: Razvan Deaconescu <razvand@unikraft.io>
Reviewed-by: Robert Kuban <robert.kuban@opensynergy.com>
Reviewed-by: Maria Sfiraiala <maria.sfiraiala@gmail.com>
Approved-by: Eduard Vintilă <eduard.vintila47@gmail.com>
Tested-by: Unikraft CI <monkey@unikraft.io>
GitHub-Closes: #49

diff --git a/README.md b/README.md
index 146884102aa265a5b97766ad83844ff93a2a9254..ba065180f1cc173ce26b00d00584999739440e22 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,29 +1,24 @@
-musl for Unikraft
-===================
+# Musl
 
-This first release provides a functional version of musl (compiles and
-links) on Unikraft but some functions are not supported (especially
-the ones related to threads and network). Furthermore, some functions
-can have unexpected behaviour since they use musl internal thread
-support.
+[Musl](https://musl.libc.org/) is a standard C library (libc) providing POSIX support on top of the Linux system call API.
+These are support files for Musl support in Unikraft.
 
-## Build
+Musl is the default and recommended libc for Unikraft.
+[`newlib`](https://github.com/unikraft/lib-newlib) is another libc available for Unikraft.
+Musl provides thread support natively, while `newlib` requires [`pthread-embedded`](https://github.com/unikraft/lib-pthread-embedded/);
+Musl doesn't require (and must not be built with) `pthread-embedded`.
 
-In order to avoid multiple definitions errors, the following components
-MUST NOT BE INCLUDED with musl:
+Note that [`lwip`](https://github.com/unikraft/lib-lwip) is required for networking support.
 
-* `lwip->socket`
-* `pthread-embedded`
+## Using Musl with Unikraft
 
-## Known Issues
+Musl is to be used as the standard C library in Unikraft applications, such as [`app-nginx`](https://github.com/unikraft/app-nginx).
+The application build system must be aware of the location of the local clone of the Musl repository.
+When Musl is selected the [internal Unikraft `nolibc` library](https://github.com/unikraft/unikraft/tree/staging/lib/nolibc) will be unselected.
 
-* At this stage, we noticed that there are some issues with buffering
-on stdout. We are currently investigating this issue but a temporary
-fix is to call `fflush()` after each output on the console.
+## Remarks
 
-As things stabilize, we will update this file to reflect this.
-
-## Further information
-
-Please refer to the `README.md` as well as the documentation in the `doc/`
-subdirectory of the main unikraft repository.
+The default configuration doesn't include complex number support, i.e. the `LIBMUSL_COMPLEX` option is disabled (see `Config.uk`);
+see [commit `45c4aa58`](https://github.com/unikraft/lib-musl/commit/45c4aa586fa0a215ebd1bc2950f5fe249d1b965c).
+This is because, in case of using Clang to build Musl, the symbol `_muldc3` (used for complex numbers) is undefined;
+in case of using Clang and requiring complex number support, [`compiler-rt`](https://github.com/unikraft/lib-compiler-rt/) is to be included to the build.