Merge branch 'wip/doc-build' into 'main'

doc: Refactor the build system for complete build dir docs

See merge request wayland/wayland!496

.gitlab-ci.yml

@@ -78,11 +78,10 @@ workflow:
   variables:
     BUILD_OS: debian
     FDO_DISTRIBUTION_VERSION: bookworm
-    FDO_DISTRIBUTION_PACKAGES: 'build-essential pkg-config libexpat1-dev libffi-dev libxml2-dev doxygen graphviz xmlto xsltproc docbook-xsl python3-pip python3-setuptools ninja-build'
-    FDO_DISTRIBUTION_EXEC: 'pip3 install --break-system-packages meson~=0.57.2'
+    FDO_DISTRIBUTION_PACKAGES: 'build-essential pkg-config libexpat1-dev libffi-dev libxml2-dev doxygen graphviz xmlto xsltproc docbook-xsl meson ninja-build'
     # bump this tag every time you change something which requires rebuilding the
     # base image
-    FDO_DISTRIBUTION_TAG: "2025-01-21.1"
+    FDO_DISTRIBUTION_TAG: "2025-10-28.1"
 
 .debian-x86_64:
   extends:
@@ -223,11 +222,10 @@ armv7-debian-container_prep:
     - .ci-rules
   stage: "Build and test"
   script:
-    - cd "$BUILDDIR"
-    - meson --prefix="$PREFIX" -Dicon_directory=/usr/share/X11/icons --fatal-meson-warnings -Dwerror=true ${MESON_BUILD_TYPE} ..
-    - ninja -k0 -j${FDO_CI_CONCURRENT:-4}
-    - meson test --num-processes ${FDO_CI_CONCURRENT:-4}
-    - ninja clean
+    - meson setup $BUILDDIR --prefix="$PREFIX" -Dicon_directory=/usr/share/X11/icons --fatal-meson-warnings -Dwerror=true ${MESON_BUILD_TYPE}
+    - ninja -C $BUILDDIR -k0 -j${FDO_CI_CONCURRENT:-4}
+    - meson test -C $BUILDDIR --num-processes ${FDO_CI_CONCURRENT:-4}
+    - ninja -C $BUILDDIR clean
   artifacts:
     name: wayland-$CI_JOB_NAME
     when: always
@@ -250,7 +248,7 @@ armv7-debian-container_prep:
     # the workspace to see details about the failed tests.
     - |
       set +e
-      /app/vmctl exec "pkg info; cd $CI_PROJECT_NAME ; meson $BUILDDIR --prefix=$PREFIX $MESON_BUILD_TYPE $MESON_ARGS && ninja -C $BUILDDIR -j${FDO_CI_CONCURRENT:-4}"
+      /app/vmctl exec "pkg info; cd $CI_PROJECT_NAME ; meson setup $BUILDDIR --prefix=$PREFIX $MESON_BUILD_TYPE $MESON_ARGS && ninja -C $BUILDDIR -j${FDO_CI_CONCURRENT:-4}"
       /app/vmctl exec "meson test --print-errorlogs -C $BUILDDIR --num-processes ${FDO_CI_CONCURRENT:-4}" && touch .tests-successful
       set -ex
       scp -r vm:$BUILDDIR/meson-logs .

doc/doxygen/meson.build

@@ -1,16 +1,5 @@
 # Here be dragons
 
-dot_gv = {
-	'wayland-architecture': files('dot/wayland-architecture.gv'),
-	'x-architecture': files('dot/x-architecture.gv'),
-}
-
-# This is a workaround for Meson's custom_target() directive, which
-# currently does not support outputs pointing to a sub-directory
-# XXX: try turning these into maps, so they can be indexed with picture name
-dot_png = []
-dot_map = []
-
 doxygen_conf = configuration_data()
 doxygen_conf.set('VERSION', meson.project_version())
 doxygen_conf.set('top_builddir', meson.project_build_root())
@@ -91,7 +80,6 @@ foreach f_name, sections: formats
 			],
 			input: s_files,
 			output: '@0@.stamp'.format(t_name),
-			depends: [dot_png, dot_map],
 			build_by_default: true,
 		)
 	endforeach

doc/doxygen/xml/Client/meson.build

@@ -11,7 +11,6 @@ tgt = custom_target(
 	],
 	input: [ shared_files, client_files ],
 	output: [ 'combine.xslt', 'index.xml' ],
-	depends: [dot_png, dot_map]
 )
 
 doxygen_Client_combine_xslt = tgt[0]

doc/doxygen/xml/Server/meson.build

@@ -11,7 +11,6 @@ tgt = custom_target(
 	],
 	input: [ shared_files, server_files ],
 	output: [ 'combine.xslt', 'index.xml' ],
-	depends: [dot_png, dot_map]
 )
 
 doxygen_Server_combine_xslt = tgt[0]

doc/doxygen/xml/meson.build

@@ -1,22 +1,2 @@
-# dot_png: list of PNG targets
-# dot_map: list of MAP targets
-foreach name, infile: dot_gv
-	dot_png += custom_target(
-		name + '.png',
-		command: [ dot, '-Tpng', '-o@OUTPUT@', '@INPUT@' ],
-		input: infile,
-		output: name + '.png',
-		install: true,
-		install_dir: join_paths(publican_install_prefix, publican_html_dir, 'images')
-	)
-
-	dot_map += custom_target(
-		name + '.map',
-		command: [ dot, '-Tcmapx_np', '-o@OUTPUT@', '@INPUT@' ],
-		input: infile,
-		output: name + '.map',
-	)
-endforeach
-
 subdir('Client')
 subdir('Server')

doc/publican/html/css/meson.build

@@ -0,0 +1,14 @@
+foreach src : files([
+	'brand.css',
+	'common.css',
+	'default.css',
+	'epub.css',
+	'print.css',
+])
+	name = fs.name(src)
+	publican_inputs += fs.copyfile(
+		name,
+		install: true,
+		install_dir: publican_install_prefix + '/html/css',
+	)
+endforeach

doc/publican/html/images/meson.build

@@ -0,0 +1,28 @@
+foreach src : files([
+	'icon.svg',
+	'wayland.png',
+])
+	name = fs.name(src)
+	publican_inputs += fs.copyfile(
+		name,
+		install: true,
+		install_dir: publican_install_prefix + '/html/images',
+	)
+endforeach
+
+foreach src : files([
+	'wayland-architecture.gv',
+	'x-architecture.gv',
+])
+	input = fs.name(src)
+	output = fs.stem(src) + '.png'
+
+	publican_inputs += custom_target(
+		input + '.png',
+		command: [ dot, '-Tpng', '-o@OUTPUT@', '@INPUT@' ],
+		input: input,
+		output: output,
+		install: true,
+		install_dir: publican_install_prefix + '/html/images',
+	)
+endforeach

doc/publican/meson.build

@@ -1,6 +1,92 @@
-merge_mapcoords_xsl = files('merge-mapcoords.xsl')
+proto_to_docboox_xsl = files('xsl/protocol-to-docbook.xsl')
+proto_iface_to_docboox_xsl = files('xsl/protocol-interfaces-to-docbook.xsl')
+merge_mapcoords_xsl = files('xsl/merge-mapcoords.xsl')
+to_publican_xsl = files('xsl/doxygen-to-publican.xsl')
 
