Re: [libvirt PATCH 335/351] meson: docs/manpages: install man pages

On Wed, Jul 22, 2020 at 19:14:01 +0200, Pavel Hrdina wrote: > On Wed, Jul 22, 2020 at 06:51:58PM +0200, Peter Krempa wrote: > > On Thu, Jul 16, 2020 at 11:59:31 +0200, Pavel Hrdina wrote: > > > Signed-off-by: Pavel Hrdina <phrdina(a)redhat.com&gt; > > > --- > > > > [...] > > > > > +foreach name : keyname_list > > > + rst_file = custom_target( > > > + 'virkeyname-@0@.rst'.format(name), > > > + input: keymap_src_file, > > > + output: 'virkeyname-@0@.rst'.format(name), > > > + command: [ > > > + meson_python_prog, python3_prog, keymap_gen_prog, 'name-docs', > > > + '--lang', 'rst', > > > + '--title', &#39;virkeyname-@0(a)&#39;.format(name), > > > + '--subtitle', 'Key name values for @0(a)&#39;.format(name), > > > + '@INPUT@', name, > > > + ], > > > + capture: true, > > > + build_by_default: true, > > > + ) > > > + > > > + docs_man_files += { > > > + 'name': &#39;virkeyname-@0(a)&#39;.format(name), 'section': '7', 'install': true, 'file': rst_file, > > > + } > > > +endforeach > > > + > > > +docs_man_conf = configuration_data() > > > +docs_man_conf.set('SYSCONFDIR', sysconfdir) > > > +docs_man_conf.set('RUNSTATEDIR', runstatedir) > > > + > > > +foreach data : docs_man_files > > > + rst_in_file = '@0@.rst.in'.format(data['name']) > > > + html_in_file = '@0@.html.in'.format(data['name']) > > > + html_file = '@0@.html'.format(data['name']) > > > + > > > + if data.has_key('file') > > > + rst_file = data['file'] > > > + else > > > + rst_file = configure_file( > > > + input: rst_in_file, > > > + output: '@0@.rst'.format(data['name']), > > > + configuration: docs_man_conf, > > > + ) > > > + endif > > > > I must say it feels weird process these through configure_file. Also > > it's super weird that they've overloaded 3 modes into configure_file. > > > > What's the difference to generator() by the way, since we use it for > > rst->html conversion? I'd expect that we could use configure_file there > > or generator here then. > > The main difference is that configure_file() is done during meson setup > but generator() is executed while building the project. Another main So how does it then handle if the file is modified prior to another build? Is 'ninja' re-running the setup phase?

> difference is that generator() outputs the files into target-private > directory. > > There is a note in documentation: > > "NOTE: Generators should only be used for outputs that will only be used > as inputs for a build target or a custom target. When you use the > processed output of a generator in multiple targets, the generator will > be run multiple times to create outputs for each target. Each output > will be created in a target-private directory @BUILD_DIR@." > > The reason why I went with configure_file is that we create a dictionary > of placeholders that should be replaced in the input file. The other > option would be custom_target() and calling 'sed'. > > The reason why we can use generator() for the rst->html.in conversion is > that the output is used in custom_target to create html from html.in > files. > > > Also is there a possibility where the input and output file will have > > the same name? I'm not very fond of the .rst.in files. > > It should be possible but I prefer using .in suffix to make it clear > that this file needs to be processed. I think we should keep the source files named .rst. The .rst format is good for human consumption even in the pre-processed state. You can also see different behaviour e.g. when viewing them via gitlab web interface: https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/kbase/domainstatecap... vs https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/manpages/virt-admin.... vs current state https://gitlab.com/libvirt/libvirt/-/blob/master/docs/manpages/virt-admin...