Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed
El jue, 03-01-2013 a las 17:11 -0600, William Hubbs escribió:
[...]
But, how to share CONFIGURATION_INSTRUCTIONS contents then for
create_doc and print_elog? The idea is to share the same message, and
using global variable for this purpose is already done with
kernel-2.eclass (I noticed it when doing last tuxonice-sources bumps)
Does kernel-2.eclass save the message somewhere or just print it? If it
just prints it I can see that, but since you are saving it to a file, I
was just thinking that there is no need to keep a global variable
around.
It just print it via elog, but I don't see the difference when it's
saved to a file. Anyway, there is no problem on setting it at pkg_setup
of src_prepare phases for example.
[...]
# @FUNCTION: configuration_print_elog
# @DESCRIPTION:
# Print elog messages with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at pkg_postinst phase.
configuration_print_elog() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${CONFIGURATION_INSTRUCTIONS} ]]; then
I would recommend using the CONFIGURATION file here, as follows:
if [ -f ${T}/CONFIGURATION ]; then
That is interesting as ensures file was created, but, will it be still
there at pkg_postinst phase?
Yes, it should be.
In that case I will try it, thanks for the tip
if ! [[ ${REPLACING_VERSIONS} ]]; then
This is an issue if I want to add display some tips that have changed
between different versions of the software. I would propose not trying
to do this, but let the user call this function.
This is intentional because the kind of messages that are always the
same and, then, need to only be shown with elog first time the package
is installed need this checking. From packages I have seen, those
messages that are related with updating from version XXX should still
be handled manually.
Say I have foobar-1 installed, and it has configuration instructions.
Now, foobar-2 comes along with different configuration instructions
that do not work for foobar-1.
What happens to the CONFIGURATION file when I upgrade? Does it now have
foobar-2's instructions? If not, this is a bug.
William
With current eclass design, you will need to handle it at ebuild itself
(as done currently), and handle that way proper version checking that
will change depending on each package. Anyway, eclass could be enhanced
to also handling this cases but, before that:
- we need to agree what is the proper way of using REPLACING_VERSIONS
for version checking (some ebuilds use / operators, while others
rely on versionator.eclass)
- I need to think how to handle both cases :|
- I guess you want to save in CONFIGURATION file that kind of messages
version-dependent ONLY when people updates from older versions and,
then, once people re-emerge the package, that part will be removed (as
is done currently with elog messages that are, for example, behind:
if [[ ${REPLACING_VERSIONS} ]] [[ ${REPLACING_VERSIONS} XX ]]; then
signature.asc
Description: This is a digitally signed message part
Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed
On Thu, Jan 03, 2013 at 02:01:03PM +0100, Pacho Ramos wrote:
# Copyright 1999-2012 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
# @ECLASS: configuration-doc
# @MAINTAINER:
# Pacho Ramos pa...@gentoo.org
# @AUTHOR:
# Author: Pacho Ramos pa...@gentoo.org
# @BLURB: An eclass for installing a CONFIGURATION doc file recording tips
# shown via elog messages. With this eclass, those elog messages will only be
# shown at first package installation and a file for later reviewing will be
# installed under /usr/share/doc/${PF}
# @DESCRIPTION:
# An eclass for installing a CONFIGURATION doc file recording tips
# shown via elog messages. With this eclass, those elog messages will only be
# shown at first package installation and a file for later reviewing will be
# installed under /usr/share/doc/${PF}
if [[ ${___ECLASS_ONCE_CONFIGURATION_DOC} != recur -_+^+_- spank ]] ; then
___ECLASS_ONCE_CONFIGURATION_DOC=recur -_+^+_- spank
inherit eutils
case ${EAPI:-0} in
0|1|2|3)
die Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}
;;
4|5)
# EAPI=4 is required for REPLACING_VERSIONS preventing us
# from needing to export another pkg_preinst phase to save
has_version
# result. Also relies on EAPI =4 default src_install phase.
;;
*)
die Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}
;;
esac
Why does it matter if the unsupported eapi is too old or unknown? I
think you can combine the first and last branches of this case
statement.
On the other hand, if you don't export phase functions, you don't have
to worry about EAPIS; you can just allow ebuild developers to call your
functions directly. This is what I see happening in your sample ebuild
below.
EXPORT_FUNCTIONS src_install pkg_postinst
Drop this export_functions call. You don't need it based on what I see
in your ebuild.
# @FUNCTION: configuration_create_doc
# @DESCRIPTION:
# Create doc file with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at src_install phase.
You can pass in the content as $1 instead of using a global variable for
it:
configuration_create_doc() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${1} ]]; then
eshopts_push
set -f
echo ${CONFIGURATION_INSTRUCTIONS} | fmt CONFIGURATION
I would use ${T}/CONFIGURATION here.
echo ${1} | fmt ${T}CONFIGURATION
eshopts_pop
dodoc CONFIGURATION
Again, ${T}/CONFIGURATION
fi
}
# @FUNCTION: configuration_print_elog
# @DESCRIPTION:
# Print elog messages with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at pkg_postinst phase.
configuration_print_elog() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${CONFIGURATION_INSTRUCTIONS} ]]; then
I would recommend using the CONFIGURATION file here, as follows:
if [ -f ${T}/CONFIGURATION ]; then
if ! [[ ${REPLACING_VERSIONS} ]]; then
This is an issue if I want to add display some tips that have changed
between different versions of the software. I would propose not trying
to do this, but let the user call this function.
eshopts_push
set -f
echo ${CONFIGURATION_INSTRUCTIONS} | fmt | while read
-r ELINE; do elog ${ELINE}; done
cat ${T}/CONFIGURATION | fmt | while read -r ELINE;
do elog ${ELINE}; done
eshopts_pop
fi
fi
}
# @FUNCTION: configuration-doc_src_install
# @DESCRIPTION:
# Show elog messages from CONFIGURATION_INSTRUCTIONS variable, that will be
# shared with /usr/share/doc/${PF}/CONFIGURATION content.
configuration-doc_src_install() {
debug-print-function ${FUNCNAME} ${@}
default
configuration_create_doc
}
# @FUNCTION: configuration-doc_pkg_postinst
# @DESCRIPTION:
# Show elog messages from CONFIGURATION_INSTRUCTIONS variable, that will be
# shared with /usr/share/doc/${PF}/CONFIGURATION content.
configuration-doc_pkg_postinst() {
debug-print-function ${FUNCNAME} ${@}
configuration_print_elog
}
fi
These can go; your example ebuild doesn't need them since it calls the
eclass functions.
Below, I am showing how the ebuild would change based on my changes to
the eclass.
# Copyright 1999-2012 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: /var/cvsroot/gentoo-x86/sys-power/acpid/acpid-2.0.17.ebuild,v 1.6
2012/11/25 18:59:25 armin76 Exp $
EAPI=4
inherit configuration-doc systemd
DESCRIPTION=Daemon for Advanced Configuration and Power Interface
HOMEPAGE=http://tedfelix.com/linux/acpid-netlink.html;
SRC_URI=http://tedfelix.com/linux/${P}.tar.xz;
LICENSE=GPL-2
SLOT=0
KEYWORDS=amd64 ia64 -ppc x86
Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed
El jue, 03-01-2013 a las 14:29 -0600, William Hubbs escribió:
[...]
case ${EAPI:-0} in
0|1|2|3)
die Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}
;;
4|5)
# EAPI=4 is required for REPLACING_VERSIONS preventing us
# from needing to export another pkg_preinst phase to save
has_version
# result. Also relies on EAPI =4 default src_install phase.
;;
*)
die Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}
;;
esac
Why does it matter if the unsupported eapi is too old or unknown? I
think you can combine the first and last branches of this case
statement.
Well, I saw it in other eclasses and thought the distinction was
preferred, but have no problems on changing it
On the other hand, if you don't export phase functions, you don't have
to worry about EAPIS; you can just allow ebuild developers to call your
functions directly. This is what I see happening in your sample ebuild
below.
It exports src_install and pkg_postinst, at least the second one could
be used in other ebuilds that are only setting a package specific one
for showing this kind of messages (for example bumblebee ebuilds).
For src_install case, probably some other ebuilds could benefit, but
didn't find them when I fast checked yesterday :/. Its purpose is to
ensure doc CONFIGURATION file is created, the ideal would be to be able
to only add it to create it and leave other eclasses or eapi defaults to
handle the rest of src_install, but I think it's not possible :| (and,
then, it will behave like eapi = 4 default src_install phase + creating
the file)
Anyway, EAPI = 4 is still needed for REPLACING_VERSIONS usage, that
allows to simplify things preventing us from needing to set pkg_preinst
also
EXPORT_FUNCTIONS src_install pkg_postinst
Drop this export_functions call. You don't need it based on what I see
in your ebuild.
They can be needed if ebuild doesn't need to have a custom
src_install/pkg_postinst only for this purposes
# @FUNCTION: configuration_create_doc
# @DESCRIPTION:
# Create doc file with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at src_install phase.
You can pass in the content as $1 instead of using a global variable for
it:
But, how to share CONFIGURATION_INSTRUCTIONS contents then for
create_doc and print_elog? The idea is to share the same message, and
using global variable for this purpose is already done with
kernel-2.eclass (I noticed it when doing last tuxonice-sources bumps)
configuration_create_doc() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${1} ]]; then
eshopts_push
set -f
echo ${CONFIGURATION_INSTRUCTIONS} | fmt CONFIGURATION
I would use ${T}/CONFIGURATION here.
echo ${1} | fmt ${T}CONFIGURATION
eshopts_pop
dodoc CONFIGURATION
Again, ${T}/CONFIGURATION
I have no problem but, what is its advantage? (to remember it more
easily next time). Thanks :)
fi
}
# @FUNCTION: configuration_print_elog
# @DESCRIPTION:
# Print elog messages with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at pkg_postinst phase.
configuration_print_elog() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${CONFIGURATION_INSTRUCTIONS} ]]; then
I would recommend using the CONFIGURATION file here, as follows:
if [ -f ${T}/CONFIGURATION ]; then
That is interesting as ensures file was created, but, will it be still
there at pkg_postinst phase?
if ! [[ ${REPLACING_VERSIONS} ]]; then
This is an issue if I want to add display some tips that have changed
between different versions of the software. I would propose not trying
to do this, but let the user call this function.
This is intentional because the kind of messages that are always the
same and, then, need to only be shown with elog first time the package
is installed need this checking. From packages I have seen, those
messages that are related with updating from version XXX should still
be handled manually.
The eclass could, of course, be handled to also handle this cases, but I
would like to keep the automatic way of it showing the message only
first time package is installed.
[...]
CONFIGURATION_INSTRUCTIONS=
You may wish to read the Gentoo Linux Power Management Guide,
which can be found online at:
http://www.gentoo.org/doc/en/power-management-guide.xml;
Delete this and make it a local below if you want the variable,
otherwise pass it as a constant.
sorry for the ignorance but, how should I pass it as a constant? Using
readonly? Also, I am not using here any external tool and, then,
global scope shouldn't be discouraged
src_configure() {
econf --docdir=/usr/share/doc/${PF}
}
src_install() {
emake DESTDIR=${D} install
newdoc kacpimon/README
Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed
On Thu, Jan 03, 2013 at 10:03:21PM +0100, Pacho Ramos wrote:
El jue, 03-01-2013 a las 14:29 -0600, William Hubbs escribió:
[...]
case ${EAPI:-0} in
0|1|2|3)
die Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}
;;
4|5)
# EAPI=4 is required for REPLACING_VERSIONS preventing us
# from needing to export another pkg_preinst phase to save
has_version
# result. Also relies on EAPI =4 default src_install phase.
;;
*)
die Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}
;;
esac
Why does it matter if the unsupported eapi is too old or unknown? I
think you can combine the first and last branches of this case
statement.
Well, I saw it in other eclasses and thought the distinction was
preferred, but have no problems on changing it
Well, that's up to you I guess, but, I just didn't see the difference.
You can pass in the content as $1 instead of using a global variable for
it:
But, how to share CONFIGURATION_INSTRUCTIONS contents then for
create_doc and print_elog? The idea is to share the same message, and
using global variable for this purpose is already done with
kernel-2.eclass (I noticed it when doing last tuxonice-sources bumps)
Does kernel-2.eclass save the message somewhere or just print it? If it
just prints it I can see that, but since you are saving it to a file, I
was just thinking that there is no need to keep a global variable
around.
configuration_create_doc() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${1} ]]; then
eshopts_push
set -f
echo ${CONFIGURATION_INSTRUCTIONS} | fmt CONFIGURATION
I would use ${T}/CONFIGURATION here.
echo ${1} | fmt ${T}CONFIGURATION
eshopts_pop
dodoc CONFIGURATION
Again, ${T}/CONFIGURATION
I have no problem but, what is its advantage? (to remember it more
easily next time). Thanks :)
Well, ${T} is a temporary directory where you can put anything you want,
and it is defined in PMS, so I just use it instead of throwing files in
the working tree.
# @FUNCTION: configuration_print_elog
# @DESCRIPTION:
# Print elog messages with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at pkg_postinst phase.
configuration_print_elog() {
debug-print-function ${FUNCNAME} ${@}
if [[ -n ${CONFIGURATION_INSTRUCTIONS} ]]; then
I would recommend using the CONFIGURATION file here, as follows:
if [ -f ${T}/CONFIGURATION ]; then
That is interesting as ensures file was created, but, will it be still
there at pkg_postinst phase?
Yes, it should be.
if ! [[ ${REPLACING_VERSIONS} ]]; then
This is an issue if I want to add display some tips that have changed
between different versions of the software. I would propose not trying
to do this, but let the user call this function.
This is intentional because the kind of messages that are always the
same and, then, need to only be shown with elog first time the package
is installed need this checking. From packages I have seen, those
messages that are related with updating from version XXX should still
be handled manually.
Say I have foobar-1 installed, and it has configuration instructions.
Now, foobar-2 comes along with different configuration instructions
that do not work for foobar-1.
What happens to the CONFIGURATION file when I upgrade? Does it now have
foobar-2's instructions? If not, this is a bug.
William
pgpRBCciB_l4o.pgp
Description: PGP signature
