merge: branch 'manpages'

build: make manpages a mandatory part of the build

Closes #1653

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/2068

contrib/scripts/nm-ci-run.sh

@@ -167,6 +167,7 @@ meson setup build \
     -D libpsl=false \
     -D vapi=false \
     -D introspection=$_WITH_DOCS \
+    -D man=$_WITH_DOCS \
     -D qt=false \
     -D crypto=$_WITH_CRYPTO \
     -D docs=$_WITH_DOCS \

docs/api/meson.build

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: LGPL-2.1-or-later
 
 if enable_introspection
+  xsltproc = find_program('xsltproc')
+
   settings = 'settings-spec'
   output = settings + '.xml'
 

man/meson.build

@@ -1,29 +1,5 @@
 # SPDX-License-Identifier: LGPL-2.1-or-later
 
-common_ent_file = configure_file(
-  input: 'common.ent.in',
-  output: '@BASENAME@',
-  configuration: data_conf,
-)
-
-xsltproc_options = [
-  xsltproc,
-  '--output', '@OUTPUT@',
-  '--path', meson.current_build_dir(),
-  '--xinclude',
-  '--nonet',
-  '--stringparam', 'man.output.quietly', '1',
-  '--stringparam', 'funcsynopsis.style', 'ansi',
-  '--stringparam', 'man.th.extra1.suppress', '1',
-  '--stringparam', 'man.authors.section.enabled', '0',
-  '--stringparam', 'man.copyright.section.enabled', '0',
-  '--stringparam', 'man.th.title.max.length', '30',
-]
-
-docbook_xls = 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl'
-
-mans_xmls = []
-
 mans = [
   ['NetworkManager', '8'],
   ['NetworkManager-dispatcher', '8'],
@@ -44,24 +20,74 @@ if enable_nm_cloud_setup
   mans += [['nm-cloud-setup', '8']]
 endif
 
-foreach man: mans
-  input = man[0] + '.xml'
-  content_files += join_paths(meson.current_source_dir(), input)
+introspection_mans = [
+  ['nm-settings-keyfile', '5'],
+  ['nm-settings-dbus',    '5'],
+  ['nm-settings-nmcli',   '5'],
+]
 
-  output = '@0@.@1@'.format(man[0], man[1])
+if enable_ifcfg_rh
+  introspection_mans += [['nm-settings-ifcfg-rh', '5']]
+endif
 
-  custom_target(
-    output,
-    input: input,
-    output: output,
-    command: xsltproc_options + [docbook_xls, '@INPUT@'],
-    depend_files: common_ent_file,
-    install: true,
-    install_dir: join_paths(nm_mandir, 'man' + man[1]),
-  )
+built_mans = []
+foreach man: mans + introspection_mans
+  name = man[0] + '.' + man[1]
+  if not fs.exists(name)
+    built_mans = []
+    break
+  endif
+
+  built_mans += name
 endforeach
 
-if enable_introspection
+if enable_introspection or enable_docs
+  common_ent_file = configure_file(
+    input: 'common.ent.in',
+    output: '@BASENAME@',
+    configuration: data_conf,
+  )
+endif
+
+if enable_introspection and (enable_man or enable_docs)
+  xsltproc_options = [
+    find_program('xsltproc'),
+    '--output', '@OUTPUT@',
+    '--path', meson.current_build_dir(),
+    '--xinclude',
+    '--nonet',
+    '--stringparam', 'man.output.quietly', '1',
+    '--stringparam', 'funcsynopsis.style', 'ansi',
+    '--stringparam', 'man.th.extra1.suppress', '1',
+    '--stringparam', 'man.authors.section.enabled', '0',
+    '--stringparam', 'man.copyright.section.enabled', '0',
+    '--stringparam', 'man.th.title.max.length', '30',
+  ]
+
+  docbook_xls = 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl'
+
+  mans_xmls = []
+
+  foreach man: mans
+    input = man[0] + '.xml'
+    content_files += join_paths(meson.current_source_dir(), input)
+
+    output = '@0@.@1@'.format(man[0], man[1])
+
+    # not needed if only html requested
+    if enable_man
+      custom_target(
+        output,
+        input: input,
+        output: output,
+        command: xsltproc_options + [docbook_xls, '@INPUT@'],
+        depend_files: common_ent_file,
+        install: true,
+        install_dir: join_paths(nm_mandir, 'man' + man[1]),
+      )
+    endif
+  endforeach
+
   merge_cmd = files(source_root / 'tools' / 'generate-docs-nm-settings-docs-merge.py')
 
   name = 'dbus'
@@ -124,13 +150,23 @@ if enable_introspection
 
     output = '@0@.@1@'.format(man[0], man[1])
 
-    custom_target(
-      output,
-      input: input,
-      output: output,
-      command: xsltproc_options + [docbook_xls, '@INPUT@'],
-      install: true,
-      install_dir: join_paths(nm_mandir, 'man' + man[1]),
-    )
+    # not needed if only html requested
+    if enable_man
+      custom_target(
+        output,
+        input: input,
+        output: output,
+        command: xsltproc_options + [docbook_xls, '@INPUT@'],
+        install: true,
+        install_dir: join_paths(nm_mandir, 'man' + man[1]),
+      )
+    endif
   endforeach
+# not needed if only html requested
+elif enable_man
+  if built_mans.length() > 0
+    install_man(built_mans)
+  else
+    error('Building manpages requires xsltproc and -Dintrospection=true, and no prebuilt manpages were found. Try building from a release tarball or using -Dman=false.')
+  endif
 endif

meson.build

@@ -12,7 +12,7 @@ project(
     'c_std=gnu11',
     'warning_level=2' # value "2" will add "-Wall" and "-Wextra" to the compiler flags
   ],
-  meson_version: '>= 0.51.0',
+  meson_version: '>= 0.53.0',
 )
 
 nm_name = meson.project_name()
