The Handbook still refers to the deprecated RSYNC_EXCLUDEFROM feature and needs to be updated to use PORTAGE_RSYNC_EXTRA_OPTS instead. Relevent page: http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=5
For the record, the new syntax is: PORTAGE_RSYNC_EXTRA_OPTS="--exclude-from=/etc/portage/rsync_excludes" The rsync section needs to be rewritten now that portage-2.1 is stable for all arches. It's all done by PORTAGE_RSYNC_EXTRA_OPTS="" followed by whatever option you're changing. Might be a good idea to review the rest of the Portage handbook and see what else needs changing now that we're all on 2.1. CCing the Portage team for any additional input on the new doc. I'd like to get this done in time for the 2006.1 release, if at all possible.
(In reply to comment #1) > For the record, the new syntax is: > PORTAGE_RSYNC_EXTRA_OPTS="--exclude-from=/etc/portage/rsync_excludes" > > The rsync section needs to be rewritten now that portage-2.1 is stable for all > arches. It's all done by PORTAGE_RSYNC_EXTRA_OPTS="" followed by whatever > option you're changing. > > Might be a good idea to review the rest of the Portage handbook and see what > else needs changing now that we're all on 2.1. > > CCing the Portage team for any additional input on the new doc. I'd like to get > this done in time for the 2006.1 release, if at all possible. > I can go over new features and whatnot with you; I will be available probably after after 6pm EST today if you want to find me on irc.
From the top of my head, 2 other things I use: color map & parallel-fetch
(In reply to comment #2) > I can go over new features and whatnot with you; I will be available probably > after after 6pm EST today if you want to find me on irc. Sure, email me and we'll go over it, or see my list of TODOs for the portage handbook available in my devspace[1] and post/comment on 'em here, if you prefer not to email me (i'm fine with either). [1] http://dev.gentoo.org/~nightmorph/misc/portage-doc-todo.txt If you think of anything else I should cover besides these, let me know. This is the new stuff I picked out of make.conf compared to portage-2.0.x.
Created attachment 101020 [details, diff] hb-portage-configuration.xml.patch Okay, first draft of the stuff I gleaned from make.conf.example (not much in there :/) as well as reading /usr/bin/emerge. This patch is for hb-portage-configuration.xml; I will of course attach separate patches for the other section. One question: while reading /usr/bin/emerge, I noticed that there seemed to be a PORTAGE_RSYNC_EXTRA_OPTS variable called --bwlimit=%s. What's that about? Is that an actual option like --timeout=30?
CCing antarus by request.
Created attachment 101022 [details, diff] hb-portage-files.xml.patch Patch for hb-portage-files.xml. Covers logging via the new elog extensively. Hey Portage guys/antarus/whoever, can you double check to make sure that I have the ideas right in the descriptions? Thanks.
Created attachment 101023 [details, diff] hb-working-features.xml.patch Patch for the FEATURES section of the Portage handbook. I added a new subsection on fetching files, since those were the only features that needed additional clarification (everything else in make.conf.example is really straightforward). One question: what on earth is metadata-transfer really used for? Why is it useful? I still need to add that to the doc.
(In reply to comment #7) > Created an attachment (id=101022) [edit] > hb-portage-files.xml.patch + log: Compilation log for an ebuild. As most compilations print out + quite a lot of text, this can rapidly take up space on your disks. This is wrong! log just logs elog's. Any einfo which the user is supposed to see should be converted to an elog. The default is "log warn error"... + save: This saves one log per package in <path>$PORT_LOGDIR/elog</path>, + or <path>/var/log/portage/elog</path> if $PORT_LOGDIR is not defined. It saves it whether $PORT_LOGDIR is defined or not. But obviously for packages that have one of the emessages specified in PORTAGE_ELOG_CLASSES. + PORTAGE_ELOG_COMMAND="/path/to/logger -p '\${PACKAGE}' -f '\${LOGFILE'" A } is missing. :) + PORTAGE_ELOG_MAILURI="user@some.domain + username:password@smtp.some.domain:100465" This example used port 465 and enables starttls. Probably needs a bit more explanation (you can copy some of the text from /etc/make.conf.example). The sendmail option should be covered too. Like e.g.: PORTAGE_ELOG_MAILURI="root /usr/sbin/sendmail"
Created attachment 101025 [details, diff] hb-portage-files.xml.patch Revised patch. (In reply to comment #9) > It saves it whether $PORT_LOGDIR is defined or not. But obviously for packages > that have one of the emessages specified in PORTAGE_ELOG_CLASSES. This stays as-is; it's good for users to know how directories are treated by default. > + PORTAGE_ELOG_COMMAND="/path/to/logger -p '\${PACKAGE}' -f > '\${LOGFILE'" > > A } is missing. :) Fixed. > This example used port 465 and enables starttls. Probably needs a bit more > explanation (you can copy some of the text from /etc/make.conf.example). No, I think the man page has a better explanation, so I'll just use a slightly simpler example for port 995. > The > sendmail option should be covered too. Again, sometimes it's best to just let the manpage and/or /etc/make.conf.example spell it out, so I'll leave it to the user to check that for mail binaries.
(In reply to comment #10) > Created an attachment (id=101025) [edit] > hb-portage-files.xml.patch > > Revised patch. > > (In reply to comment #9) > > It saves it whether $PORT_LOGDIR is defined or not. But obviously for > > packages that have one of the emessages specified in PORTAGE_ELOG_CLASSES. > This stays as-is; it's good for users to know how directories are treated by > default. I had misread this part and it is correct, sorry. I'm wondering if it should refer to 1.d [1] or something. After reading this part a user might decide to set PORT_LOGDIR without realizing the side effect..? On the other hand 1.d isn't far away from this part so perhaps it isn't necessary. Actually it might be a good idea to rephrase 1.d. It says "Portage can create per-ebuild logfiles [...]" but I'm wondering if that makes it clear that if PORT_LOGDIR is set it will create per-ebuild logfiles... Before the elog system the user had no reason to set it unless he wanted that but with the elog system he does have another reason. [1]http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=1#doc_chap4 [SNIP] I agree with the rest of this comment. I hadn't quite realized where this was going.
Created attachment 101071 [details, diff] hb-portage-configuration.xml.patch Revised to show the proper format for --exclude='/distfiles' et al.
@features: - drop the comment about cpu usage in parallel-fetch, it's virtually non-existant and would just confuse people. - metadata-transfer simply retains the cache update after a sync (it's enabled by default). It can be useful to disable this when using the metadata-overlay cache backend or when you run a emerge --metadata later on anyway (for example after syncing overlays). @configuration: - either drop the AUTOCLEAN comment or make it even more obvious (e.g. with <warn>) that this is extremely discouraged. Also it might be dropped in the (near) future. - for PORTAGE_RSYNC_OPTS might add a note that certain absolutely required options will always be used even if PORTAGE_RSYNC_OPTS is empty. - add a pointer to the rsync manpage for PORTAGE_RSYNC_EXTRA_OPTS - for rsync exclude handling please add another pointer to the rsync manpage for the exact syntax. I'd also drop the "one line per cat/pkg" part as it gives the impression that this is the only usable variant. - certain rsync options are implied by emerge options (e.g. emerge --quiet implies rsync --quiet), this might be worth another note. @files: - "log" isn't supposed to be "special", so don't call it that way. - "error" just includes eerror messages, not die messages, so the summary is wrong. Also if a build fails nothing is logged at all (by elog) as the relevant codepath isn't reached (might change in the future). - add a note about the side-effect of defining $PORT_LOGDIR - add a big fat note that elog and the (unofficial) enotice are completely incompatible and will break/disable each other. - some elog features (MAIL_FROM and MAIL_SUBJECT) require >=portage-2.1.1, I guess that's worth to mention somewhere.
Created attachment 101111 [details, diff] hb-portage-configuration.xml.patch Revised version.
Created attachment 101112 [details, diff] hb-portage-files.xml.patch Revised.
Created attachment 101113 [details, diff] hb-working-features.xml.patch Revised.
(In reply to comment #13) > @features: > - drop the comment about cpu usage in parallel-fetch, it's virtually > non-existant and would just confuse people. > - metadata-transfer simply retains the cache update after a sync (it's enabled > by default). It can be useful to disable this when using the metadata-overlay > cache backend or when you run a emerge --metadata later on anyway (for example > after syncing overlays). - Done. - Dropped description entirely; just one of those things that should be seen in the manpage. > @configuration: > - either drop the AUTOCLEAN comment or make it even more obvious (e.g. with > <warn>) that this is extremely discouraged. Also it might be dropped in the > (near) future. > - for PORTAGE_RSYNC_OPTS might add a note that certain absolutely required > options will always be used even if PORTAGE_RSYNC_OPTS is empty. > - add a pointer to the rsync manpage for PORTAGE_RSYNC_EXTRA_OPTS > - for rsync exclude handling please add another pointer to the rsync manpage > for the exact syntax. I'd also drop the "one line per cat/pkg" part as it gives > the impression that this is the only usable variant. > - certain rsync options are implied by emerge options (e.g. emerge --quiet > implies rsync --quiet), this might be worth another note. - Dropped AUTOCLEAN section. - Done. - There's already a few urges to read the rsync & portage manpages, but I added a specific one at the end of the RSYNC/EXTRA_OPTS section. - Done; dropped details on it, instead referring users to the existing discussion of it on another Portage handbook page (that I just updated yesterday :)). > @files: > - "log" isn't supposed to be "special", so don't call it that way. > - "error" just includes eerror messages, not die messages, so the summary is > wrong. Also if a build fails nothing is logged at all (by elog) as the relevant > codepath isn't reached (might change in the future). > - add a note about the side-effect of defining $PORT_LOGDIR > - add a big fat note that elog and the (unofficial) enotice are completely > incompatible and will break/disable each other. > - some elog features (MAIL_FROM and MAIL_SUBJECT) require >=portage-2.1.1, I > guess that's worth to mention somewhere. - Done. - Done. - What side effect is this? Please be more specific. - We don't care about enotice...I'm don't think I've ever heard of it, so it's not worth mentioning just because we have two users (does it have a small userbase?) who use this unofficial whatsit. - Done; added to the mail introduction. So, aside from my one question on the -files.xml doc, what else should happen? I'd like to get this finished & added ASAP.
> - What side effect is this? Please be more specific. If you don't define PORTLOG_DIR then you get no build logs (using the 'old' logging system, you may still get some logs from elog depending on your settings and if the build completed) If you define PORTLOG_DIR you get build logs IN ADDITION TO any elog settings you may have.
Created attachment 101114 [details, diff] hb-portage-files.xml.patch (In reply to comment #18) Revised; thanks for the explanation. Look good?
(In reply to comment #17) > - We don't care about enotice...I'm don't think I've ever heard of it, so it's > not worth mentioning just because we have two users (does it have a small > userbase?) who use this unofficial whatsit. It was a quite popular hack for portage-2.0 (see bug #11359). The problem is that the breakage is subtle, so people wonder why elog doesn't work as advertised and solving such support issues can take some time if you don't think about enotice right at the start. Just add a <impo>If you used enotice with portage-2.0 you have to remove it completely before you can use elog as they are completely incompatible systems.</impo> or so.
Created attachment 101119 [details, diff] hb-portage-files.xml.patch As requested by genone. I hadn't realized it was a hack.
All done. Thanks to antarus, genone, bo, and zmedico for reviewing. (removed --checksum from hb-portage-config since it wasn't a useful option for rsync; thanks to zmedico on irc). Fixed in CVS!
