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

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.
 

src/README.md

+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 |

src/contrib/README.md

+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.

src/core/README.md

+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.

src/libnm-base/README.md

+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/)

src/libnm-client-aux-extern/README.md

-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.

src/libnm-client-impl/README.md

+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.

src/libnm-client-public/README.md

+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.

src/libnm-client-test/README.md

+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.

src/libnm-glib-aux/README.md

+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.

src/libnm-log-core/README.md

+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.

src/libnm-log-null/README.md

+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.

src/libnm-platform/README.md

+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/)

src/libnm-std-aux/README.md

+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.

src/libnm-systemd-core/README.md

+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.

src/libnm-systemd-shared/README.md

+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.

src/libnm-udev-aux/README.md

+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/)

src/libnmc-base/README.md

+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.

src/libnmc-setting/README.md

+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.

src/libnmt-newt/README.md

+libnmt-newt
+===========
+
+A helper library of UI elements on top of libnewt and libnm, for nmtui.