@@ -77,6 +77,7 @@ libnm_version = '@0@.@1@.@2@'.format(current - age, age, revision)
 
 libnm_pkgincludedir = join_paths(nm_includedir, libnm_name)
 
+fs = import('fs')
 gnome = import('gnome')
 i18n = import('i18n')
 pkg = import('pkgconfig')
@@ -89,7 +90,6 @@ po_dir = source_root / 'po'
 top_inc = include_directories('.')
 
 perl = find_program('perl')
-xsltproc = find_program('xsltproc')
 
 check_exports = find_program(join_paths(source_root, 'tools', 'check-exports.sh'))
 
@@ -816,6 +816,7 @@ if enable_nm_cloud_setup
   assert(jansson_dep.found(), 'nm-cloud-setup requires jansson library. Use -Dnm_cloud_setup=false to disable it')
 endif
 
+enable_man = get_option('man')
 enable_docs = get_option('docs')
 
 more_asserts = get_option('more_asserts')
@@ -964,38 +965,6 @@ data_conf.set('nmstatedir',                              nm_pkgstatedir)
 data_conf.set('sbindir',                                 nm_sbindir)
 data_conf.set('sysconfdir',                              nm_sysconfdir)
 
-# check if we can build setting property documentation
-'''
-build_docs=no
-if test -n "$INTROSPECTION_MAKEFILE"; then
-  # If g-i is installed we know we have python, but we might not have pygobject
-  if ! "$PYTHON" -c 'from gi.repository import GObject' >& /dev/null; then
-    AC_MSG_ERROR(["--enable-introspection aims to build the settings documentation. This requires GObject introspection for python (pygobject)])
-  fi
-
-  AC_PATH_PROG(PERL, perl)
-  if test -z "$PERL"; then
-    AC_MSG_ERROR([--enable-introspection requires perl])
-  fi
-  AC_PATH_PROG(XSLTPROC, xsltproc)
-  if test -z "$XSLTPROC"; then
-    AC_MSG_ERROR([--enable-introspection requires xsltproc])
-  fi
-
-  have_introspection=yes
-  if test "$enable_gtk_doc" = "yes"; then
-    build_docs=yes
-  fi
-else
-  if test "$enable_gtk_doc" = "yes"; then
-    # large parts of the documentation require introspection/pygobject to extract
-    # the documentation out of the source files. You cannot enable gtk-doc without alone.
-    AC_MSG_ERROR(["--with-gtk-doc requires --enable-introspection"])
-  fi
-  have_introspection=no
-fi
-'''
-
 content_files = []
 
 subdir('introspection')
@@ -1033,9 +1002,14 @@ if enable_qt != 'false'
   endif
 endif
 
+# The man/ directory builds a couple targets needed by the docs build too.
+# If we build with docs but no man, then enter the subdir and only build
+# some targets.
+if enable_docs or enable_man
+  subdir('man')
+endif
 if enable_docs
   assert(enable_introspection, '-Ddocs=true requires -Dintrospection=true')
-  subdir('man')
   subdir('docs')
   meson.add_dist_script(
     'tools/meson-dist-data.sh',
@@ -1086,7 +1060,7 @@ meson.add_install_script(
   nm_pkgstatedir,
   nm_mandir,
   nm_sysconfdir,
-  enable_docs ? '1' : '0',
+  enable_man ? '1' : '0',
   enable_ifcfg_rh ? '1' : '0',
   enable_nm_cloud_setup ? '1' : '0',
   install_systemdunitdir ? '1' : '0',

meson_options.txt

@@ -67,6 +67,7 @@ option('config_dhcp_default', type: 'combo', choices: ['dhclient', 'dhcpcd', 'in
 option('introspection', type: 'boolean', value: true, description: 'Enable introspection for this build')
 option('vapi', type : 'combo', choices : ['auto', 'true', 'false'], description: 'build Vala bindings')
 option('docs', type: 'boolean', value: false, description: 'use to build documentation')
+option('man', type: 'boolean', value: true, description: 'Install manpages')
 option('tests', type: 'combo', choices: ['yes', 'no', 'root'], value: 'yes', description: 'Build NetworkManager tests')
 option('firewalld_zone', type: 'boolean', value: true, description: 'Install and use firewalld zone for shared mode')
 option('more_asserts', type: 'string', value: 'auto', description: 'Enable more assertions for debugging (0 = no, 100 = all, default: auto)')

tools/meson-post-install.sh

@@ -7,7 +7,7 @@ nm_pkglibdir="$4"
 nm_pkgstatedir="$5"
 nm_mandir="$6"
 nm_sysconfdir="$7"
-enable_docs="$8"
+enable_man="$8"
 enable_ifcfg_rh="$9"
 enable_nm_cloud_setup="${10}"
 install_systemdunitdir="${11}"
@@ -40,7 +40,7 @@ done
 mkdir -p "${DESTDIR}${nm_pkgstatedir}"
 chmod 0700 "${DESTDIR}${nm_pkgstatedir}"
 
-if [ "$enable_docs" = 1 ]; then
+if [ "$enable_man" = 1 ]; then
 
     for alias in nmtui-connect nmtui-edit nmtui-hostname; do
         ln -fn "${DESTDIR}${nm_mandir}/man1/nmtui.1" "${DESTDIR}${nm_mandir}/man1/${alias}.1"
@@ -58,4 +58,3 @@ if [ "$enable_nm_cloud_setup" = 1 -a "$install_systemdunitdir" = 1 ]; then
     ln -sfn '../pre-up.d/90-nm-cloud-setup.sh' "${DESTDIR}${nm_pkglibdir}/dispatcher.d/no-wait.d/90-nm-cloud-setup.sh"
     ln -sfn 'no-wait.d/90-nm-cloud-setup.sh' "${DESTDIR}${nm_pkglibdir}/dispatcher.d/90-nm-cloud-setup.sh"
 fi
-