[gentoo-portage-dev] [PATCH] man pages: note that make.conf can be a directory (463266)

[gentoo-portage-dev] [PATCH] man pages: note that make.conf can be a directory (463266)

[Zac Medico]

Commit 86e75790954e766beba75443d967b2c25055c5b0 added support for
make.conf to be a directory, but the feature was undocumented.
Therefore, update the man pages, as suggested in bug #465164,
comment #9.

Fixes 86e75790954e ("make.conf: recurse directories, bug #463266")
X-Gentoo-Bug: 463266
X-Gentoo-Bug-URL: https://bugs.gentoo.org/show_bug.cgi?id=463266
---
 man/make.conf.5 | 5 ++++-
 man/portage.5   | 3 ++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/man/make.conf.5 b/man/make.conf.5
index 69d95fc..a7adecc 100644
--- a/man/make.conf.5
+++ b/man/make.conf.5
@@ -1,4 +1,4 @@
-.TH "MAKE.CONF" "5" "Apr 2014" "Portage VERSION" "Portage"
+.TH "MAKE.CONF" "5" "December 2014" "Portage VERSION" "Portage"
 .SH "NAME"
 make.conf \- custom settings for Portage
 .SH "SYNOPSIS"
@@ -14,6 +14,9 @@ features like arrays and special parameter expansions. For more details, see
 the Simple lexical analysis documentation:
 \fLhttp://docs.python.org/3/library/shlex.html\fR. Note that if you source
 files, they need to be in the same shlex syntax for portage to read them.
+If make.conf is a directory, then all the files in that directory will
+be sorted in ascending alphabetical order by file name and summed
+together as if it were a single file.
 .br
 Portage will check the currently\-defined environment variables
 first for any settings.  If no environment settings are found,
diff --git a/man/portage.5 b/man/portage.5
index 88cf3bb..542ffeb 100644
--- a/man/portage.5
+++ b/man/portage.5
@@ -568,7 +568,8 @@ virtual/aspell\-dict   app\-dicts/aspell\-en
 .RE
 .TP
 .BR /etc/portage/
-Any file in this directory that begins with "package." or is repos.conf can be
+Files in this directory including make.conf, repos.conf, and any file
+with a name that begins with "package." can be
 more than just a flat file.  If it is a directory, then all the files in that
 directory will be sorted in ascending alphabetical order by file name and summed
 together as if it were a single file.
-- 
2.0.5

[gentoo-portage-dev] Re: [PATCH] man pages: note that make.conf can be a directory (463266)

[Duncan]

Zac Medico posted on Fri, 26 Dec 2014 14:01:47 -0800 as excerpted:

> Commit 86e75790954e766beba75443d967b2c25055c5b0 added support for
> make.conf to be a directory, but the feature was undocumented.
> Therefore, update the man pages, as suggested in bug #465164, comment
> #9.

What about other apps that parse make.conf?  A note that this might break 
compatibility with some of them, and/or with other scripts people 
sometimes post on the forums, lists, etc, could be worthwhile.

I believe that's why I chose to stick with a make.conf file that simply 
sourced a bunch of other files, instead of simply making it a directory 
and sticking all those other files in the dir, when I first read about  
the possibility.  I have scripts myself that simply source make.conf, 
that I'd have to rewrite with a for loop to process a directory.  It's 
not hard to do, but people haven't had to worry about it and so they 
haven't.  If people aren't thinking about that when they up and make 
make.conf a directory, they might well wish they had! =8^0

Most of the others I've made dirs, tho.  It's much easier configuring 
portage that way, and as I said, my make.conf is already just a bunch of 
source directives, giving me pretty much the best of both worlds. =:^)

(Until I add a new configuration file and forget to add a corresponding 
source line for it in make.conf, as I did recently. =:^(  )

I'll eventually do make.conf as well, but it's not worth worrying about 
changing my scripts until all the packages that reference it are known to 
handle it.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-portage-dev] Re: [PATCH] man pages: note that make.conf can be a directory (463266)

[Zac Medico]

On 12/26/2014 10:22 PM, Duncan wrote:
> Zac Medico posted on Fri, 26 Dec 2014 14:01:47 -0800 as excerpted:
> 
>> Commit 86e75790954e766beba75443d967b2c25055c5b0 added support for
>> make.conf to be a directory, but the feature was undocumented.
>> Therefore, update the man pages, as suggested in bug #465164, comment
>> #9.
> 
> What about other apps that parse make.conf?  A note that this might break 
> compatibility with some of them, and/or with other scripts people 
> sometimes post on the forums, lists, etc, could be worthwhile.

