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]

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