From a288de4b3d8fc753b1b350d5f620b3a1426aaaf6 Mon Sep 17 00:00:00 2001 From: Thomas Haller Date: Fri, 15 Jan 2021 10:14:34 +0100 Subject: [PATCH] shared: add "shared/README.md" --- Makefile.am | 1 + shared/README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 shared/README.md 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.