[gentoo-dev] About the 'eapi' file in profile directories

[gentoo-dev] About the 'eapi' file in profile directories

[Joshua Kinard]

I can't find much documentation on the 'eapi' file found in many of the
profile directories.  Several of the ones in
profiles/arch/{amd64,sparc,mips} all report '5', and this aligns with the
mips 17.0 profile under default/linux.  Since EAPI 5 is deprecated, should
this file be edited to be at least EAPI 6 or 7, or is it a relic of the past
and really just needs to be tossed out?

If EAPI support is really needed in the profiles, it seems like there has to
be a better mechanism to codify it in a more central location versus
scattering ~390 of the things across the base profiles directory.

Thoughts?

-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
rsa6144/5C63F4E3F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And
our lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Sam James]

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



> On 31 Jul 2021, at 23:42, Joshua Kinard <kumba@gentoo.org> wrote:
> 
> 
> I can't find much documentation on the 'eapi' file found in many of the
> profile directories.  Several of the ones in
> profiles/arch/{amd64,sparc,mips} all report '5', and this aligns with the
> mips 17.0 profile under default/linux.  Since EAPI 5 is deprecated, should
> this file be edited to be at least EAPI 6 or 7, or is it a relic of the past
> and really just needs to be tossed out?
> 
> If EAPI support is really needed in the profiles, it seems like there has to
> be a better mechanism to codify it in a more central location versus
> scattering ~390 of the things across the base profiles directory.
> 
> Thoughts?

As far as I know, the only real documentation on this is in PMS [0]. Not much
changed in EAPIs 6, 7, or 8 for profiles and I think we're rather conservative
(a number of years) about increasing the baseline because it makes old
upgrades even more difficult.

I think there may be a guideline about that somewhere but I can't think where
it Is right now. There's a reference to it in the devmanual [1] when explaining
EAPI 8 - that page may have other useful information too.

TL;DR: We don't get much out of it and either the EAPIs are too new to use
in profiles or they didn't change anything relevant.

[0] https://dev.gentoo.org/~ulm/pms/head/pms.html#x1-450005.2.2
[1] https://devmanual.gentoo.org/ebuild-writing/eapi/#eapi-8-tree-layout

best,
sam

[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Joshua Kinard]

On 7/31/2021 18:47, Sam James wrote:
> 
> 
>> On 31 Jul 2021, at 23:42, Joshua Kinard <kumba@gentoo.org> wrote:
>>
>>
>> I can't find much documentation on the 'eapi' file found in many of the
>> profile directories.  Several of the ones in
>> profiles/arch/{amd64,sparc,mips} all report '5', and this aligns with the
>> mips 17.0 profile under default/linux.  Since EAPI 5 is deprecated, should
>> this file be edited to be at least EAPI 6 or 7, or is it a relic of the past
>> and really just needs to be tossed out?
>>
>> If EAPI support is really needed in the profiles, it seems like there has to
>> be a better mechanism to codify it in a more central location versus
>> scattering ~390 of the things across the base profiles directory.
>>
>> Thoughts?
> 
> As far as I know, the only real documentation on this is in PMS [0]. Not much
> changed in EAPIs 6, 7, or 8 for profiles and I think we're rather conservative
> (a number of years) about increasing the baseline because it makes old
> upgrades even more difficult.
> 
> I think there may be a guideline about that somewhere but I can't think where
> it Is right now. There's a reference to it in the devmanual [1] when explaining
> EAPI 8 - that page may have other useful information too.
> 
> TL;DR: We don't get much out of it and either the EAPIs are too new to use
> in profiles or they didn't change anything relevant.
> 
> [0] https://dev.gentoo.org/~ulm/pms/head/pms.html#x1-450005.2.2
> [1] https://devmanual.gentoo.org/ebuild-writing/eapi/#eapi-8-tree-layout
> 
> best,
> sam

Yeah, I found one mention in the Wiki[1], but not under "Profiles" in the
devmanual[2].  The Wiki description doesn't say why that file is needed in
every single subdirectory.

[1] https://wiki.gentoo.org/wiki/Profile_(Portage)#Profile_structure
[2] https://devmanual.gentoo.org/profiles/index.html

That said, the PMS reference actually provides the clearest explanation.  I
think that language should be in the devmanual at [2], as it also explains
the lack of inheritance.

The other devmanual reference only refers to a specific instance of that
file at the base of the profiles directory.

Okay, mystery solved.  We'll have to someday revisit why this file can't be
inherited, which would allow us to reduce the number of copies in the tree.

Thanks!,

-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
rsa6144/5C63F4E3F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And
our lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Sam James]

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



