shared: add "shared/README.md"

2 files changed, 109 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
index 3ff90639ec..0735882dec 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -729,6 +729,7 @@ EXTRA_DIST += libnm/nm-libnm-aux/README.md
 
 EXTRA_DIST += \
 	shared/nm-glib-aux/tests/meson.build \
+	shared/README.md \
 	$(NULL)
 
 ###############################################################################
diff --git a/shared/README.md b/shared/README.md
new file mode 100644
index 0000000000..ed950fce39
--- /dev/null
+++ b/shared/README.md
@@ -0,0 +1,108 @@
+The "shared/" Directory
+=======================
+
+For NetworkManager we place helper/utility code under "shared/"
+in static libraries. The idea is to avoid code duplication but also
+provide high quality helper functions that simplify the higher layers.
+In NetworkManager there are complicated parts, for example "src/nm-manager.c"
+is huge. On the other hand, this helper code should be simple and easy
+to understand, so that we can build more complex code on top of it.
+
+As we statically link them into our binaries, they are all inherently
+internal API, that means they cannot be part of libnm's (libnm-core's) public API.
+It also means that their API/ABI is not stable.
+
+We don't care these libraries to be minimal and contain only symbols that are
+used by all users. Instead, we expect the linker to throw away unused symbols.
+We achieve this by having a symbol versioning file to hide internal symbols
+(which gives the linker a possibility to remove them if they are unused) and
+compiling with LTO or `"-Wl,--gc-sections"`. Let the tool solve this and not
+manual organization.
+
+Hence these libraries (and their content) are structured this way to satisfy
+the following questions:
+
+1) which dependencies (libraries) do they have? That determines which
+   other libraries can use it. For example:
+
+   - "shared/nm-std-aux" and "shared/nm-glib-aux" both provide general
+     purpose helpers, the difference is that the former has no dependency
+     on glib2 library. Both these libraries are a basic dependency for
+     many other parts of the code.
+
+   - "shared/nm-udev-aux" has a dependency on libudev, it thus cannot
+     be in "shared/nm-glib-aux".
+
+   - client code also has a glib2 dependency. That means it can link with
+     "shared/nm-std-aux" and "shared/nm-glib-aux", but must not link
+     with "shared/nm-udev-aux" (as it has no direct udev dependenct --
+     although clients get it indirectly because libnm already requires
+     it).
+
+2) what is their overall purpose? As said, we rely on the linker to
+   prune unused symbols. But in a few cases we avoid to merge different
+   code in the same library. For example:
+
+   - "shared/nm-glib-aux" and "shared/nm-base" both only have a
+     glib2 dependency. Hence, they could be merged. However we
+     don't do that because "shared/nm-base" is more about NetworkManager
+     specific code, while "shared/nm-glib-aux" is about general
+     purpose helpers.
+
+3) some of these libraries are forked from an upstream. They are kept
+   separate so that we can re-import future upstream versions.
+
+Detail
+======
+
+- `shared/c-list`
+- `shared/c-rbtree`
+- `shared/c-siphash`
+- `shared/c-stdoux`
+- `shared/n-acd`
+- `shared/n-dhcp4`
+
+   These are forked from upstream and imported with git-subtree. They
+   in general only have a libc dependency (or dependencies between each
+   other).
+
+- `shared/nm-std-aux`
+
+   This contains helper code with only a libc dependency.
+   Almost all C code depends on this library.
+
+- `shared/nm-glib-aux`
+
+   Like "shared/nm-std-aux" but also has a glib2 dependency.
+   Almost all glib2 code depends on this library.
+
+- `shared/nm-udev/aux`
+
+   Like "shared/nm-glib-aux" but also has a libudev dependency. It
+   has code related to libudev.
+
+- `shared/systemd`
+
+   These are forked from upstream systemd and imported with a script.
+   Under "shared/systemd/src" we try to keep the sources as close to
+   the original as possible. There is also some adapter code to make
+   it useable for us. It has a dependency on "shared/nm-glib-aux"
+   and will need a logging implementation for "shared/nm-glib-aux/nm-logging-fwd.h".
+
+- `shared/nm-base`
+
+   Depends on "shared/nm-glib-aux" and glib2 but it provides helper code
+   that more about NetworkManager specifc things.
+
+- `shared/nm-log-core`
+
+   This is the logging implementation as used by NetworkManager core ("src/").
+   It is also a dependency for "shared/nm-platform".
+
+- `shared/nm-platform`
+
+   Platform implementation. It depends on "shared/nm-log-core", "shared/nm-base"
+   and "shared/nm-glib-aux".
+
+- Other than that, there are still a few unorganized files/directories here.
+  These should be cleaned up.