perf: enable man pages for 'help' functionality

PATCH In review Dengke Du 4 participants 9 messages Jul 27, 2016 – Aug 4, 2016

lore

Share & tools

lore

Dengke Du

author

2016-07-27 05:02 UTC #0 lore raw

cover perf: enable man pages for 'help' functionality

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

Signature · 1 line

2.8.1

Dengke Du

author

2016-07-27 05:02 UTC #1 lore raw

PATCH 1/2 Asciidoc: add it

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 <[email protected]>

---
 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

meta/recipes-extended/asciidoc/asciidoc_8.6.9.bb new file +20 -0

new file mode 100644
index 0000000..1500b0a
@@ -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"

Signature · 1 line

2.8.1

Dengke Du

author

2016-07-27 05:02 UTC #2 lore raw

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

In reply to 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 <[email protected]>

---
 meta/recipes-kernel/perf/perf.bb | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

meta/recipes-kernel/perf/perf.bb +10 -1

index 171d23f..1e84a22 100644
@@ -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"

Signature · 1 line

2.8.1

Burton, Ross

2016-08-02 16:56 UTC #3 lore raw

Hi,

Quoted 8 lines · 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.

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

Joshua G Lock

2016-08-02 20:06 UTC #4 lore raw

Quoted 4 lines · Ross

Hi,
Quoted 2 lines · Dengke Du
Quoted 1 line
Quoted 1 line
When using 'perf help <subcommand>', it can't find 'man' command

and pages for

Quoted 3 lines

Quoted 3 lines
perf.
Quoted 1 line
Quoted 1 line
The perf man pages depends on the xmlto-native and asciidoc-native,

so we just

Quoted 2 lines

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
need to add the two packages to the DEPENDS variable and add

'man'to

Quoted 5 lines

Quoted 5 lines
RDEPENDS_perf-doc.
Quoted 1 line
Quoted 1 line
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.

Quoted 2 lines

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
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.

Quoted 2 lines

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

Randy MacLeod

2016-07-27 18:23 UTC #5 lore raw

In reply to Dengke Du

Quoted 9 lines · 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

Quoted 9 lines

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?

Signature · 2 lines

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

[email protected]

author

2016-08-01 01:33 UTC #6 lore raw

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

Quoted 33 lines · Randy MacLeod

Quoted 15 lines · 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
Quoted 6 lines
 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

2016-08-02 17:59 UTC #7 lore raw

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.

Quoted 7 lines · On 2016-07-31 09:33 PM, [email protected] 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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
Date:   Wed Nov 30 17:58:52 2011 -0800

trace-cmd: Update to 1.2 (includes kernelshark)

Quoted 2 lines

3. Yes, the build system using python3.

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

../Randy

Quoted 40 lines

//dengke
Quoted 35 lines · Randy MacLeod
Quoted 17 lines · 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
Quoted 6 lines
 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?

Signature · 2 lines

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

[email protected]

author

2016-08-04 01:35 UTC #8 lore raw

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

Quoted 110 lines · 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.
Quoted 7 lines · On 2016-07-31 09:33 PM, [email protected] 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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
Date:   Wed Nov 30 17:58:52 2011 -0800
trace-cmd: Update to 1.2 (includes kernelshark)
Quoted 2 lines
3. Yes, the build system using python3.
so what about python2? Does asciidoc require a specific major version of python?
../Randy
Quoted 41 lines
//dengke
Quoted 36 lines · Randy MacLeod
Quoted 18 lines · 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
Quoted 6 lines
 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?