-subdir('sources')
+publican_inputs = []
+
+foreach src : files([
+	'Wayland.xml', # must be first in publican_inputs
+	'Wayland.ent',
+	'Book_Info.xml',
+	'Author_Group.xml',
+	'Foreword.xml',
+	'Preface.xml',
+	'Revision_History.xml',
+	'Protocol.xml',
+	'Xwayland.xml',
+	'Compositors.xml',
+	'Color.xml',
+	'Client.xml',
+	'Server.xml',
+])
+	name = fs.name(src)
+	publican_inputs += fs.copyfile(name)
+endforeach
+
+publican_inputs += custom_target(
+	'ProtocolSpec.xml',
+	command: [ xsltproc, '-o', '@OUTPUT@', proto_to_docboox_xsl, '@INPUT@' ],
+	input: wayland_protocol_xml,
+	output: 'ProtocolSpec.xml'
+)
+
+publican_inputs += custom_target(
+	'ProtocolInterfaces.xml',
+	command: [ xsltproc, '-o', '@OUTPUT@', proto_iface_to_docboox_xsl, '@INPUT@' ],
+	input: wayland_protocol_xml,
+	output: 'ProtocolInterfaces.xml'
+)
+
+ClientAPI_combined = custom_target(
+	'ClientAPI-combined',
+	command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ],
+	input: [ doxygen_Client_combine_xslt, doxygen_Client_index_xml ],
+	output: 'ClientAPI-combined.xml'
+)
+
+publican_inputs += custom_target(
+	'ClientAPI.xml',
+	command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Client', to_publican_xsl, '@INPUT@' ],
+	input: ClientAPI_combined,
+	output: 'ClientAPI.xml'
+)
+
+ServerAPI_combined = custom_target(
+	'ServerAPI-combined',
+	command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ],
+	input: [ doxygen_Server_combine_xslt, doxygen_Server_index_xml ],
+	output: 'ServerAPI-combined.xml'
+)
+
+publican_inputs += custom_target(
+	'ServerAPI.xml',
+	command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Server', to_publican_xsl, '@INPUT@' ],
+	input: ServerAPI_combined,
+	output: 'ServerAPI.xml'
+)
+
+foreach src : files([
+	'Architecture.xml',
+	'Introduction.xml'
+])
+	name = fs.name(src)
+	publican_inputs += custom_target(
+		name,
+		command: [
+			xsltproc,
+			'-o', '@OUTPUT@',
+			'--stringparam', 'basedir', '.',
+			merge_mapcoords_xsl,
+			'@INPUT@',
+		],
+		input: [name],
+		output: [name],
+	)
+endforeach
+
+subdir('html/css')
+subdir('html/images')
 
 custom_target(
 	'Wayland-docbook-html',
@@ -14,19 +100,11 @@ custom_target(
 		'--stringparam', 'html.stylesheet=css/default.css',
 		'-o', '@OUTPUT@',
 		'html',
-		'@INPUT@'
-	],
-	input: publican_processed_main,
-	output: publican_html_dir,
-	depend_files: publican_copied_sources,
-	depends: [
-		publican_processed_targets,
-		ClientAPI_xml,
-		ServerAPI_xml,
-		ProtocolSpec_xml,
-		ProtocolInterfaces_xml
+		'@INPUT0@'
 	],
+	input: publican_inputs,
+	output: 'html',
 	build_by_default: true,
 	install: true,
-	install_dir: publican_install_prefix
+	install_dir: publican_install_prefix,
 )

doc/publican/sources/meson.build

