Portage's documentation doesn't mention the epatch_user function at all. This tool allows an end-user to apply an additional patch to the source code, without having to change any ebuilds or create overlays. However, the ebuild that requires the patching must already contain the "epatch_user" function in the src_prepare() chunk. For example, wine-1.3.8 has an ebuild that calls this function. Lack of documentation includes: - Reference to /etc/portage/patches/package-category/packagename/my-extra-changes.patch in "man portage". - Gentoo Handbook, chapter 5 - Diverting from the Official Tree: http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=3&chap=5 - The Ebuild HOWTO as seen here: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=1#doc_chap2 does not mention epatch_user in the table of functions provided by "inherit eutils". - eutils.eclass manual: http://devmanual.gentoo.org/eclass-reference/eutils.eclass/index.html In fact, I was hard-pressed to find any kind of information at all. The only things I could find with Google were: - Forum thread: http://forums.gentoo.org/viewtopic-t-791464.html - Reading the code itself in: /usr/portage/eclass/eutils.eclass - Some Gentoo bugs asking for the inclusion of epatch_user in ebuilds. Reproducible: Always Steps to Reproduce: 1. Read any of the sources mentioned in the bug's description. 2. Notice the lack of documentation on even the existence of the epatch_user function. 3. Read the code in /usr/portage/eclass/eutils.eclass for a general idea of what the function is supposed to do. Actual Results: Complete lack of documentation. Expected Results: A clear documentation in the places where a Gentoo end-user may find it (Gentoo Handbook, man pages, et cetera). Perhaps some more information for beginning ebuild writers as well.
It isn't a portage feature/function, but a "hack" in an eclass...
(In reply to comment #1) > It isn't a portage feature/function, but a "hack" in an eclass... > How will end-users know about the existence of this "hack" if it isn't documented or mentioned anywhere? Hell, it's so obscure that even some Gentoo Developers are unaware of it: when I was informing about it on IRC I was told by a dev that "nope, Portage doesn't [have a way to apply an extra patch without altering ebuilds]". As an end-user, tbh, I was very happy to discover this way of applying my own patches. I suggest you give it some publicity - peoples will love the function/feature/"hack", can tell you that much.
This hack is one of the most massively useful "non-features" I've ever seen. It would be really really nice to have it documented (both in the eclass doc as well as some general "how to fix issues" handbooks) and to have as many ebuilds as feasible call it in one way or another. I know that since I found out about it, writing fixes for issues takes much less time, at least if the ebuild does call that function. I don't have to copy ebuilds to my overlay, I don't have to delete those versions I don't want to modify, I don't have to worry about keeping my overlay up to date as the main portage tree evolves... And in contrast to the "ebuild prepare && patch && ebuild merge" I used to do before, I know that my fix is going to stay. So please consider promoting epatch_user from an obscure hack to a well-documented feature. And perhaps add a bit of code to make multiple invocations harmless, i.e. touch some temp file at the first run and return immediately if that file exists. That way more ebuilds and eclasses could call the function without conflicting.
in the meanwhile i've discovered that PATCHES=/path/to/patches emerge -va package/atom also does the job.
epatch_user is an obscure hack, not a solution. The most important drawback is that it's impossible for developer to find out if user has applied some patches or not. Another problem is that some patches require other tools to be used (e.g. patching configure.ac requires autoreconf to be called) and epatch_user is unable to cope with this. We need better solution to address this problem.
(In reply to comment #5) > epatch_user is an obscure hack, not a solution. whether it is an hack or a proper solution, it IS present in the eclass as a public interface and should therefor be documented properly otherwise remove it completely... > We need better solution to address this problem. definitely... -> portage hooks are supposed to be the solution ;)
(In reply to comment #5) > The most important drawback is > that it's impossible for developer to find out if user has applied > some patches or not. grep 'Applying user patches' build.log. I think that the opposite is true: using the epatch_user approach, the build log will state that user patches have been applied, whereas that fact might go unnoticed if users address the issue in their own overlay, or apply patches through some bashrc hackery similar to http://dev.gentoo.org/~pva/bashrc but perhaps without the verbosity of that specific file, or simply modify the source tree manually between "ebuild prepare" and "ebuild merge". > Another problem is that some patches require other tools to be used > (e.g. patching configure.ac requires autoreconf to be called) and epatch_user > is unable to cope with this. It doesn't work for all cases, so let's not allow its use for any case? > We need better solution to address this problem. I agree that there is room for improvements. But that's not an unsolvable problem. It would be possible to add your automatic reconfigure calls or my stamp files to deal with duplicate invocations, without breaking the function as such. So unless you have a more detailed idea ready for discussion, I'd take what we have now, and improve on it as opportunities arise. (In reply to comment #6) > definitely... -> portage hooks are supposed to be the solution ;) Glad you don't really mean that: portage hooks in their current bashrc form would cause more divergence than epatch_user does. What term would I have to search for in build log files in order to find out whether user patches were applied? I used to have user patches as portage hooks, using a shell script file in the env dir of each affected package. One more file means one step more before I get things solved, which was annoying at best. So I was very glad when i could dump many of them in favour of epatch_user. Another reason to favour epatch_user over portage hooks: it gives you greater control over WHEN in the prepare phase your patches are applied. I'd say you'd usually want to apply user patches AFTER applying portage patches, so that the user patches won't keep portage patches from applying, and so that they can even undo portage patches if the need arises. Otoh they should be applied BEFORE any call to eautoreconf, so the patch can modify autotool input files in those cases that already do call eautoreconf. As both these things happen in the prepare phase, you can imo only achieve this through an eclass function. > whether it is an hack or a proper solution, it IS present in the eclass > as a public interface and should therefor be documented properly > otherwise remove it completely... At least for the eclass documentation, this is true. Advertising the function in the handbook or similar places might require more consensus about the advisability of the function. But the eclass man page should document the function as it exists. I believe it is already too late to simply remove the function, as there are many eclasses and ebuilds that use it, so you won't accept any additional commitment by documenting that the function exists.
(In reply to comment #7) Martin, you've raised valid points here. Personally I don't like current solution and I will not put it in my packages (without valid reason to have it there like it is for iptables). I'm not going to argue now how good or bad it is - such discussion should happen on the -dev mailing list. That said, please, provide patch and it'll be easier to consider/discuss and possibly apply it.
yes, the only thing stopping docs from being added to eutils.eclass is someone doing it and/or posting a patch for it (i'd merge clean docs). policy/developer buy-in is completely orthogonal and best put onto the -dev list.
Created attachment 282441 [details, diff] Documentation in eclass (v1) This patch adds documentation to the eclass. It also makes the function safe for repeated calls. Please merge as is or improve as you see fit.
this is surprisingly better than anything i was expecting :P http://sources.gentoo.org/eclass/eutils.eclass?r1=1.360&r2=1.361
