Support managing the loopback interface through NM as the users want to
set the proper mtu for loopback interface when forwarding the packets.
Additionally, the IP addresses, DNS, route and routing rules are also
allowed to configure for the loopback connection profiles.
https://bugzilla.redhat.com/show_bug.cgi?id=2060905
Turns out automake doesn't like either that we add dependencies to a
target conditionally. Not sure why, but it's a tasteless thing to do
nevertheless:
gtk-doc.make:174: warning: $(DOC_MAIN_SGML_FILE) was already defined in condition BUILD_DOCS, which is included in condition TRUE ...
docs/api/Makefile.am:112: 'gtk-doc.make' included from here
docs/api/Makefile.am:14: ... '$(DOC_MAIN_SGML_FILE)' previously defined here
In any case, the dependency is wrong in the first place -- the source
document doesn't depend on other source. The target (which is a stamp
file, since the xslt processor produces multiple files) does! Moreover,
there's a dependency of the stamp file on $(content_files) already, so
including GENERATED_FILES (like we already do) in content_files should
be sufficient.
While at that, deal with other not-so-nice things; don't extend "all"
target needlessly and don't define a target conditionally.
NetworkManager-wait-online is a constant source of confusion,
as it seems to delay the boot (when it's often just the messenger
or either a network problem, a NetworkManager misconfiguration
or a misconfiguration of other systemd services).
Try to clear that up with a manual page.
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1130
"libnm-core/" is rather complicated. It provides a static library that
is linked into libnm.so and NetworkManager. It also contains public
headers (like "nm-setting.h") which are part of public libnm API.
Then we have helper libraries ("libnm-core/nm-libnm-core-*/") which
only rely on public API of libnm-core, but are themself static
libraries that can be used by anybody who uses libnm-core. And
"libnm-core/nm-libnm-core-intern" is used by libnm-core itself.
Move "libnm-core/" to "src/". But also split it in different
directories so that they have a clearer purpose.
The goal is to have a flat directory hierarchy. The "src/libnm-core*/"
directories correspond to the different modules (static libraries and set
of headers that we have). We have different kinds of such modules because
of how we combine various code together. The directory layout now reflects
this.
"nm-settings-docs-nmcli.xml" will be generated by a tool that depends on
"clients/common/". The file should thus not be in libnm directory, otherwise
there is a circular dependency.
Move the file to "man/" directory.
For consistency, also move "nm-settings-docs-dbus.xml". Note that we
cannot move "nm-settings-docs-gir.xml" to "man/", because that one is
needed for building clients.
A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.
Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.
There are the following aspects:
- "dbus"
- "keyfile"
- "ifcfg-rh"
- "nmcli"
For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.
Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.
"nm-settings-docs-dbus.xml" is "nm-settings-docs-gir.xml" merged with
"nm-property-infos-dbus.xml". The name should reflect that, also because
we will get more files with this naming scheme.
"man/nm-settings%.xml" really should depend on "common.ent".
The reason is that XSL files like "man/nm-settings.xsl" include
"common.ent".
The previous code already tried to express that, but for some
reasons this dependency was not honored. Fix that.
However, that uncovers another problem with gtk-doc.make. If we do
that without the workaround for "docs/api/Makefile.am", then
$ ./autogen.sh && make V=1 SHELL='sh -x' distcheck
breaks.
The reason is not clear to me. The new dependency leads to rebuild
"man/nm-settings-keyfile.xml". But that is worse, somehow the file
"$(top_srcdir)/man/nm-settings-keyfile.xml" ends up being read-only.
Afterwards, gtk-doc.make does
setup-build.stamp:
-$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ;
then \
files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
if test "x$$files" != "x" ; then \
for file in $$files ; do \
destdir=`dirname $(abs_builddir)/$$file`; \
test -d "$$destdir" || mkdir -p "$$destdir"; \
test -f $(abs_srcdir)/$$file && \
cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true;
\
done; \
fi; \
fi
$(AM_V_at)touch setup-build.stamp
so that the files in build dir are also read-only. Then, make distcheck
goes ahead and builds the files once again, which fails.
You are welcome to understand why this workaround is necessary. Please
then create a better fix.
What's actually needed here is an explaination of how the license
applies along with the explanation where to find the full text.
Also, the libnm documentation was lacking the licensing information
altogether. Fix fixes it too.
nm-initrd-generator scans the command line for options relevant to network
configuration and creates configuration files for an early instance of
NetworkManager run from the initial ramdisk during early boot.
Although it is possible to generate distributable files on meson
since version 0.41 by using the `ninja dist` command, autotools does
different things that end up creating a different distributable
file.
meson build files have been added to autotools build files as
distributable files, so the whole meson port would also be
distributed.
https://mail.gnome.org/archives/networkmanager-list/2018-January/msg00047.html
Building the man pages via xsltproc requires "docbook.xsl"
which is part of docbook.
Previously, we would build the man pages solely based on
"--enable-introspection", which checks for the presence of
xsltproc, but not docbook. This can lead to build failure
when docbook is not available, but "--enable-introspection"
is given.
Instead of adding yet another configure option to fine-tune
and say "--with-docbook --disable-gtk-doc", just simplify it.
Now, documentation (both man pages and setting docs) will be generated
with "--enable-gtk-doc" and "--enable-introspection".
If the documentation is not about to be generated, pre-generated docs
will be installed if they are available. That is commonly the case
with a source tarball, but not with a git checkout.
Finally, if documentation is nither generated nor pre-generated,
no documentation will be installed *duh*.
This removes the possibility to treat man pages separate from settings
docs. Now you either generate both, install both pre-generated, or don't
get any of them.
https://bugzilla.gnome.org/show_bug.cgi?id=778551
- `make dist` requires --enable-gtk-doc --enable-introspection --with-libnm-glib
- --enable-gtk-doc requires --enable-introspection
- --with-nmcli requires either --enable-introspection or pregenerated
settings-docs.c files from the dist tarball. It does not require
--enable-gtk-doc.
There is a bit of a problem in that --enable-introspection requires
now xsltproc. However, gobject-introspection does itself not depend
on xsltproc. So, more correct might be a special --enable-doc argument,
that combines --enable-introspection --with-xsltproc. Anyway, that
seems to make it more complicated then it already is so just implicitly
(and surprisingly?) require xsltproc with --enable-introspection.
https://bugzilla.gnome.org/show_bug.cgi?id=775003
This makes it easier to install the files with proper names.
Also, it makes the makefile rules slightly simpler.
Lastly, the documentation is now generated into docs/api, which makes it
possible to get rid of the awkward relative file names in docbook.
Otherwise the types links would be dangling or resolved to slightly
irrelevant documentation in libnm or completely irrelevant documentation
in libnm-util.
May use a lot of improvement (actually documenting the names and
objects that use the interfaces in question), but at least this looks a
lot better on developer.gnome.org.
When compiling NetworkManager with --enable-gtk-doc outside the
source tree, the generated documents are slightly different from
those generated in tree. This patch fixes that missed COPYING file in
$(top_builddir) and adds $(top_builddir)/libnm-util to DOC_SOURCE_DIR.
https://bugzilla.gnome.org/show_bug.cgi?id=742139
Signed-off-by: You-Sheng Yang <vicamo@gmail.com>
Move the settings/plugins doc generation from libnm-util to
libnm-core, since libnm-util isn't being updated for all new
properties.
With this commit, the keyfile and ifcfg-rh documentation is basically
unchanged, except that deprecated properties are now gone, and new
properties have been added, and the sections are in a different order.
(generate-plugin-docs.pl just outputs the settings in Makefile order,
and they were unsorted in libnm-util, but are sorted in libnm-core).
The settings documentation used for nm-settings.5, the D-Bus API docs,
and the nmcli help is changed a bit more at this point, and mostly for
the worse, since the libnm-core setting properties don't match up with
the D-Bus API as well as the libnm-util ones do. To be fixed...
(I also removed the "plugins docs" line in each plugin docs comment
block while moving them, since those blocks will be used for more than
just plugins soon, and it's sort of obvious anyway.)
docs/api/settings-spec.xml was accidentally not getting disted,
because gtk-doc.make explicitly removes all DISTCLEANFILES from
distdir. However, it doesn't actually make sense for the settings docs
files to be in DISTCLEANFILES anyway; they were put there rather than
CLEANFILES (IIRC) so that "make clean" in a tarball build wouldn't
delete them and break things. But the right fix is to just make them
only be in CLEANFILES when BUILD_SETTING_DOCS is true, and not ever
get deleted otherwise.
Also adjust the build rules to ensure that the generated docs don't
get rebuilt in tarball builds, since that can cause problems when
building from a read-only source tree, etc.
Meanwhile, in an unrelated but also fatal bug, configure.ac's check
for if the generated docs were already present never got updated for
the cli/src -> clients/cli move, and so even if we had been disting
settings-spec.xml, configure would still think that the tarball didn't
have all of the generated docs in it, so SETTING_DOCS_AVAILABLE would
be set false and none of the generated docs would get used.
https://bugzilla.gnome.org/show_bug.cgi?id=740035
Certain build configurations (like --enable-gtk-doc
--disable-introspection) were broken with respect to nm-setting-docs.
Fix this. Also, we don't require just gobject-introspection, we need
pygobject specifically as well.
dist tarballs shouldn't ever be released without the documentation,
and this allows us to build the tarballs with pre-generated docs
that get installed on the end system, but don't need to be built
there. So the end system doesn't need gtk-doc installed, only
the dist system does.
https://bugzilla.gnome.org/show_bug.cgi?id=700093
"./autogen.sh --enable-doc && make" produced this error:
warning: failed to load external entity "../settings-spec.xml"
../network-manager-docs.xml:57: element include: XInclude error : could not load ../settings-spec.xml, and no fallback was found
Removing settings-spec.xml from $(content_files) made the file non-DISTed but it
also removed the file as a dependency for html-build.stamp that also runs
cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
and $(DOC_MAIN_SGML_FILE) includes settings-spec.xml.
Fix that by making $(DOC_MAIN_SGML_FILE) dependent on setting-spec.xml.
The generated settings-spec.xml should not be DIST-ed because it's
regenerated every time libnm-util changes. That meants it gets
rebuilt during 'make' even from a dist tarball. Thus, it shouldn't
be part of the dist tarball itself.
In addition, settings-spec.html shouldn't be included in
$(content_files) becuase this is added to EXTRA_DIST by gtk-doc.make.
Since generate-settings-spec.c the move from docs/api/ to tools/,
this started breaking distcheck even though the original Makefile
rules were wrong too.
The refentry xml is used to generate manual page with settings description.
The invocation is:
generate-settings-spec <type> <output file> [<type> <output file>]
where <type> is "book" or "refentry"
