all: add some README.md files describing the purpose of our sources

30 files changed, 426 insertions, 3 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bc57f962ed..254ba066c9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -218,7 +218,7 @@ Code Structure
 
 `./po`- contains text-based portable object file. These .PO files are referenced by GNU gettext as a property file and these files are human readable used for translating purpose.
 
-`./src`- source code for libnm, nmcli, nm-cloud-setup, nmtui…
+[`./src`](src/)- source code for libnm, nmcli, nm-cloud-setup, nmtui…
 
 `./tools`- tools for generating the intermediate files or merging the file.
 
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000000..e923ef7f25
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,65 @@
+src/
+====
+
+Most of the subdirectories are static helper libraries, which
+get linked into one of the final build artifacts (like libnm,
+nmcli or NetworkManager). Static libraries are internal API.
+
+The only public API is libnm, which is a shared library provided
+client implementations.
+
+Our own clients (like nmcli and nmtui) also use libnm, the shared library.
+But they also use additional static helper libraries.
+
+The daemon statically links against a part of libnm, the part that provides
+connection profiles. That is libnm-core. libnm-core is thus statically linked
+with libnm and the daemon. It does not get linked by clients that already link
+with libnm (like nmtui).
+
+Read the individual README.md files in the subdirectories for details:
+
+| Directory                                            | Description                                             |
+|------------------------------------------------------|---------------------------------------------------------|
+| [core/](core/)                                       | the NetworkManager daemon |
+| [nmcli/](nmcli/)                                     | nmcli application, a command line client for NetworkManager |
+| [nmtui/](nmtui/)                                     | nmtui application, a text UI client for NetworkManager |
+| [nm-cloud-setup/](nm-cloud-setup/)                   | service to automatically configure NetworkManager in cloud environment |
+| [nm-initrd-generator/](nm-initrd-generator/)         | generates NetworkManager configuration by parsing kernel command line options for dracut/initrd |
+| [nm-dispatcher/](nm-dispatcher/)                     | NetworkManager-dispatcher service to run user scripts |
+| [nm-online/](nm-online/)                             | application which checks whether NetworkManager is done, for implementing NetworkManager-wait-online.service |
+| [nm-sudo/](nm-sudo/)                                 | internal service for privileged operations |
+| [nm-daemon-helper/](nm-daemon-helper/)               | internal helper binary spawned by NetworkManager |
+|                                                      | |
+| [libnm-std-aux/](libnm-std-aux/)                     | internal helper library for standard C |
+| [libnm-glib-aux/](libnm-glib-aux/)                   | internal helper library for glib |
+| [libnm-log-null/](libnm-log-null/)                   | internal helper library with dummy (null) logging backend |
+| [libnm-log-core/](libnm-log-core/)                   | internal helper library with logging backend (syslog) used by daemon |
+| [libnm-base/](libnm-base/)                           | internal helper library with base definitions |
+| [libnm-platform/](libnm-platform/)                   | internal helper library for netlink and other platform/kernel API |
+| [libnm-udev-aux/](libnm-udev-aux/)                   | internal helper library for libudev |
+|                                                      | |
+| [libnm-core-public/](libnm-core-public/)             | public API of libnm (libnm-core part) |
+| [libnm-core-intern/](libnm-core-intern/)             | internal API of libnm-core, used by libnm and daemon |
+| [libnm-core-impl/](libnm-core-impl/)                 | implementation of libnm-core |
+| [libnm-core-aux-intern/](libnm-core-aux-intern/)     | internal helper library on top of libnm-core (used by libnm-core itself) |
+| [libnm-core-aux-extern/](libnm-core-aux-extern/)     | internal helper library on top of libnm-core (not used by libnm-core) |
+| [libnm-client-public/](libnm-client-public/)         | public API of libnm (NMClient part) |
+| [libnm-client-impl/](libnm-client-impl/)             | implementation of libnm (NMClient) |
+| [libnm-client-aux-extern/](libnm-client-aux-extern/) | internal helper library on top of libnm (not used by libnm itself) |
+| [libnmc-base/](libnmc-base/)                         | internal helper library for libnm clients |
+| [libnmc-setting/](libnmc-setting/)                   | internal helper library for setting connection profiles (used by nmcli) |
+| [libnmt-newt/](libnmt-newt/)                         | internal helper library for libnewt for nmtui |
+|                                                      | |
+| [linux-headers/](linux-headers/)                     | extra Linux kernel UAPI headers |
+| [contrib/](contrib/)                                 | sources that are not used by NetworkManager itself |
+| [tests/](tests/)                                     | unit tests that are not specific to one of the other directories |
+| [libnm-client-test/](libnm-client-test/)             | internal helper library with test utils for libnm |
+|                                                      | |
+| [c-list/](c-list/)                                   | fork of c-util helper library for intrusive, doubly linked list |
+| [c-rbtree/](c-rbtree/)                               | fork of c-util helper library for intrusive Red-Black Tree |
+| [c-siphash/](c-siphash/)                             | fork of c-util helper library for SIPHash24 |
+| [c-stdaux/](c-stdaux/)                               | fork of c-util general purpose helpers for standard C |
+| [n-acd/](n-acd/)                                     | fork of nettools IPv4 ACD library |
+| [n-dhcp4/](n-dhcp4/)                                 | fork of nettools DHCPv4 library |
+| [libnm-systemd-core/](libnm-systemd-core/)           | fork of systemd code as network library |
+| [libnm-systemd-shared/](libnm-systemd-shared/)       | fork of systemd code as general purpose library |
diff --git a/src/contrib/README.md b/src/contrib/README.md
new file mode 100644
index 0000000000..81ebaf0331
--- /dev/null
+++ b/src/contrib/README.md
@@ -0,0 +1,11 @@
+contrib
+=======
+
+This directories contains miscellaneous helpers.
+This code is not actually used anywhere in our source
+tree (beside unit tests).
+
+The purpose is that a external libnm/NetworkManager user
+can copy+paste these helpers into their source three. This
+code should act as an example but also be directly usable
+by copying.
diff --git a/src/core/README.md b/src/core/README.md
new file mode 100644
index 0000000000..13779197fd
--- /dev/null
+++ b/src/core/README.md
@@ -0,0 +1,9 @@
+core
+====
+
+The source code of the NetworkManager daemon.
+
+NetworkManager is a daemon that provides a D-Bus API and a file-based
+API for configuring the network on a Linux host.
+
+This is the daemon source code.
diff --git a/src/libnm-base/README.md b/src/libnm-base/README.md
new file mode 100644
index 0000000000..8eb2119a18
--- /dev/null
+++ b/src/libnm-base/README.md
@@ -0,0 +1,20 @@
+libnm-base
+==========
+
+A static helper library with network/NetworkManager specific
+code.
+
+Contrary to libnm-glib-aux, this does not contain general purpose
+helpers, but code that is more specific about NetworkManager.
+
+This is the most low-level dependency of this kind. Most NetworkManager
+specific code will directly or indirectly link with this.
+
+As this is a static library, there is no problem with dragging this into your
+binary/library, if your application already depends on libnm-glib-aux (and glib).
+
+Dependencies:
+
+  - glib
+  - [../libnm-std-aux/](../libnm-std-aux/)
+  - [../libnm-glib-aux/](../libnm-glib-aux/)
diff --git a/src/libnm-client-aux-extern/README.md b/src/libnm-client-aux-extern/README.md
index 460b269e6d..7d3b27e890 100644
--- a/src/libnm-client-aux-extern/README.md
+++ b/src/libnm-client-aux-extern/README.md
@@ -1,4 +1,7 @@
-nm-libnm-aux is a static library that:
+libnm-client-aux-extern
+=======================
+
+libnm-client-aux-extern is a static library that:
 
  - uses the public parts of "libnm"
  - that can also be statically linked into other users of libnm.
@@ -10,6 +13,10 @@ That means:
 
   - you can use it everywhere where you dynamically link with libnm.
 
-Also, since nm-libnm-aux itself only uses public (stable)
+Also, since libnm-client-aux-extern itself only uses public (stable)
 API of libnm, you theoretically can copy the sources into your
 own source tree.
+
+This makes it very similar in purpose to [../libnmc-base/](../libnmc-base/).
+The difference might be that this one is smaller and that you could easier
+copy+paste this to a libnm application outside this source tree.
diff --git a/src/libnm-client-impl/README.md b/src/libnm-client-impl/README.md
new file mode 100644
index 0000000000..1ec481c1ac
--- /dev/null
+++ b/src/libnm-client-impl/README.md
@@ -0,0 +1,14 @@
+libnm-client-impl
+=================
+
+libnm is NetworkManager's client API.
+This API consists of two parts:
+
+- the handling of connections (`NMConnection`), implemented
+  by libnm-core-impl.
+- the caching of D-Bus API (`NMClient`), implemented by
+  libnm-client-impl.
+
+This directory contains the implementation of the second part.
+As such, it will be statically linked with libnm-core-impl
+to make libnm. Also, it cannot be used by the daemon.
diff --git a/src/libnm-client-public/README.md b/src/libnm-client-public/README.md
new file mode 100644
index 0000000000..a4ecb06627
--- /dev/null
+++ b/src/libnm-client-public/README.md
@@ -0,0 +1,16 @@
+libnm-client-public
+===================
+
+libnm is NetworkManager's client API. It has a public API.
+This API consists of two parts:
+
+- the handling of connections (`NMConnection`), implemented
+  by libnm-core-impl.
+- the caching of D-Bus API (`NMClient`), implemented by
+  libnm-client-impl.
+
+This directory contains public headers that are used by libnm
+users. As such, it's the `NMClient` part of libnm-core-public.
+
+These headers are usable to any libnm client application and
+to libnm itself. But not to libnm-core-impl or the daemon.
diff --git a/src/libnm-client-test/README.md b/src/libnm-client-test/README.md
new file mode 100644
index 0000000000..f06220b47a
--- /dev/null
+++ b/src/libnm-client-test/README.md
@@ -0,0 +1,11 @@
+libnm-client-test
+=================
+
+A static helper library that is used by unit tests
+on top of libnm. Mostly it's D-Bus helpers.
+
+It has no purpose in non-test code.
+
+Unit tests may not dynamically link with libnm. They
+may also statically link with the relevant parts of libnm,
+and still be able to use this helper.
diff --git a/src/libnm-glib-aux/README.md b/src/libnm-glib-aux/README.md
new file mode 100644
index 0000000000..cb43e87c69
--- /dev/null
+++ b/src/libnm-glib-aux/README.md
@@ -0,0 +1,16 @@
+libnm-glib-aux
+==============
+
+A static helper library with general purpose helpers on top
+of glib.
+
+This is similar to libnm-std-aux (on which this library depends).
+The difference is that libnm-std-aux only requires standard C (C11),
+while this has a dependency on glib.
+
+As this has no additional dependencies, we should have all our glib code
+use this internal helper library. It contains helpers that should be
+available (and used) in all our C/glib applications/libraries.
+
+Parts of this library are usually already included via the `nm-default*.h`
+headers.
diff --git a/src/libnm-log-core/README.md b/src/libnm-log-core/README.md
new file mode 100644
index 0000000000..4223232bfa
--- /dev/null
+++ b/src/libnm-log-core/README.md
@@ -0,0 +1,10 @@
+libnm-log-core
+==============
+
+libnm-glib-aux has a forward-declaration of logging API.
+If a libnm-glib-aux user uses that API for logging, it must
+link the final binary with an implementation.
+
+There are two implementations: libnm-log-core and
+[../libnm-log-null/(..libnm-log-null/). This one is the implementation
+used by the daemon and logs to syslog/journald.
diff --git a/src/libnm-log-null/README.md b/src/libnm-log-null/README.md
new file mode 100644
index 0000000000..eb5d0821a9
--- /dev/null
+++ b/src/libnm-log-null/README.md
@@ -0,0 +1,10 @@
+libnm-log-null
+==============
+
+libnm-glib-aux has a forward-declaration of logging API.
+If a libnm-glib-aux user uses that API for logging, it must
+link the final binary with an implementation.
+
+There are two implementations: libnm-log-null and
+[../libnm-log-core/(..libnm-log-core/). This one is a dummy implementation
+that drops all logging.
diff --git a/src/libnm-platform/README.md b/src/libnm-platform/README.md
new file mode 100644
index 0000000000..c8e7cf7679
--- /dev/null
+++ b/src/libnm-platform/README.md
@@ -0,0 +1,22 @@
+libnm-platform
+==============
+
+A static helper library that provides `NMPlatform` and other utils.
+This is NetworkManager's internal netlink library, but also contains
+helpers for sysfs, ethtool and other kernel APIs.
+
+`NMPlaform` is also a cache of objects of the netlink API: `NMPCache`
+and `NMPObject`. These objects are used throughout NetworkManager
+also for generally tracking information about these types. For example,
+`NMPlatformIP4Address` (the public part of a certain type of `NMPObject`)
+is not only used to track platform addresses from netlink in the cache,
+but to track information about IPv4 addresses in general.
+
+This depends on the following helper libraries
+
+  - [../libnm-std-aux/](../libnm-std-aux/)
+  - [../libnm-base/](../libnm-base/)
+  - [../libnm-glib-aux/](../libnm-glib-aux/)
+  - [../libnm-udev-aux/](../libnm-udev-aux/)
+  - [../libnm-log-core/](../libnm-log-core/)
+  - [../linux-headers/](../linux-headers/)
diff --git a/src/libnm-std-aux/README.md b/src/libnm-std-aux/README.md
new file mode 100644
index 0000000000..ccc48e9dc8
--- /dev/null
+++ b/src/libnm-std-aux/README.md
@@ -0,0 +1,16 @@
+libnm-std-aux
+=============
+
+A static helper library with general purpose helpers on top of
+standard C (C11).
+
+As this has no additional dependencies, we should have all our C code
+use this internal helper library. It contains helpers that should be
+available (and used) everywhere where we write C.
+
+Our C is gnu11, that is C11 or newer with some GCC-ism. The requirement
+is that it is supported by all complilers we care about (in pratice GCC
+and Clang).
+
+Parts of this library are usually already included via the `nm-default*.h`
+headers.
diff --git a/src/libnm-systemd-core/README.md b/src/libnm-systemd-core/README.md
new file mode 100644
index 0000000000..b9792ca705
--- /dev/null
+++ b/src/libnm-systemd-core/README.md
@@ -0,0 +1,16 @@
+libnm-systemd-core
+==================
+
+This is a fork of systemd source files that are compiled
+as a static library with network helpers.
+
+We use systemd's DHCPv6 and LLDP library, by forking their code.
+
+We also still use their DHCPv4 library, but that is about to be replaced
+by nettools' n-dhcp4.
+
+This approach of code-reuse is very cumbersome, and we should replace
+systemd code by a proper library (like nettools).
+
+We should not use systemd directly from our sources, beyond what
+we really need.
diff --git a/src/libnm-systemd-shared/README.md b/src/libnm-systemd-shared/README.md
new file mode 100644
index 0000000000..67ad4875c2
--- /dev/null
+++ b/src/libnm-systemd-shared/README.md
@@ -0,0 +1,11 @@
+libnm-systemd-shared
+====================
+
+This is a fork of systemd source files that are compiled
+as a static library with general purpose helpers.
+
+We mainly need this for [../libnm-systemd-core/](../libnm-systemd-core/),
+which contains systemd library with network tools (like DHCPv6).
+
+We should not use systemd directly from our sources, beyond what
+we really need to make get libnm-systemd-core working.
diff --git a/src/libnm-udev-aux/README.md b/src/libnm-udev-aux/README.md
new file mode 100644
index 0000000000..648f792ca8
--- /dev/null
+++ b/src/libnm-udev-aux/README.md
@@ -0,0 +1,9 @@
+libnm-udev-aux
+==============
+
+Static helper library with tools around libudev.
+
+This library depends on glib and libudev:
+
+  - [../libnm-std-aux/](../libnm-std-aux/)
+  - [../libnm-glib-aux/](../libnm-glib-aux/)
diff --git a/src/libnmc-base/README.md b/src/libnmc-base/README.md
new file mode 100644
index 0000000000..8038c785a9
--- /dev/null
+++ b/src/libnmc-base/README.md
@@ -0,0 +1,12 @@
+libnmc-base
+===========
+
+A helper library on top of libnm for our clients.
+The "c" in "libnmc-base" stands for clients.
+
+This has no additional dependencies on top of libnm,
+so any client application that uses libnm can statically
+link with this helper at will.
+
+As such, this is very similar in purpose to [../libnm-client-aux-extern](../libnm-client-aux-extern),
+the difference is only in scope.
diff --git a/src/libnmc-setting/README.md b/src/libnmc-setting/README.md
new file mode 100644
index 0000000000..6ed424353a
--- /dev/null
+++ b/src/libnmc-setting/README.md
@@ -0,0 +1,17 @@
+libnmc-setting
+==============
+
+A client library on top of libnm (and libnm-base).
+Like libnmc-base, this is a helper library that a libnm
+client could use.
+
+But its purpose is more specific. It's mainly about providing
+a generic API for handling connection properties. As such, it's
+only used by nmcli and in practice also specific to nmcli.
+
+Theoretically, the API is supposed to be generic, so we could
+imagine another client that uses this beside nmcli.
+
+Like libnm-base, this has a similar purpose and application
+as [../libnm-client-aux-extern/](../libnm-client-aux-extern/),
+the difference is that it's even more specific.
diff --git a/src/libnmt-newt/README.md b/src/libnmt-newt/README.md
new file mode 100644
index 0000000000..386a86cb2d
--- /dev/null
+++ b/src/libnmt-newt/README.md
@@ -0,0 +1,4 @@
+libnmt-newt
+===========
+
+A helper library of UI elements on top of libnewt and libnm, for nmtui.
diff --git a/src/linux-headers/README.md b/src/linux-headers/README.md
new file mode 100644
index 0000000000..382632b995
--- /dev/null
+++ b/src/linux-headers/README.md
@@ -0,0 +1,10 @@
+linux-headers
+=============
+
+Contains a copy of Linux UAPI kernel headers.
+When we build against an older kernel, we may
+still want to unconditionally build against a
+certain version of kernel API.
+
+These headers should be taken without modification
+from Linux.
diff --git a/src/nm-cloud-setup/README.md b/src/nm-cloud-setup/README.md
new file mode 100644
index 0000000000..e484aa20df
--- /dev/null
+++ b/src/nm-cloud-setup/README.md
@@ -0,0 +1,8 @@
+nm-cloud-setup
+==============
+
+A NetworkManager client application that aims to automatically
+configure the network in a cloud environment.
+
+See:
+- `man 8 nm-cloud-setup` ([[www]](https://networkmanager.dev/docs/api/latest/nm-cloud-setup.html))
diff --git a/src/nm-daemon-helper/README.md b/src/nm-daemon-helper/README.md
new file mode 100644
index 0000000000..695f533553
--- /dev/null
+++ b/src/nm-daemon-helper/README.md
@@ -0,0 +1,11 @@
+nm-daemon-helper
+================
+
+A internal helper application that is spawned by NetworkManager
+to perform certain actions.
+
+Currently all it does is doing a reverse DNS lookup, which
+cannot be done by NetworkManager because the operation requires
+to reconfigure the libc resolver (which is a process-wide operation).
+
+This is not directly useful to the user.
diff --git a/src/nm-dispatcher/README.md b/src/nm-dispatcher/README.md
new file mode 100644
index 0000000000..53c8c70945
--- /dev/null
+++ b/src/nm-dispatcher/README.md
@@ -0,0 +1,15 @@
+nm-dispatcher
+=============
+
+Runs as a D-Bus activated, exit-on-idle service to execute
+user scripts (dispatcher scripts) on certain events.
+
+The user does not directly configure this service, it gets
+controlled by NetworkManager. However, the user (or other
+applications) would place scripts in certain directories for
+the dispatcher service to execute them.
+
+The systemd service is called `NetworkManager-dispatcher.service`.
+
+See:
+- `man 8 NetworkManager-dispatcher` ([[www]](https://networkmanager.dev/docs/api/latest/NetworkManager-dispatcher.html))
diff --git a/src/nm-initrd-generator/README.md b/src/nm-initrd-generator/README.md
new file mode 100644
index 0000000000..cc995f5fd1
--- /dev/null
+++ b/src/nm-initrd-generator/README.md
@@ -0,0 +1,12 @@
+nm-initrd-generator
+===================
+
+A command line tool that generates NetworkManager configuration.
+
+This is supposed to be run by dracut in initrd, before NetworkManager
+starts. It parses the kernel command line, generates configuration
+and quits.
+
+See:
+- `man 8 nm-initrd-generator` ([[www]](https://networkmanager.dev/docs/api/latest/nm-initrd-generator.html))
+- `man 7 dracut.cmdline`
diff --git a/src/nm-online/README.md b/src/nm-online/README.md
new file mode 100644
index 0000000000..eaa909f717
--- /dev/null
+++ b/src/nm-online/README.md
@@ -0,0 +1,14 @@
+nm-online
+=========
+
+A small NetworkManager client that blocks until
+NetworkManager is done configuring the interfaces.
+
+This is not very useful to the end user. It is used
+by `NetworkManager-wait-online.service` to determine
+when NetworkManager is done with startup.
+
+See:
+
+- `man 1 nm-online` ([[www]](https://networkmanager.dev/docs/api/latest/nm-online.html))
+- `systemctl cat NetworkManager-wait-online.service`
diff --git a/src/nm-sudo/README.md b/src/nm-sudo/README.md
new file mode 100644
index 0000000000..13fd488185
--- /dev/null
+++ b/src/nm-sudo/README.md
@@ -0,0 +1,21 @@
+nm-sudo
+=======
+
+This is a D-Bus activatable, exit-on-idle service, which
+provides an internal API to NetworkManager daemon.
+
+This has no purpose for the user, it is an implementation detail
+of the daemon.
+
+The purpose is that `nm-sudo` can execute certain operations,
+which NetworkManager process is not allowed to. We want to
+sandbox NetworkManager as much as possible, and nm-sudo provides
+a controlled way to perform some very specific operations.
+
+As such, nm-sudo should still be sandboxed too to only being
+able to execute the operations that are necessary for NetworkManager.
+
+nm-sudo will reject all D-Bus requests that are not originating
+from the current name owner of "org.freedesktop.NetworkManager".
+That is, it is supposed to only reply to NetworkManager daemon
+and as such is not useful to the user directly.
diff --git a/src/nmcli/README.md b/src/nmcli/README.md
new file mode 100644
index 0000000000..a828a762cd
--- /dev/null
+++ b/src/nmcli/README.md
@@ -0,0 +1,13 @@
+nmcli
+=====
+
+The command line user interface of NetworkManager.
+It uses the D-Bus API of NetworkManager (via libnm).
+
+See:
+
+- `man 1 nmcli` ([[www]](https://networkmanager.dev/docs/api/latest/nmcli.html))
+- `man 7 nmcli-examples` ([[www]](https://networkmanager.dev/docs/api/latest/nmcli-examples.html))
+- `man 5 nm-settings-nmcli` ([[www]](https://networkmanager.dev/docs/api/latest/nm-settings-nmcli.html))
+
+Try also with bash-completion!
diff --git a/src/nmtui/README.md b/src/nmtui/README.md
new file mode 100644
index 0000000000..5205f48095
--- /dev/null
+++ b/src/nmtui/README.md
@@ -0,0 +1,15 @@
+nmtui
+=====
+
+The curses-based text user interface of NetworkManager.
+It uses the D-Bus API of NetworkManager (via libnm).
+
+This is a NetworkManager client applications that can
+edit connection profiles and activate them, by providing
+a text UI.
+
+It uses libnewt.
+
+See:
+
+- `man 1 nmtui` ([[www]](https://networkmanager.dev/docs/api/latest/nmtui.html))
diff --git a/src/tests/README.md b/src/tests/README.md
new file mode 100644
index 0000000000..7ffae40ddd
--- /dev/null
+++ b/src/tests/README.md
@@ -0,0 +1,8 @@
+tests
+=====
+
+Contains some unit tests that don't clearly fit a category
+to be placed in a different location.
+
+Maybe a better place should be found and this directory should
+go away.