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@xxxxxxxxxx>
> > > ---
> >
> > [...]
> >
> > > +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', 'virkeyname-@0@'.format(name),
> > > + '--subtitle', 'Key name values for @0@'.format(name),
> > > + '@INPUT@', name,
> > > + ],
> > > + capture: true,
> > > + build_by_default: true,
> > > + )
> > > +
> > > + docs_man_files += {
> > > + 'name': 'virkeyname-@0@'.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@xxxxxxx'.format(data['name'])
> > > + html_in_file = '@0@xxxxxxxx'.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/domainstatecapture.rst
vs
https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/manpages/virt-admin.rst.in
vs current state
https://gitlab.com/libvirt/libvirt/-/blob/master/docs/manpages/virt-admin.rst