> On 1 Aug 2021, at 00:23, Joshua Kinard <kumba@gentoo.org> wrote:
> 
>> [snip]
> 
> Yeah, I found one mention in the Wiki[1], but not under "Profiles" in the
> devmanual[2].  The Wiki description doesn't say why that file is needed in
> every single subdirectory.
> 
> [1] https://wiki.gentoo.org/wiki/Profile_(Portage)#Profile_structure
> [2] https://devmanual.gentoo.org/profiles/index.html
> 
> That said, the PMS reference actually provides the clearest explanation.  I
> think that language should be in the devmanual at [2], as it also explains
> the lack of inheritance.
> 

Does this PR [0] for the devmanual help a bit? Let me know if you have feedback
(either here or on GitHub is fine, I don't mind).

> Okay, mystery solved.  We'll have to someday revisit why this file can't be
> inherited, which would allow us to reduce the number of copies in the tree.
> 

Yeah, I think this is worth investigating. I've wondered the same thing before.

[0]  https://github.com/gentoo/devmanual/pull/240

best,
sam

[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Joshua Kinard]

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

On 7/31/2021 22:02, Sam James wrote:
> 
> 
>> On 1 Aug 2021, at 00:23, Joshua Kinard <kumba@gentoo.org> wrote:
>>
>>> [snip]
>>
>> Yeah, I found one mention in the Wiki[1], but not under "Profiles" in the
>> devmanual[2].  The Wiki description doesn't say why that file is needed in
>> every single subdirectory.
>>
>> [1] https://wiki.gentoo.org/wiki/Profile_(Portage)#Profile_structure
>> [2] https://devmanual.gentoo.org/profiles/index.html
>>
>> That said, the PMS reference actually provides the clearest explanation.  I
>> think that language should be in the devmanual at [2], as it also explains
>> the lack of inheritance.
>>
> 
> Does this PR [0] for the devmanual help a bit? Let me know if you have feedback
> (either here or on GitHub is fine, I don't mind).
> 
>> Okay, mystery solved.  We'll have to someday revisit why this file can't be
>> inherited, which would allow us to reduce the number of copies in the tree.
>>
> 
> Yeah, I think this is worth investigating. I've wondered the same thing before.
> 
> [0]  https://github.com/gentoo/devmanual/pull/240
> 
> best,
> sam

That does help, thanks!

Let's go one further, though, and also add a mention of eapi, borrowing some
of the lingo from PMS, since the file is so prolific.  See the attached
patch and let me know how the language looks.

-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
rsa6144/5C63F4E3F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And
our lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic

[-- Attachment #2: devmanual_add-eapi-info.patch --]
[-- Type: text/plain, Size: 1034 bytes --]

diff --git a/profiles/eapi/text.xml b/profiles/eapi/text.xml
new file mode 100644
index 0000000..477ff24
--- /dev/null
+++ b/profiles/eapi/text.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<guide self="profiles/eapi/">
+<chapter>
+<title>Profiles <c>eapi</c> Files</title>
+<body>
+
+<p>
+An <c>eapi</c> file may be found in each profile directory.  If present, this
+file specifies the EAPI to use when handling the directory.  Otherwise, EAPI 0
+will be used instead.  The contents of the file is a single line specifying the
+numeric value of the supported EAPI.  This file is not inherited by <c>parent</c>
+nor in subdirectories.
+</p>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/profiles/text.xml b/profiles/text.xml
index 3269d33..87a8358 100644
--- a/profiles/text.xml
+++ b/profiles/text.xml
@@ -19,6 +19,7 @@ are also documented in <c>man portage</c>.
 </chapter>
 
 <include href="categories/"/>
+<include href="eapi/"/>
 <include href="info_files/"/>
 <include href="make.defaults/"/>
 <include href="package.mask/"/>

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Mart Raudsepp]

Ühel kenal päeval, P, 01.08.2021 kell 00:58, kirjutas Joshua Kinard:
> numeric value of the supported EAPI

EAPI isn't a numeric value, it is a string (section 3.1.8) - it just
happens that Gentoo official ones are logically numeric. PMS even
quotes the EAPIs in "2.2 Defined EAPIs" section to signify that, it
seems.

So s/numeric value/name/ as per PMS section 5.2.2?


Mart

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Joshua Kinard]

On 8/1/2021 08:19, Mart Raudsepp wrote:
> Ühel kenal päeval, P, 01.08.2021 kell 00:58, kirjutas Joshua Kinard:
>> numeric value of the supported EAPI
> 
> EAPI isn't a numeric value, it is a string (section 3.1.8) - it just
> happens that Gentoo official ones are logically numeric. PMS even
> quotes the EAPIs in "2.2 Defined EAPIs" section to signify that, it
> seems.
> 
> So s/numeric value/name/ as per PMS section 5.2.2?
> 
> 
> Mart

I used "numeric" so that someone would know to type "5" without quotes,
since the file is literally only supposed to have a single character in it.
 It's more or less irrelevant whether its a string or integer at this point.
 Just one way to differentiate them is strings are usually quoted while raw
integers are not.

-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
rsa6144/5C63F4E3F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And
our lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Joshua Kinard]

