[PATCH 0/2] perf: enable man pages for 'help' functionality

[PATCH 0/2] perf: enable man pages for 'help' functionality

[Dengke Du]

The following changes since commit 36feb38045b7a2af86ece147fec54b0db3bf491f:

  linux-yocto: Update genericx86* SRCREVs for linux-yocto 4.4 (2016-07-21 07:48:53 +0100)

are available in the git repository at:

  git://git.openembedded.org/openembedded-core-contrib dengke/enable-help-man-pages-for-perf
  http://cgit.openembedded.org/cgit.cgi/openembedded-core-contrib/log/?h=dengke/enable-help-man-pages-for-perf

Dengke Du (2):
  Asciidoc: add it
  perf: enable man pages for 'help' functionality

 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb | 20 ++++++++++++++++++++
 meta/recipes-kernel/perf/perf.bb                 | 11 ++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb

-- 
2.8.1

[PATCH 1/2] Asciidoc: add it

[Dengke Du]

In order to enable perf man pages for basic 'help' functionality,
it needs to produce man pages for perf, which depends on the xmlto
and asciidoc tools.
So add the asciidoc recipe to help produce man pages for perf and
other commands.

Signed-off-by: Dengke Du <dengke.du@windriver.com>
---
 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb

diff --git a/meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb b/meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb
new file mode 100644
index 0000000..1500b0a
--- /dev/null
+++ b/meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb
@@ -0,0 +1,20 @@
+SUMMARY = "Tool for creating HTML, PDF, EPUB, man pages"
+DESCRIPTION = "AsciiDoc is a text document format for writing short documents, \
+articles, books and UNIX man pages."
+
+HOMEPAGE = "http://asciidoc.org/"
+
+LICENSE = "GPLv2"
+LIC_FILES_CHKSUM = "file://COPYING;md5=8ca43cbc842c2336e835926c2166c28b \
+                    file://COPYRIGHT;md5=029ad5428ba5efa20176b396222d4069"
+
+SRC_URI = "http://downloads.sourceforge.net/project/${BPN}/${BPN}/${PV}/${BP}.tar.gz"
+SRC_URI[md5sum] = "c59018f105be8d022714b826b0be130a"
+SRC_URI[sha256sum] = "78db9d0567c8ab6570a6eff7ffdf84eadd91f2dfc0a92a2d0105d323cab4e1f0"
+
+
+inherit distutils autotools-brokensep
+
+export DESTDIR = "${D}"
+RDEPENDS_${PN} += "python" 
+BBCLASSEXTEND = "native"
-- 
2.8.1

[PATCH 2/2] perf: enable man pages for 'help' functionality

[Dengke Du]

When using 'perf help <subcommand>', it can't find 'man' command and pages for
perf.
The perf man pages depends on the xmlto-native and asciidoc-native, so we just
need to add the two packages to the DEPENDS variable and add 'man'to
RDEPENDS_perf-doc.

Signed-off-by: Dengke Du <dengke.du@windriver.com>
---
 meta/recipes-kernel/perf/perf.bb | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/meta/recipes-kernel/perf/perf.bb b/meta/recipes-kernel/perf/perf.bb
index 171d23f..1e84a22 100644
--- a/meta/recipes-kernel/perf/perf.bb
+++ b/meta/recipes-kernel/perf/perf.bb
@@ -30,6 +30,8 @@ DEPENDS = " \
     ${SCRIPTING_DEPENDS} \
     ${LIBUNWIND_DEPENDS} \
     bison flex xz \
+    xmlto-native \
+    asciidoc-native \
 "
 
 do_configure[depends] += "virtual/kernel:do_shared_workdir"