I think this goes without saying. External tools would really be better
off calling 'portageq envvar' than parsing make.conf directly. I think
it's fine to let people discover such issues themselves, and report bugs
for the corresponding tools. Maybe that will help generate some noise
that will give the maintainers some incentive to fix those tools.

Cluttering our documentation with compatibility notes that will
eventually become outdated seems kind of pointless. Also, such notes are
not necessarily relevant to all users, so that's another reason I would
prefer to omit them.

> I believe that's why I chose to stick with a make.conf file that simply 
> sourced a bunch of other files, instead of simply making it a directory 
> and sticking all those other files in the dir, when I first read about  
> the possibility.  I have scripts myself that simply source make.conf, 
> that I'd have to rewrite with a for loop to process a directory.  It's 
> not hard to do, but people haven't had to worry about it and so they 
> haven't.  If people aren't thinking about that when they up and make 
> make.conf a directory, they might well wish they had! =8^0

Why don't you use 'portageq envvar'?

> Most of the others I've made dirs, tho.  It's much easier configuring 
> portage that way, and as I said, my make.conf is already just a bunch of 
> source directives, giving me pretty much the best of both worlds. =:^)
> 
> (Until I add a new configuration file and forget to add a corresponding 
> source line for it in make.conf, as I did recently. =:^(  )
> 
> I'll eventually do make.conf as well, but it's not worth worrying about 
> changing my scripts until all the packages that reference it are known to 
> handle it.

These bug reports for euse, euses, and ufed come to mind:

	https://bugs.gentoo.org/show_bug.cgi?id=474574
	https://bugs.gentoo.org/show_bug.cgi?id=478318

If I actually used any of those tools, then they probably would have
been fixed long ago.
-- 
Thanks,
Zac

[gentoo-portage-dev] Re: [PATCH] man pages: note that make.conf can be a directory (463266)

[Duncan]

Zac Medico posted on Fri, 26 Dec 2014 22:52:42 -0800 as excerpted:

>> I believe that's why I chose to stick with a make.conf file that simply
>> sourced a bunch of other files, instead of simply making it a directory
>> and sticking all those other files in the dir, when I first read about
>> the possibility.  I have scripts myself that simply source make.conf,
>> that I'd have to rewrite with a for loop to process a directory.  It's
>> not hard to do, but people haven't had to worry about it and so they
>> haven't.  If people aren't thinking about that when they up and make
>> make.conf a directory, they might well wish they had! =8^0
> 
> Why don't you use 'portageq envvar'?

Thanks for the hint.  I will likely use it. =:^)

Which hints at half the answer to your question; I didn't really know 
about it.  The other half of the answer is simple.  It was never needed 
before, as sourcing make.conf always "just worked".  Now that it's 
needed... Thanks again!  =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-portage-dev] Re: [PATCH] man pages: note that make.conf can be a directory (463266)

[Zac Medico]

On 12/28/2014 06:55 PM, Duncan wrote:
> Zac Medico posted on Fri, 26 Dec 2014 22:52:42 -0800 as excerpted:
> 
>>> I believe that's why I chose to stick with a make.conf file that simply
>>> sourced a bunch of other files, instead of simply making it a directory
>>> and sticking all those other files in the dir, when I first read about
>>> the possibility.  I have scripts myself that simply source make.conf,
>>> that I'd have to rewrite with a for loop to process a directory.  It's
>>> not hard to do, but people haven't had to worry about it and so they
>>> haven't.  If people aren't thinking about that when they up and make
>>> make.conf a directory, they might well wish they had! =8^0
>>
>> Why don't you use 'portageq envvar'?
> 
> Thanks for the hint.  I will likely use it. =:^)
> 
> Which hints at half the answer to your question; I didn't really know 
> about it.  The other half of the answer is simple.  It was never needed 
> before, as sourcing make.conf always "just worked".  Now that it's 
> needed... Thanks again!  =:^)

Note that it's handy to pull multiple variables into your environment
with a single portageq call like this:

	eval "$(portage envvar -v VARIABLE_1 VARIABLE_2 ...)"

For example, we use this construct in emerge-webrsync.
-- 
Thanks,
Zac

Re: [gentoo-portage-dev] [PATCH] man pages: note that make.conf can be a directory (463266)

[Alexander Berntsen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

LGTM, go ahead & merge.

- -- 
Alexander
bernalex@gentoo.org
https://secure.plaimi.net/~alexander
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iF0EAREIAAYFAlSqjcIACgkQRtClrXBQc7Uj8ADzBW0kDWclO7KlB68oD218pRjZ
cgc7Fz29x6BDEZVbjAEAn8NSq1kDMYTlmjrOnhIy7DOjLnr1K5Ijg8J6rIgK+WM=
=xDQ1
-----END PGP SIGNATURE-----