On 8/1/2021 08:19, Mart Raudsepp wrote:
> Ühel kenal päeval, P, 01.08.2021 kell 00:58, kirjutas Joshua Kinard:
>> numeric value of the supported EAPI
> 
> EAPI isn't a numeric value, it is a string (section 3.1.8) - it just
> happens that Gentoo official ones are logically numeric. PMS even
> quotes the EAPIs in "2.2 Defined EAPIs" section to signify that, it
> seems.
> 
> So s/numeric value/name/ as per PMS section 5.2.2?

So it looks like Section 2.3, "Reserved EAPIs" is more relevant here:

    2.3 Reserved EAPIs

        EAPIs whose value consists purely of an integer are reserved
        for future versions of this specification.

        EAPIs whose value starts with the string paludis- are reserved
        for experimental use by the Paludis package manager.

That means that, yes, EAPIs can be literal string values (just without
quotes).  However, the primary use case, IOW, the official repo, we're using
incrementing numeric integers.  PMS is supposed to be package-manager
agnostic, so carving out a specific reservation for a specific package
manager in Section 2.3 seems to defeat that purpose.

If Paludis is still being developed and needs something for experimental
use, then it's up to it to do that on its own.  We could support this by
specifying that EAPIs are single-line strings of a form [A-Za-z0-9\x20_-]+?,
thus removing the specific reservation for a specific package manager and
handling the current single-number format as well as other fancy names.
Like maybe EAPI 9 can be "Magnificent Penguin"? :)

-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
rsa6144/5C63F4E3F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And
our lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Ulrich Mueller]

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

>>>>> On Sun, 01 Aug 2021, Joshua Kinard wrote:

> So it looks like Section 2.3, "Reserved EAPIs" is more relevant here:

>     2.3 Reserved EAPIs

>         EAPIs whose value consists purely of an integer are reserved
>         for future versions of this specification.

>         EAPIs whose value starts with the string paludis- are reserved
>         for experimental use by the Paludis package manager.

> That means that, yes, EAPIs can be literal string values (just without
> quotes).  However, the primary use case, IOW, the official repo, we're
> using incrementing numeric integers.

No, it only says that unofficial EAPIs cannot be pure integers.
The reverse conclusion does not follow.

> PMS is supposed to be package-manager agnostic, so carving out a
> specific reservation for a specific package manager in Section 2.3
> seems to defeat that purpose.

Quoting ciaranm [1]:

| > "EAPIs whose value starts with the string paludis- are reserved for
| > experimental use by the Paludis package manager."
|
| Don't tell anyone, but that's mostly just in there because some people
| insisted that EAPIs were numbers (and thus comparable), so I wanted an
| explicit mention of one that wasn't.

> If Paludis is still being developed and needs something for
> experimental use, then it's up to it to do that on its own. We could
> support this by specifying that EAPIs are single-line strings of a
> form [A-Za-z0-9\x20_-]+?, thus removing the specific reservation for a
> specific package manager and handling the current single-number format
> as well as other fancy names. Like maybe EAPI 9 can be "Magnificent
> Penguin"? :)

PMS specifies what characters are allowed in an EAPI name [2], namely
the same as in a slot name:

| An EAPI name may contain any of the characters [A-Za-z0-9+_.-].
| It must not begin with a hyphen, a dot or a plus sign.

Ulrich

[1] https://archives.gentoo.org/gentoo-pms/message/98cdbfbe67a19c0fea5cc69e8b8ea2fe
[2] https://projects.gentoo.org/pms/8/pms.html#x1-240003.1.8

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Rich Freeman]

On Sun, Aug 1, 2021 at 5:54 PM Ulrich Mueller <ulm@gentoo.org> wrote:
>
> Quoting ciaranm [1]:
>
> | > "EAPIs whose value starts with the string paludis- are reserved for
> | > experimental use by the Paludis package manager."
> |
> | Don't tell anyone, but that's mostly just in there because some people
> | insisted that EAPIs were numbers (and thus comparable), so I wanted an
> | explicit mention of one that wasn't.
>

The other aspect of it is that they cannot be assumed to be ordered.
You could at some point in the future have a branching hierarchy of
sorts where some EAPIs contain some features and others contain
others, with neither being a superset of the other even accounting for
deprecation.