@@ -1,114 +0,0 @@
-ProtocolSpec_xml = custom_target(
-	'ProtocolSpec.xml',
-	command: [ xsltproc, '-o', '@OUTPUT@', files('../protocol-to-docbook.xsl'), '@INPUT@' ],
-	input: wayland_protocol_xml,
-	output: 'ProtocolSpec.xml'
-)
-
-ProtocolInterfaces_xml = custom_target(
-	'ProtocolInterfaces.xml',
-	command: [ xsltproc, '-o', '@OUTPUT@', files('../protocol-interfaces-to-docbook.xsl'), '@INPUT@' ],
-	input: wayland_protocol_xml,
-	output: 'ProtocolInterfaces.xml'
-)
-
-ClientAPI_combined = custom_target(
-	'ClientAPI-combined',
-	command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ],
-	input: [ doxygen_Client_combine_xslt, doxygen_Client_index_xml ],
-	output: 'ClientAPI-combined.xml'
-)
-
-to_publican_xsl = files('../doxygen-to-publican.xsl')
-
-ClientAPI_xml = custom_target(
-	'ClientAPI.xml',
-	command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Client', to_publican_xsl, '@INPUT@' ],
-	input: ClientAPI_combined,
-	output: 'ClientAPI.xml'
-)
-
-ServerAPI_combined = custom_target(
-	'ServerAPI-combined',
-	command: [ xsltproc, '-o', '@OUTPUT@', '@INPUT@' ],
-	input: [ doxygen_Server_combine_xslt, doxygen_Server_index_xml ],
-	output: 'ServerAPI-combined.xml'
-)
-
-ServerAPI_xml = custom_target(
-	'ServerAPI.xml',
-	command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'which', 'Server', to_publican_xsl, '@INPUT@' ],
-	input: ServerAPI_combined,
-	output: 'ServerAPI.xml'
-)
-
-
-publican_sources = [
-	'Wayland.ent',
-	# 'Wayland.xml', # handled specially
-	'Book_Info.xml',
-	'Author_Group.xml',
-	'Foreword.xml',
-	'Preface.xml',
-	'Revision_History.xml',
-	'Protocol.xml',
-	'Xwayland.xml',
-	'Compositors.xml',
-	'Color.xml',
-	'Client.xml',
-	'Server.xml'
-]
-
-publican_processed_main = configure_file(
-	input: 'Wayland.xml',
-	output: 'Wayland.xml',
-	copy: true
-)
-
-publican_copied_sources = []
-foreach src: publican_sources
-	publican_copied_sources += configure_file(
-		input: src,
-		output: src,
-		copy: true
-	)
-endforeach
-
-publican_processed_sources = [
-	'Architecture.xml',
-	'Introduction.xml'
-]
-
-publican_processed_targets = []
-foreach src: publican_processed_sources
-	publican_processed_targets += custom_target(
-		src,
-		command: [ xsltproc, '-o', '@OUTPUT@', '--stringparam', 'basedir', '.', merge_mapcoords_xsl, '@INPUT@' ],
-		input: src,
-		output: src
-	)
-endforeach
-
-publican_css_sources = files([
-	'css/brand.css',
-	'css/common.css',
-	'css/default.css',
-	'css/epub.css',
-	'css/print.css'
-])
-
-install_data(
-	publican_css_sources,
-	install_dir: join_paths(publican_install_prefix, publican_html_dir, 'css')
-)
-
-publican_img_sources = files([
-	'images/icon.svg',
-	'images/wayland.png',
-	'images/xwayland-architecture.png'
-])
-
-install_data(
-	publican_img_sources,
-	install_dir: join_paths(publican_install_prefix, publican_html_dir, 'images')
-)

meson.build

@@ -2,13 +2,17 @@ project(
 	'wayland', 'c',
 	version: '1.24.90',
 	license: 'MIT',
-	meson_version: '>= 0.57.0',
+	meson_version: '>= 0.64.0',
 	default_options: [
 		'warning_level=2',
 		'buildtype=debugoptimized',
 		'c_std=c99',
 	]
 )
+
+fs = import('fs')
+pkgconfig = import('pkgconfig')
+
 wayland_version = meson.project_version().split('.')
 
 config_h = configuration_data()
@@ -106,8 +110,6 @@ configure_file(
 	configuration: config_h,
 )
 
-pkgconfig = import('pkgconfig')
-
 wayland_protocol_xml = files('protocol/wayland.xml')
 
 root_inc = include_directories('.')

src/meson.build

@@ -66,7 +66,6 @@ if get_option('scanner')
 		variables: [
 			'datarootdir=' + join_paths('${prefix}', get_option('datadir')),
 			'pkgdatadir=' + join_paths('${pc_sysrootdir}${datarootdir}', meson.project_name()),
-			'bindir=' + join_paths('${prefix}', get_option('bindir')),
 			'wayland_scanner=${bindir}/wayland-scanner'
 		],
 		filebase: 'wayland-scanner'