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

Petri Latvala
2017-12-05T09:43:02Z

On Mon, Dec 04, 2017 at 09:48:36PM +0100, Daniel Vetter wrote:
> 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')
> +

This breaks building from a clean checkout. files() can only be used
for files that already exist.

You can use the object from custom_target() directly for
test-list.txt:

--- a/tests/meson.build
+++ b/tests/meson.build
@@ -280,14 +280,12 @@ test_progs += 'testdisplay'
pkgdatadir = join_paths(get_option('prefix'), get_option('datadir'),
'intel-gpu-tools')

gen_testlist = find_program('generate_testlist.sh')
-custom_target('testlist',
+test_list = custom_target('testlist',
output : 'test-list.txt',
command : [ gen_testlist, '@OUTPUT@', test_progs ],
install : true,
install_dir : pkgdatadir)

--
Petri Latvala