@@ -90,7 +92,6 @@ EXTRA_OEMAKE += "\
     'sharedir=${datadir}' \
     'sysconfdir=${sysconfdir}' \
     'perfexecdir=${libexecdir}/perf-core' \
-    \
     'ETC_PERFCONFIG=${@os.path.relpath(sysconfdir, prefix)}' \
     'sharedir=${@os.path.relpath(datadir, prefix)}' \
     'mandir=${@os.path.relpath(mandir, prefix)}' \
@@ -138,6 +139,13 @@ do_configure_prepend () {
                -e 's,\ .config-detected, $(OUTPUT)/config-detected,g' \
             ${S}/tools/perf/config/Makefile
     fi
+    # The man pages installation is "$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)"
+    # in ${S}/tools/perf/Documentation/Makefile, if the mandir set to '?=', it
+    # will use the relative path 'share/man', in the way it will resulting in
+    # incorrect installation for man pages.
+    if [ -e "${S}/tools/perf/Documentation/Makefile" ]; then
+	sed -i 's,^mandir?=,mandir:=,' ${S}/tools/perf/Documentation/Makefile
+    fi
     if [ -e "${S}/tools/perf/Makefile.perf" ]; then
         sed -i -e 's,\ .config-detected, $(OUTPUT)/config-detected,g' \
             ${S}/tools/perf/Makefile.perf
@@ -197,6 +205,7 @@ PACKAGE_ARCH = "${MACHINE_ARCH}"
 PACKAGES =+ "${PN}-archive ${PN}-tests ${PN}-perl ${PN}-python"
 
 RDEPENDS_${PN} += "elfutils bash"
+RDEPENDS_${PN}-doc += "man"
 RDEPENDS_${PN}-archive =+ "bash"
 RDEPENDS_${PN}-python =+ "bash python python-modules"
 RDEPENDS_${PN}-perl =+ "bash perl perl-modules"
-- 
2.8.1

Re: [PATCH 2/2] perf: enable man pages for 'help' functionality

[Burton, Ross]

