[gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed

[gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed

[Pacho Ramos]

[-- Attachment #1.1: Type: text/plain, Size: 1774 bytes --]

This comes from the following gentoo-dev thread:
http://www.gossamer-threads.com/lists/gentoo/dev/264888

Its usage will lead to the installation of a CONFIGURATION file
under /usr/share/doc/${PF} and show of elog messages with its content
first time package is installed, relying in doc file for future
installations or people simply going there to review configuration tips.

I also attach acpid ebuild as example.

Currently I have doubts about how to handle formatting, it is now using
"fmt" as kernel-2.eclass to format it and, then, you can set:
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"

and it will be properly formatted at the end. The problem is that I find
no way to force a jump to a new line (for example if somebody want to
show a command to run in a new line).

Other option would be to simply add quotes to:
echo ${CONFIGURATION_INSTRUCTIONS}

and drop "fmt" usage.

It will respect formatting specified in ebuild, but this needs to be
taken into account as, for example, acpid ebuild used as example should
be changed to use:
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"

or people will get an empty line at the top of the messages.

Maybe an option to toggle fmt/formatting usage could be used, but I am
unsure about how to handle it at eclass level in a "short" way (I could
add some "ifs" running either variant (with quotes or without them and
fmt usage), but not sure if a shorter way could be used)



[-- Attachment #1.2: configuration-doc.eclass --]
[-- Type: text/plain, Size: 2950 bytes --]

# Copyright 1999-2012 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

# @ECLASS: configuration-doc
# @MAINTAINER:
# Pacho Ramos <pacho@gentoo.org>
# @AUTHOR:
# Author: Pacho Ramos <pacho@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

EXPORT_FUNCTIONS src_install pkg_postinst

# @FUNCTION: configuration_create_doc
# @DESCRIPTION:
# Create doc file with CONFIGURATION_INSTRUCTIONS contents.
# Usually called at src_install phase.
configuration_create_doc() {
	debug-print-function ${FUNCNAME} "${@}"

	if [[ -n "${CONFIGURATION_INSTRUCTIONS}" ]]; then
		eshopts_push
		set -f
		echo ${CONFIGURATION_INSTRUCTIONS} | fmt > CONFIGURATION
		eshopts_pop
		dodoc 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
		if ! [[ "${REPLACING_VERSIONS}" ]]; then
			eshopts_push
			set -f
			echo ${CONFIGURATION_INSTRUCTIONS} | 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

[-- Attachment #1.3: acpid-2.0.17.ebuild --]
[-- Type: text/plain, Size: 1645 bytes --]

# 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"
IUSE="selinux"

RDEPEND="selinux? ( sec-policy/selinux-apm )"
DEPEND="${RDEPEND}"

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"

src_configure() {
	econf --docdir=/usr/share/doc/${PF}
}

src_install() {
	emake DESTDIR="${D}" install

	newdoc kacpimon/README README.kacpimon
	dodoc -r samples
	rm -f "${D}"/usr/share/doc/${PF}/COPYING

	exeinto /etc/acpi
	newexe "${FILESDIR}"/${PN}-1.0.6-default.sh default.sh
	insinto /etc/acpi/events
	newins "${FILESDIR}"/${PN}-1.0.4-default default

	newinitd "${FILESDIR}"/${PN}-2.0.16-init.d ${PN}
	newconfd "${FILESDIR}"/${PN}-2.0.16-conf.d ${PN}

	systemd_dounit "${FILESDIR}"/systemd/${PN}.{service,socket}

	configuration_create_doc
}

pkg_postinst() {
	configuration_print_elog

	# files/systemd/acpid.socket -> ListenStream=/run/acpid.socket
	mkdir -p "${ROOT}"/run

	if ! grep -qs "^tmpfs.*/run " "${ROOT}"/proc/mounts ; then
		echo
		ewarn "You should reboot the system now to get /run mounted with tmpfs!"
	fi
}

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed

[William Hubbs]

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

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 <pacho@gentoo.org>
> # @AUTHOR:
> # Author: Pacho Ramos <pacho@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"
> IUSE="selinux"
> 
> RDEPEND="selinux? ( sec-policy/selinux-apm )"
> DEPEND="${RDEPEND}"
> 
> 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.

> src_configure() {
> 	econf --docdir=/usr/share/doc/${PF}
> }
> 
> src_install() {
> 	emake DESTDIR="${D}" install
> 
> 	newdoc kacpimon/README README.kacpimon
> 	dodoc -r samples
> 	rm -f "${D}"/usr/share/doc/${PF}/COPYING
> 
> 	exeinto /etc/acpi
> 	newexe "${FILESDIR}"/${PN}-1.0.6-default.sh default.sh
> 	insinto /etc/acpi/events
> 	newins "${FILESDIR}"/${PN}-1.0.4-default default
> 
> 	newinitd "${FILESDIR}"/${PN}-2.0.16-init.d ${PN}
> 	newconfd "${FILESDIR}"/${PN}-2.0.16-conf.d ${PN}
> 
> 	systemd_dounit "${FILESDIR}"/systemd/${PN}.{service,socket}

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

> 	configuration_create_doc

 	configuration_create_doc "${CONFIGURATION_INSTRUCTIONS}"
> }
> 
> pkg_postinst() {
> 	configuration_print_elog
 
 The thing that would change here would be that you would have to make
 postinst smart enough to know when to call configuration_print_elog.
 Maybe you do it all the time like this, or maybe you do it the first
 time the package is installed, or you do it when you are upgrading from
 an older version and adding or removing some configuration information.

> 	# files/systemd/acpid.socket -> ListenStream=/run/acpid.socket
> 	mkdir -p "${ROOT}"/run
> 
> 	if ! grep -qs "^tmpfs.*/run " "${ROOT}"/proc/mounts ; then
> 		echo
> 		ewarn "You should reboot the system now to get /run mounted with tmpfs!"
> 	fi
> }

William


[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed

[Pacho Ramos]

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

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 README.kacpimon
> > 	dodoc -r samples
> > 	rm -f "${D}"/usr/share/doc/${PF}/COPYING
> > 
> > 	exeinto /etc/acpi
> > 	newexe "${FILESDIR}"/${PN}-1.0.6-default.sh default.sh
> > 	insinto /etc/acpi/events
> > 	newins "${FILESDIR}"/${PN}-1.0.4-default default
> > 
> > 	newinitd "${FILESDIR}"/${PN}-2.0.16-init.d ${PN}
> > 	newconfd "${FILESDIR}"/${PN}-2.0.16-conf.d ${PN}
> > 
> > 	systemd_dounit "${FILESDIR}"/systemd/${PN}.{service,socket}
> 
> 	local 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"
> 
> > 	configuration_create_doc
> 
>  	configuration_create_doc "${CONFIGURATION_INSTRUCTIONS}"
> > }
> > 
> > pkg_postinst() {
> > 	configuration_print_elog
>  
>  The thing that would change here would be that you would have to make
>  postinst smart enough to know when to call configuration_print_elog.
>  Maybe you do it all the time like this, or maybe you do it the first
>  time the package is installed, or you do it when you are upgrading from
>  an older version and adding or removing some configuration information.
> 

I thought about this but, for now, I preferred to only cover the
simplest case for handling messages that are always shown between
versions and can be easily standardized. For the other kind of messages,
I think it would be much more difficult to standardize but I think could
be added later when we start to migrate ebuilds and see the needings.

Best regards



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed

[William Hubbs]

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

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


[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] configuration-doc.eclass: an eclass to install a CONFIGURATION doc file and show an elog message first time package is installed

[Pacho Ramos]

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

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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]