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]

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