From aff816f07d490122e41779296dbff40d3284afca Mon Sep 17 00:00:00 2001
From: Ribbon <ribbon_45@proton.me>
Date: Thu, 7 Dec 2023 15:35:13 +0000
Subject: [PATCH] Improve the README

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 1dc17f2f66..0a98315000 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,45 @@
-# relibc ![build](https://travis-ci.org/redox-os/relibc.svg?branch=master)
+# relibc
+
 relibc is a portable POSIX C standard library written in Rust. It is under heavy development, and currently supports Redox and Linux.
 
-The motivation for this project is twofold: Reduce issues the redox crew was having with newlib, and create a safer alternative to a C standard library written in C. It is mainly designed to be used under redox, as an alternative to newlib, but it also supports linux syscalls via the [sc](https://crates.io/crates/sc) crate.
+The motivation for this project is twofold: Reduce issues that the Redox developers were having with [newlib](https://sourceware.org/newlib/), and create a safer alternative to a C standard library written in C. It is mainly designed to be used under Redox, as an alternative to newlib, but it also supports Linux system calls via the [sc](https://crates.io/crates/sc) crate.
 
-## Building
-Just run `make all`.
+### Repository Layout
+
+- `include` - Header files (mostly macros and variadic functions `cbindgen` can't generate)
+- `src` - Source files
+- `src/c` - C code
+- `src/crt0` - Runtime code
+- `src/crti` - Runtime code
+- `src/crtn` - Runtime code
+- `src/header` - Header files implementation
+- `src/header/*` - Each folder has a `cbindgen.toml` file, it generates a C-to-Rust interface and header files
+- `src/ld_so` - Dynamic loader code
+- `src/platform` - Platform-specific and common code
+- `src/platform/redox` - Redox-specific code
+- `src/platform/linux` - Linux-specific code
+- `src/pthread` - pthread implementation
+- `src/sync` - Synchronization primitives
+- `tests` - C tests (each MR needs to give success in all of them)
+
+### Build On The Build System
+
+Inside of your Redox build system, run:
+
+```sh
+make prefix
+```
+
+(It only works if the timestamp of the `relibc` folder changed)
 
 ### Issues
+
 #### I'm building for my own platform which I run, and am getting `x86_64-linux-gnu-ar: command not found` (or similar)
-The Makefile expects the gnu compiler tools prefixed with the platform specifier, as would be present when you'd install a cross compiler. Since you are building for your own platform, some distros (like Manjaro) don't install/symlink the prefixed executables.
+
+The Makefile expects GNU compiler tools prefixed with the platform specifier, as would be present when you installed a cross compiler. Since you are building for your own platform, some Linux distributions (like Manjaro) don't install/symlink the prefixed executables.
+
 An easy fix would be to replace the corresponding lines in the Makefile, e.g.
+
 ```diff
  ifeq ($(TARGET),x86_64-unknown-linux-gnu)
         export CC=x86_64-linux-gnu-gcc
@@ -21,14 +51,16 @@ An easy fix would be to replace the corresponding lines in the Makefile, e.g.
  endif
 ```
 
-### [Contributing](CONTRIBUTING.md)
+### Contributing
 
-## Supported OSes
+Before starting to contribute, read [this](CONTRIBUTING.md) document.
+
+### Supported OSes
 
  - Redox OS
  - Linux
 
-## Supported architectures
+### Supported architectures
 
- - x86\_64
- - Aarch64
+ - x86_64 (Intel/AMD)
+ - Aarch64 (ARM64)