The man page for portage should make clear which files are for user changes. A proposed addition is below. The first and last (4th) paragraph are from the current man page; the middle two paragraphs are new. The current portage code uses many different configuration files, most of which are unknown to users and normal developers. Here we will try to collect all the odds and ends so as to help users more effectively utilize portage. This is a reference only for files which do not already have a man page. Note that users should place in make.conf local changes that are to apply to all emerges; per-package changes belong in the /etc/portage directory, creating any needed files listed below that do not exist. The files are listed in increasing order of priority. The make.profile directory, which is a symlink into the /usr/portage tree, is for system defaults. Like all of the /usr/portage tree, these files are overwritten when an emerge sync is performed. Hence users normally do *not* alter these files. All files in the make.profile directory may be tweaked via parent pro- files when using cascading profiles. For more info, please see http://www.gentoo.org/proj/en/releng/docs/cascading-profiles.xml Reproducible: Always Steps to Reproduce: 1. man portage 2. 3. Actual Results: man page does not make clear which files are for user changes Expected Results: man page makes clear which files are for user changes
make.conf is already described as "The global customs settings for portage", i dont see a need to further describe it. /etc/portage isnt just for per-package changes. the individual files are properly described in the /etc/portage section.
(In reply to comment #1) > make.conf is already described as "The global customs settings for portage", i > dont see a need to further describe it. > > /etc/portage isnt just for per-package changes. the individual files are > properly described in the /etc/portage section. The make.conf vs /etc/portage distinction was suggested in the gentoo-user newsgroup. You can drop it if you think it is not helpful. However, the point about using those two instead of make.profile remains. The two new paragraphs can be combined to give. Note that users should place local changes in /etc/make.conf and /etc/portage/* as described below, creating any of the latter that are missing. The make.profile directory, which is a symlink into the /usr/portage tree, is for system defaults. Like all of the /usr/portage tree, these files are overwritten when an emerge sync is performed. Hence users normally do *not* alter these files.
Are you reading a different manpage, or what's the point of duplicating the info already contained there? <snip> /etc/make.profile/ This is usually just a symlink to the correct profile in /usr/portage/profiles/. Since it is part of the portage tree, it may easily be updated/regenerated by running `emerge --sync`. It defines what a profile is (usually arch specific stuff). If you need a custom profile, then you should make your own /etc/make.profile/ directory and populate it. However, if you just wish to override some settings, do NOT edit these files because they WILL be lost with the next `emerge --sync`. See the section below on /etc/portage/ for overriding. </snip>
(In reply to comment #3) > Are you reading a different manpage, or what's the point of duplicating the > info already contained there? > > <snip> > /etc/make.profile/ > This is usually just a symlink to the correct profile in > /usr/portage/profiles/. Since it is part of the portage tree, it may easily > be updated/regenerated by running `emerge --sync`. It defines what a profile > is (usually arch specific stuff). If you need a custom profile, then you > should make your own /etc/make.profile/ directory and populate it. However, > if you just wish to override some settings, do NOT edit these files because > they WILL be lost with the next `emerge --sync`. See the section below on > /etc/portage/ for overriding. > </snip> > I must confess to not seeing this, but can add that no one on the group pointed it out and a few people wrote messages. I still think the general comment belongs in the top (and repeated where it is in the current man page). If a user wants to mask a use flag s/he searches for use and mask and finds package.use.mask and then notices it is in make.profile. S/he doubtless *should* read the words in make.profile, but I and apparently some others didn't. I did read the beginning of the (long, as it needs to be) man page. The proposed new paragraph I would argue gives the general setting, "changes go here and not there" in one place, short, at the beginning. I will agree that the material is already in the man page, but currently it is not summarized in one place.
(In reply to comment #3) > /etc/make.profile/ > This is usually just a symlink to the correct profile in > /usr/portage/profiles/. Since it is part of the portage tree, it may > easily be updated/regenerated by running `emerge --sync`. It defines what a > profile is (usually arch specific stuff). If you need a custom profile, > then you should make your own /etc/make.profile/ directory and populate > it. However, if you just wish to override some settings, do NOT edit these > files because they WILL be lost with the next `emerge --sync`. See the > section below on /etc/portage/ for overriding. I think that this information is sufficient to mark this bug as WORKSFORME.
Created attachment 126196 [details, diff] clarify the relationship between /etc/make.profile/ and /etc/portage/profile/ Hopefully this patch clarifies it enough. It's in svn r7414.
This has been released in 2.1.3.