[-- Attachment #1: Type: text/plain, Size: 997 bytes --]

Hi,

On 27 July 2016 at 06:02, Dengke Du <dengke.du@windriver.com> wrote:

> When using 'perf help <subcommand>', it can't find 'man' command and
> pages for
> perf.
> The perf man pages depends on the xmlto-native and asciidoc-native, so we
> just
> need to add the two packages to the DEPENDS variable and add 'man'to
> RDEPENDS_perf-doc.
>

Whilst I like the idea of supporting more documentation, and have long
wanted to integrate doxygen/gtk-doc/etc into Yocto for building SDKs with
API documentation, I'm not sure we should be making random packages depend
on tooling to always generate documentation.

What do people think of a distro feature / global environment variable for
"recipe should build the documentation"?  For perf this would mean adding
asciidoc so it can build the man pages, for GLib it would mean depending on
gtk-doc so the API docs can be generated, and so on.  But if they're not
needed then they can be disabled to improve build speeds.

Ross

[-- Attachment #2: Type: text/html, Size: 1534 bytes --]

Re: [PATCH 2/2] perf: enable man pages for 'help' functionality

[Joshua G Lock]

[-- Attachment #1: Type: text/plain, Size: 1329 bytes --]

On Tue, 2016-08-02 at 17:56 +0100, Burton, Ross wrote:
> Hi,
> 
> > On 27 July 2016 at 06:02, Dengke Du <dengke.du@windriver.com> wrote:
> > > > When using 'perf help <subcommand>', it can't find 'man' command
and pages for
> > perf.
> > 
> > > > The perf man pages depends on the xmlto-native and asciidoc-native, 
so we just
> > 
> > > > need to add the two packages to the DEPENDS variable and add
'man'to
> > 
> > RDEPENDS_perf-doc.
> > 
> 
> > > > Whilst I like the idea of supporting more documentation, and have
long wanted to integrate doxygen/gtk-doc/etc into Yocto for building
SDKs with API documentation, I'm not sure we should be making random
packages depend on tooling to always generate documentation.
> 
> > > > > > What do people think of a distro feature / global environment
variable for "recipe should build the documentation"?  For perf this
would mean adding asciidoc so it can build the man pages, for GLib it
would mean depending on gtk-doc so the API docs can be generated, and
so on.  But if they're not needed then they can be disabled to
improve build speeds.
> 
> 

I like the idea. I've had a similar one in mind for a while now as it
would be a nice feature to be able to provide the documentation for an
image as an output of the system.

Regards,

Joshua

[-- Attachment #2: Type: text/html, Size: 1741 bytes --]

Re: [PATCH 0/2] perf: enable man pages for 'help' functionality

[Randy MacLeod]

On 2016-07-27 01:02 AM, Dengke Du wrote:
> The following changes since commit 36feb38045b7a2af86ece147fec54b0db3bf491f:
>
>   linux-yocto: Update genericx86* SRCREVs for linux-yocto 4.4 (2016-07-21 07:48:53 +0100)
>
> are available in the git repository at:
>
>   git://git.openembedded.org/openembedded-core-contrib dengke/enable-help-man-pages-for-perf
>   http://cgit.openembedded.org/cgit.cgi/openembedded-core-contrib/log/?h=dengke/enable-help-man-pages-for-perf
>
> Dengke Du (2):
>   Asciidoc: add it
>   perf: enable man pages for 'help' functionality
>
>  meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb | 20 ++++++++++++++++++++
>  meta/recipes-kernel/perf/perf.bb                 | 11 ++++++++++-
>  2 files changed, 30 insertions(+), 1 deletion(-)
>  create mode 100644 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb
>

Looks good .

I was under the impression that asciidoc was larger but it's just
  ~ 900KB plus it's all python so it's not going to add to the system
build time directly.

How much longer does it take to build perf?

Did you test for python3 only?

-- 
# Randy MacLeod. SMTS, Linux, Wind River
Direct: 613.963.1350 | 350 Terry Fox Drive, Suite 200, Ottawa, ON, 
Canada, K2K 2W5

Re: [PATCH 0/2] perf: enable man pages for 'help' functionality

[dengke.du]

Hi Randy

1.  I have checked the asciidoc-native: 3.1M

2.  real    4m41.858s
      user    27m3.280s
      sys    6m32.372s

3.  Yes, the build system using python3.

//dengke

On 2016年07月28日 02:23, Randy MacLeod wrote:
> On 2016-07-27 01:02 AM, Dengke Du wrote:
>> The following changes since commit 
>> 36feb38045b7a2af86ece147fec54b0db3bf491f:
>>
>>   linux-yocto: Update genericx86* SRCREVs for linux-yocto 4.4 
>> (2016-07-21 07:48:53 +0100)
>>
>> are available in the git repository at:
>>
>>   git://git.openembedded.org/openembedded-core-contrib 
>> dengke/enable-help-man-pages-for-perf
>> http://cgit.openembedded.org/cgit.cgi/openembedded-core-contrib/log/?h=dengke/enable-help-man-pages-for-perf
>>
>> Dengke Du (2):
>>   Asciidoc: add it
>>   perf: enable man pages for 'help' functionality
>>
>>  meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb | 20 
>> ++++++++++++++++++++
>>  meta/recipes-kernel/perf/perf.bb                 | 11 ++++++++++-
>>  2 files changed, 30 insertions(+), 1 deletion(-)
>>  create mode 100644 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb
>>
>
> Looks good .
>
> I was under the impression that asciidoc was larger but it's just
>  ~ 900KB plus it's all python so it's not going to add to the system
> build time directly.
>
> How much longer does it take to build perf?
>
> Did you test for python3 only?
>

Re: [PATCH 0/2] perf: enable man pages for 'help' functionality

[Randy MacLeod]

As Ross asked in a separate reply, we should discuss
the pros and cons of making the host-based generation of docs
be optional. I think that's the way to go since, in the common case
of not enabling docs, the builds would be faster and the output smaller.

On 2016-07-31 09:33 PM, dengke.du@windriver.com wrote:
> Hi Randy
>
> 1.  I have checked the asciidoc-native: 3.1M
>
> 2.  real    4m41.858s
>      user    27m3.280s
>      sys    6m32.372s



Those numbers, on their own, are not useful.

How long does it take to build another native package on your system?
What's the overall time  and time difference to build an image without
and then with asciidoc and perf (and maybe ccache, git, trace-cmd)
docs being generated? Alternatively just make the generation of docs
be optional and then the time isn't a critical concern.

You should follow-up, ***later*** by enabling doc generation for:

commit 40627f5c334544178b056078da5e1d645ebd2a38
Author: Robert Yang <liezhi.yang@windriver.com>
Date:   Mon Jul 25 01:16:31 2016 -0700

     ccache: 3.2.4 -> 3.2.5

     Add Revert-Create-man-page-in-the-make-install-from-git-.patch to
     disable asciidoc since we don't have it.


and perhaps:


commit 9aba4bf2143c228d58aac06764f87ace5dd21d02
Author: Paul Gortmaker <paul.gortmaker@windriver.com>
Date:   Tue Feb 10 14:17:37 2015 -0500

     git: expand recipe to take advantage of pre-gen'd manpages

     These could be created from scratch from git itself, but it
     requires asciidoc, xsltproc, python bits and too much other
     baggage.  Since the git folks issue a tarball with the manpages
     for each release, it is simpler to just go get that.

and:

commit 73ac48377491561151658617d8cc45936242eb0c
Author: Darren Hart <dvhart@linux.intel.com>
Date:   Wed Nov 30 17:58:52 2011 -0800

     trace-cmd: Update to 1.2 (includes kernelshark)

>
> 3.  Yes, the build system using python3.

so what about python2? Does asciidoc require a specific major version
of python?

../Randy

>
> //dengke
>
> On 2016年07月28日 02:23, Randy MacLeod wrote:
>> On 2016-07-27 01:02 AM, Dengke Du wrote:
>>> The following changes since commit
>>> 36feb38045b7a2af86ece147fec54b0db3bf491f:
>>>
>>>   linux-yocto: Update genericx86* SRCREVs for linux-yocto 4.4
>>> (2016-07-21 07:48:53 +0100)
>>>
>>> are available in the git repository at:
>>>
>>>   git://git.openembedded.org/openembedded-core-contrib
>>> dengke/enable-help-man-pages-for-perf
>>> http://cgit.openembedded.org/cgit.cgi/openembedded-core-contrib/log/?h=dengke/enable-help-man-pages-for-perf
>>>
>>>
>>> Dengke Du (2):
>>>   Asciidoc: add it
>>>   perf: enable man pages for 'help' functionality
>>>
>>>  meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb | 20
>>> ++++++++++++++++++++
>>>  meta/recipes-kernel/perf/perf.bb                 | 11 ++++++++++-
>>>  2 files changed, 30 insertions(+), 1 deletion(-)
>>>  create mode 100644 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb
>>>
>>
>> Looks good .
>>
>> I was under the impression that asciidoc was larger but it's just
>>  ~ 900KB plus it's all python so it's not going to add to the system
>> build time directly.
>>
>> How much longer does it take to build perf?
>>
>> Did you test for python3 only?
>>
>


-- 
# Randy MacLeod. SMTS, Linux, Wind River
Direct: 613.963.1350 | 350 Terry Fox Drive, Suite 200, Ottawa, ON, 
Canada, K2K 2W5

Re: [PATCH 0/2] perf: enable man pages for 'help' functionality

[dengke.du]

Hi Randy & Ross

1. After my test, python2 & python3 works well.
2. I will follow-up the packages docs related to the asciidoc and work 
on the
     generation of docs, let it be optional.

//dengke

On 2016年08月03日 01:59, Randy MacLeod wrote:
>
> As Ross asked in a separate reply, we should discuss
> the pros and cons of making the host-based generation of docs
> be optional. I think that's the way to go since, in the common case
> of not enabling docs, the builds would be faster and the output smaller.
>
> On 2016-07-31 09:33 PM, dengke.du@windriver.com wrote:
>> Hi Randy
>>
>> 1.  I have checked the asciidoc-native: 3.1M
>>
>> 2.  real    4m41.858s
>>      user    27m3.280s
>>      sys    6m32.372s
>
>
>
> Those numbers, on their own, are not useful.
>
> How long does it take to build another native package on your system?
> What's the overall time  and time difference to build an image without
> and then with asciidoc and perf (and maybe ccache, git, trace-cmd)
> docs being generated? Alternatively just make the generation of docs
> be optional and then the time isn't a critical concern.
>
> You should follow-up, ***later*** by enabling doc generation for:
>
> commit 40627f5c334544178b056078da5e1d645ebd2a38
> Author: Robert Yang <liezhi.yang@windriver.com>
> Date:   Mon Jul 25 01:16:31 2016 -0700
>
>     ccache: 3.2.4 -> 3.2.5
>
>     Add Revert-Create-man-page-in-the-make-install-from-git-.patch to
>     disable asciidoc since we don't have it.
>
>
> and perhaps:
>
>
> commit 9aba4bf2143c228d58aac06764f87ace5dd21d02
> Author: Paul Gortmaker <paul.gortmaker@windriver.com>
> Date:   Tue Feb 10 14:17:37 2015 -0500
>
>     git: expand recipe to take advantage of pre-gen'd manpages
>
>     These could be created from scratch from git itself, but it
>     requires asciidoc, xsltproc, python bits and too much other
>     baggage.  Since the git folks issue a tarball with the manpages
>     for each release, it is simpler to just go get that.
>
> and:
>
> commit 73ac48377491561151658617d8cc45936242eb0c
> Author: Darren Hart <dvhart@linux.intel.com>
> Date:   Wed Nov 30 17:58:52 2011 -0800
>
>     trace-cmd: Update to 1.2 (includes kernelshark)
>
>>
>> 3.  Yes, the build system using python3.
>
> so what about python2? Does asciidoc require a specific major version
> of python?
>
> ../Randy
>
>>
>> //dengke
>>
>> On 2016年07月28日 02:23, Randy MacLeod wrote:
>>> On 2016-07-27 01:02 AM, Dengke Du wrote:
>>>> The following changes since commit
>>>> 36feb38045b7a2af86ece147fec54b0db3bf491f:
>>>>
>>>>   linux-yocto: Update genericx86* SRCREVs for linux-yocto 4.4
>>>> (2016-07-21 07:48:53 +0100)
>>>>
>>>> are available in the git repository at:
>>>>
>>>>   git://git.openembedded.org/openembedded-core-contrib
>>>> dengke/enable-help-man-pages-for-perf
>>>> http://cgit.openembedded.org/cgit.cgi/openembedded-core-contrib/log/?h=dengke/enable-help-man-pages-for-perf 
>>>>
>>>>
>>>>
>>>> Dengke Du (2):
>>>>   Asciidoc: add it
>>>>   perf: enable man pages for 'help' functionality
>>>>
>>>>  meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb | 20
>>>> ++++++++++++++++++++
>>>>  meta/recipes-kernel/perf/perf.bb                 | 11 ++++++++++-
>>>>  2 files changed, 30 insertions(+), 1 deletion(-)
>>>>  create mode 100644 meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb
>>>>
>>>
>>> Looks good .
>>>
>>> I was under the impression that asciidoc was larger but it's just
>>>  ~ 900KB plus it's all python so it's not going to add to the system
>>> build time directly.
>>>
>>> How much longer does it take to build perf?
>>>
>>> Did you test for python3 only?
>>>
>>
>
>