Verified Commit ea49b506 authored by Thomas Haller's avatar Thomas Haller
Browse files

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

parent 2f3c2647
Pipeline #385127 failed with stages
in 46 seconds
......@@ -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/
====
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 |
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.
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.
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/)
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.
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.
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.
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.
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.
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.
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.
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/)
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.
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.
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.
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/)
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.
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.
libnmt-newt
===========
A helper library of UI elements on top of libnewt and libnm, for nmtui.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment