[PATCH i-g-t 2/3] meson: gtkdoc support

Daniel Vetter
2017-12-04T20:48:45Z

Bunch of neat improvements:

- xml generates correctly depend upon the test binaries
- no need to re-run autogen.sh when new chapters/functions get added,
all handed by meson

Still one issue:

- the gtkdoc target doesn't depend upon the custom_target yet, hacked
around using build_by_default: true

This is an issue known to upstream already:

https://github.com/mesonbuild/meson/issues/2148

v2: Bump meson version to 0.42, since that's the first release which
adds the build dir when running the gtkdoc tools, and hence allows
including generated files.

v2:
- Undo the bump, it's only needed for generated source files. Other
generated files as input should work with 0.40 already.

- Generate version.xml from version.xml.in, which allows us to keep
the &version; entity.

v3: Add github issue link.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
docs/meson.build | 1 +
.../intel-gpu-tools/generate_description_xml.sh | 44 ++++++++++++
.../intel-gpu-tools/generate_programs_xml.sh | 22 ++++++
docs/reference/intel-gpu-tools/meson.build | 80 ++++++++++++++++++++++
docs/reference/meson.build | 1 +
meson.build | 3 +
meson.sh | 2 +-
tests/meson.build | 6 +-
8 files changed, 157 insertions(+), 2 deletions(-)
create mode 100644 docs/meson.build
create mode 100644 docs/reference/intel-gpu-tools/generate_description_xml.sh
create mode 100755 docs/reference/intel-gpu-tools/generate_programs_xml.sh
create mode 100644 docs/reference/intel-gpu-tools/meson.build
create mode 100644 docs/reference/meson.build

diff --git a/docs/meson.build b/docs/meson.build
new file mode 100644
index 000000000000..ead14c4015d9
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1 @@
+subdir('reference')
diff --git a/docs/reference/intel-gpu-tools/generate_description_xml.sh b/docs/reference/intel-gpu-tools/generate_description_xml.sh
new file mode 100644
index 000000000000..8e39e0c4c289
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/generate_description_xml.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+
+output=$1
+filter=$2
+testlist=$3
+testdir=$(dirname $testlist)
+
+echo "<?xml version=\"1.0\"?>" > $output
+echo " > $output
+echo " \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"" >> $output
+echo "[" >> $output
+echo " <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">" >> $output
+echo " <!ENTITY version SYSTEM \"version.xml\">" >> $output
+echo "]>" >> $output
+echo "<refsect1>" >> $output
+echo " Description " >> $output
+for test in `cat $testlist | tr ' ' '\n' | grep "^$filter" | sort`; do
+ echo "<refsect2 id=\"$test\"> " >> $output;
+ echo "$test" | perl -pe 's/(?<=_)$(KEYWORDS)(?=(_|\W))/ \1<\/acronym>/g' >> $output;
+ echo " " >> $output;
+ testprog=$testdir/$test;
+ ./$testprog --help-description >> $output;
+ echo " " >> $output;
+ if ./$testprog --list-subtests > /dev/null ; then
+ echo "<refsect3> Subtests " >> $output;
+ subtest_list=`./$testprog --list-subtests`;
+ subtest_count=`echo $subtest_list | wc -w`;
+ if [ $subtest_count -gt 100 ]; then
+ echo " This test has over 100 subtests. " >> $output;
+ echo "Run <command>$test</command> --list-subtests to list them. " >> $output;
+ else
+ echo "<simplelist>" >> $output;
+ for subtest in $subtest_list; do
+ echo "<member>" >> $output;
+ echo "$subtest" | perl -pe 's/\b$(KEYWORDS)\b/ \1<\/acronym>/g' >> $output;
+ echo "</member>" >> $output;
+ done;
+ echo "</simplelist>" >> $output;
+ fi;
+ echo "</refsect3>" >> $output;
+ fi;
+ echo "</refsect2>" >> $output;
+done;
+echo "</refsect1>" >> $output
diff --git a/docs/reference/intel-gpu-tools/generate_programs_xml.sh b/docs/reference/intel-gpu-tools/generate_programs_xml.sh
new file mode 100755
index 000000000000..73adc8cc7bfc
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/generate_programs_xml.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+output=$1
+filter=$2
+testlist=$3
+
+echo "<?xml version=\"1.0\"?>" > $output
+echo " > $output
+echo " \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"" >> $output
+echo "[" >> $output
+echo " <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">" >> $output
+echo " <!ENTITY version SYSTEM \"version.xml\">" >> $output
+echo "]>" >> $output
+echo "<refsect1>" >> $output
+echo " Programs " >> $output
+echo "<informaltable pgwide=\"1\" frame=\"none\"><tgroup cols=\"2\"> " >> $output
+for test in `cat $testlist | tr ' ' '\n' | grep "^$filter" | sort`; do
+ echo "<row><entry role=\"program_name\">" >> $output;
+ echo " $test </entry></row>" >> $output;
+done;
+echo " </tgroup></informaltable>" >> $output
+echo "</refsect1>" >> $output
diff --git a/docs/reference/intel-gpu-tools/meson.build b/docs/reference/intel-gpu-tools/meson.build
new file mode 100644
index 000000000000..1c009229aae2
--- /dev/null
+++ b/docs/reference/intel-gpu-tools/meson.build
@@ -0,0 +1,80 @@
+gnome = import('gnome')
+
+ignore_headers = [
+ 'gen6_render.h',
+ 'gen7_media.h',
+ 'gen7_render.h',
+ 'gen8_media.h',
+ 'gen8_render.h',
+ 'gpgpu_fill.h',
+ 'i830_reg.h',
+ 'i915_3d.h',
+ 'i915_pciids.h',
+ 'i915_reg.h',
+ 'igt_edid_template.h',
+ 'intel_reg.h',
+ 'debug.h',
+ 'instdone.h',
+ 'media_fill.h',
+ 'rendercopy.h',
+ 'media_spin.h',
+ 'media_fill_gen9.h',
+ 'gen9_render.h',
+ 'version.h',
+]
+
+test_groups = [
+ 'amdgpu',
+ 'chamelium',
+ 'core',
+ 'debugfs',
+ 'drm',
+ 'drv',
+ 'gem',
+ 'gen3',
+ 'gen7',
+ 'gvt',
+ 'kms',
+ 'meta',
+ 'perf',
+ 'pm',
+ 'prime',
+ 'sw_sync',
+ 'testdisplay',
+ 'tools',
+ 'vgem',
+]
+
+gen_description = find_program('generate_description_xml.sh')
+gen_programs = find_program('generate_programs_xml.sh')
+
+test_list_files = []
+
+foreach group : test_groups
+ programs_xml = 'igt_test_programs_' + group + '_programs.xml'
+ custom_target(programs_xml,
+ output : programs_xml,
+ build_by_default : true,
+ command : [ gen_programs, '@OUTPUT@', group, test_list ])
+
+ description_xml = 'igt_test_programs_' + group + '_description.xml'
+ custom_target(description_xml,
+ output : description_xml,
+ build_by_default : true,
+ depends : test_executables,
+ command : [ gen_description, '@OUTPUT@', group, test_list ])
+endforeach
+
+configure_file(input: 'version.xml.in',
+ output: 'version.xml',
+ install: false, configuration: config)
+
+gnome.gtkdoc('intel-gpu-tools',
+ content_files : ['igt_test_programs.xml'],
+ dependencies : lib_igt,
+ install : true,
+ main_xml : 'intel-gpu-tools-docs.xml',
+ scan_args : '--rebuild-sections',
+ mkdb_args : '--output-format=xml',
+ ignore_headers : ignore_headers,
+ src_dir : inc_for_gtkdoc)
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
new file mode 100644
index 000000000000..944f28a5615e
--- /dev/null
+++ b/docs/reference/meson.build
@@ -0,0 +1 @@
+subdir('intel-gpu-tools')
diff --git a/meson.build b/meson.build
index a564893dc7cb..0950d3c7bbd5 100644
--- a/meson.build
+++ b/meson.build
@@ -28,6 +28,8 @@ endforeach

inc = include_directories('include/drm-uapi', 'lib', '.')

+inc_for_gtkdoc = include_directories('lib')
+
config = configuration_data()

libdrm = dependency('libdrm', version : '>=2.4.82')
@@ -136,3 +138,4 @@ if libdrm_intel.found()
endif
endif
subdir('man')
+subdir('docs')
diff --git a/meson.sh b/meson.sh
index cbf1a9326dbe..ae8e3488d962 100755
--- a/meson.sh
+++ b/meson.sh
@@ -28,7 +28,7 @@ install uninstall:
echo "meson install support not yet completed" && false

docs:
- echo "meson gtkdoc support not yet completed" && false
+ ninja -C build intel-gpu-tools-doc

EOF

diff --git a/tests/meson.build b/tests/meson.build
index 8d8abe062640..088c37ec9b15 100644
--- a/tests/meson.build
+++ b/tests/meson.build
@@ -260,12 +260,14 @@ endif

libexecdir = join_paths(get_option('prefix'), get_option('libexecdir'), 'intel-gpu-tools')

+test_executables = []
+
foreach prog : test_progs
link = []
if prog == 'perf_pmu'
link += lib_igt_perf
endif
- executable(prog, prog + '.c',
+ test_executables += executable(prog, prog + '.c',
dependencies : test_deps,
install_dir : libexecdir,
link_with : link,
@@ -287,6 +289,8 @@ custom_target('testlist',
install : true,
install_dir : pkgdatadir)

+test_list = files('test-list.txt')
+
test_script = find_program('igt_command_line.sh')
foreach prog : test_progs
test('testcase check: ' + prog, test_script,
--
2.15.0