I get that we haven't generally done that historically, but you
shouldn't be doing ordered/range/etc comparisons with EAPIs (ie "if
EAPI < 5 do this, else do that").  Such things should always be based
on explicit values ("if EAPI in (1,2,3,4) do this, else do that").

-- 
Rich

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Ulrich Mueller]

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

>>>>> On Sun, 01 Aug 2021, Joshua Kinard wrote:

> Let's go one further, though, and also add a mention of eapi, borrowing some
> of the lingo from PMS, since the file is so prolific.  See the attached
> patch and let me know how the language looks.

> diff --git a/profiles/eapi/text.xml b/profiles/eapi/text.xml
> new file mode 100644
> index 0000000..477ff24
> --- /dev/null
> +++ b/profiles/eapi/text.xml
> @@ -0,0 +1,18 @@
> +<?xml version="1.0"?>
> +<guide self="profiles/eapi/">
> +<chapter>
> +<title>Profiles <c>eapi</c> Files</title>
> +<body>
> +
> +<p>
> +An <c>eapi</c> file may be found in each profile directory.  If present, this
> +file specifies the EAPI to use when handling the directory.  Otherwise, EAPI 0
> +will be used instead.  The contents of the file is a single line specifying the
> +numeric value of the supported EAPI.  This file is not inherited by <c>parent</c>
> +nor in subdirectories.
> +</p>
> +
> +</body>
> +</chapter>
> +</guide>
> +

This doesn't really belong there, because the "Profiles" chapter in the
devmanual describes only the top-level profiles dir. So the wording from
https://projects.gentoo.org/pms/8/pms.html#x1-320004.4 would apply
(for the single profiles/eapi file):

| The profiles directory may contain an \t{eapi} file. This file, if it
| exists, must contain a single line with the name of an EAPI\@. This
| specifies the EAPI to use when handling the profiles directory; a
| package manager must not attempt to use any repository whose profiles
| directory requires an EAPI it does not support. If no \t{eapi} file is
| present, EAPI 0 shall be used.

That said (and hard to believe), the devmanual currently doesn't
describe the profile tree at all.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Ulrich Mueller]

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

>>>>> On Sun, 01 Aug 2021, Joshua Kinard wrote:

> I can't find much documentation on the 'eapi' file found in many of the
> profile directories.  Several of the ones in
> profiles/arch/{amd64,sparc,mips} all report '5', and this aligns with the
> mips 17.0 profile under default/linux.  Since EAPI 5 is deprecated, should
> this file be edited to be at least EAPI 6 or 7, or is it a relic of the past
> and really just needs to be tossed out?

EAPIs 6, 7, and 8 don't come with any changes related to profiles,
therefore updating the EAPI in profiles won't have any benefits. We can
leave it at 5, for the time being.

(EAPI 8 has a change in the updates directory, but that will only affect
the eapi in the top-level profiles directory, not individual profiles.
Also, we're at least two years away from updating that.)

We keep track of profile EAPIs here:
https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification#Council_approval_and_use_in_Gentoo_repository

> If EAPI support is really needed in the profiles, it seems like there has to
> be a better mechanism to codify it in a more central location versus
> scattering ~390 of the things across the base profiles directory.

It's required by PMS, and it's not inherited from the parent profile,
so there's nothing that could be done about it for now.

$ for d in $(find . -type f ! -path './desc/*' ! -path './updates/*' ! -name eapi -printf '%h\n' | sort -u); do [[ -f ${d}/eapi ]] || echo ${d}; done
./arch/amd64/lib32
./arch/mips/mipsel
./arch/ppc64/big-endian
./default/linux/amd64/17.0/no-multilib/prefix
./default/linux/amd64/17.1/no-multilib/prefix
./default/linux/arm/17.0/armv7a/prefix
./default/linux/arm64/17.0/prefix
./default/linux/ppc64le/17.0/prefix
./default/linux/x86/17.0/prefix
./features/prefix/standalone/kernel-2.6.16+
./features/prefix/standalone/kernel-2.6.32+
./prefix/darwin/macos/features/fsf-gcc-ld64
./prefix/darwin/macos/features/fsf-gcc-nold

Looks like we have a few profiles that are missing the eapi file, so
effectively they are still at EAPI 0.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] About the 'eapi' file in profile directories

[Ulrich Mueller]

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

>>>>> On Sun, 01 Aug 2021, Joshua Kinard wrote:

> If EAPI support is really needed in the profiles, it seems like there
> has to be a better mechanism to codify it in a more central location
> versus scattering ~390 of the things across the base profiles
> directory.

I have filed https://bugs.gentoo.org/806181 for this.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]