From: Bruce Richardson <bruce.richardson@intel.com>
To: Jerin Jacob <jerinjacobk@gmail.com>
Cc: <dev@dpdk.org>
Subject: Re: [PATCH] doc: build manpages as well as html output
Date: Tue, 6 Jun 2023 11:18:50 +0100 [thread overview]
Message-ID: <ZH8ICsTsjKmQqpvT@bricha3-MOBL.ger.corp.intel.com> (raw)
In-Reply-To: <CALBAE1Ob=9EY+nCmbk5rxo9xSPRm2=qmQ_M=uCrPviLgrwOTbQ@mail.gmail.com>
On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote:
> On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> > > On Thu, Jun 1, 2023 at 9:08 PM Bruce Richardson
> > > <bruce.richardson@intel.com> wrote:
> > > >
> > > > Doxygen can produce manpage output as well as html output for the DPDK
> > > > APIs. However, we need to do this as a separate task as the manpage
> > > > output needs to be placed in a different location post-install to the
> > > > html output (/usr/local/share/man vs /usr/local/share/doc/).
> > > >
> > > > Changes required are:
> > > > * Add configurable options for manpage output and html output to the
> > > > doxygen config template. (Remove option for html output path as it's
> > > > always "html")
> > > > * Modify API meson.build file to configure two separate doxygen config
> > > > files, for HTML and manpages respectively.
> > > > * Change doxygen wrapper script to have separate output log files for
> > > > the manpage and HTML jobs, to avoid conflicts
> > > > * Add "custom_targets" to meson.build file to build the HTML pages and
> > > > the manpages, with individual install locations for each.
> > > > * Where supported by meson version, call "mandb" post-install to update
> > > > the man database to ensure the new manpages can be found.
> > > >
> > > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > >
> > > > +
> > > > +mandb = find_program('mandb', required: false)
> > > > +if mandb.found() and get_option('enable_docs') and meson.version().version_compare('>=0.55.0')
> > > > + meson.add_install_script(mandb)
> > >
> > > It does not look like just executing mandb it is adding these man
> > > pages to database
> > >
> > > log:
> > > Running custom install script '/usr/bin/mandb'
> > > Purging old database entries in /home/jerin/.local/man...
> > > Processing manual pages under /home/jerin/.local/man...
> > > Checking for stray cats under /home/jerin/.local/man...
> > > Processing manual pages under /home/jerin/.local/man/cat1...
> > > Purging old database entries in /home/jerin/.local/share/man...
> > > Processing manual pages under /home/jerin/.local/share/man...
> > > Checking for stray cats under /home/jerin/.local/share/man...
> > > Processing manual pages under /home/jerin/.local/share/man/cat1...
> > > 0 man subdirectories contained newer manual pages.
> > > 0 manual pages were added.
> > > 0 stray cats were added.
> > > 0 old database entries were purged.
> > >
> > > [main][dpdk.org] $ man rte_flow_create
> > > No manual entry for rte_flow_create
> > >
> > > # Following works by providing the path i.e man pages created properly
> > > only db update is missing
> > > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> > >
> > Yes, that is correct.
> >
> > If you install to a non-standard location, then yes you need to update
> > manpath yourself. However, in case you install to a "standard" location,
> > then running mandb will update the database for you. I believe this is the
> > behaviour we should have. I view it as the same as installing binaries in a
> > standard vs non-standard path - if the binaries are placed in a standard
> > location then they are found automatically, but if installed in a custom
> > location, then the user is responsible for ensuring all paths are correct.
>
> OK. Then I think, we can move "meson.add_install_script(mandb)"
> invocation under !DESTDIR not provided.
> As if DESTDIR is provided then there is no use for mandb.
>
That would mean adding a new build script to run mandb, since:
* meson doesn't directly support getting environment variables
* DESTDIR may only be set at install time rather than at configuration
time, so we'll always need to set up the build script
Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary
runs of mandb, since using a special "prefix" setting would also cause the
manpages to not be found.
Overall, I'd view the complexity of avoiding the mandb call not to be
worth it, since calling mandb is largely harmless - bar the time taken to
run it. However, if you feel strongly it should be skipped when installing
with DESTDIR, I'll spin a v2 with the wrapper script added. Let me know
what you think?
/Bruce
next prev parent reply other threads:[~2023-06-06 10:19 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-01 15:38 Bruce Richardson
2023-06-05 5:20 ` Jerin Jacob
2023-06-06 9:18 ` Bruce Richardson
2023-06-06 9:46 ` Jerin Jacob
2023-06-06 10:18 ` Bruce Richardson [this message]
2023-06-06 10:49 ` Jerin Jacob
2023-06-06 10:54 ` Bruce Richardson
2023-06-06 13:12 ` [PATCH v2] " Bruce Richardson
2023-07-04 8:21 ` David Marchand
2023-07-17 11:09 ` Bruce Richardson
2023-08-03 9:18 ` David Marchand
2023-08-03 16:43 ` Bruce Richardson
2023-08-03 16:44 ` [PATCH v3] " Bruce Richardson
2023-08-04 12:12 ` David Marchand
2023-08-29 9:28 ` Thomas Monjalon
2023-08-29 10:10 ` Bruce Richardson
2023-08-30 9:47 ` Thomas Monjalon
2023-08-30 10:20 ` Bruce Richardson
2023-08-30 11:23 ` Thomas Monjalon
2023-08-31 9:49 ` [PATCH v4] " Bruce Richardson
2023-08-31 10:12 ` Thomas Monjalon
2023-08-31 15:48 ` Morten Brørup
2023-09-27 16:25 ` Thomas Monjalon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZH8ICsTsjKmQqpvT@bricha3-MOBL.ger.corp.intel.com \
--to=bruce.richardson@intel.com \
--cc=dev@dpdk.org \
--cc=jerinjacobk@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).