I was trying to update an ebuild but when I ran the "ebuild package merge" command, I only got a "doebuild(): aux_get() error; aborting" error. On the IRC channel someone told me to set PORTDIR_OVERLAY in the /etc/make.conf. Nowhere in the ebuild documentation this is explained. Maybe there should be a sort of step-by-step documentation like there is in the gentoo installation guide.
PORTDIR_OVERLAY is a variable in which you define where your self-made ebuilds are located. I don't think this has anything to do with what you encounter. PORTDIR_OVERLAY is documented in the portage manual: http://www.gentoo.org/doc/en/portage-manual.xml
Can you use/test ebuilds without PORTDIR_OVERLAY? Once I set it up and copy the ebuild in the directory, I stopped getting the error and was able to test my ebuild. I guess I could have copied the file in /usr/portage too but even that isn't in the "Gentoo Linux Developers HOWTO" (a.k.a "Ebuild HOWTO"). So it does seem to have been my problem. I followed the HOWTO and I couldn't use my ebuild until I set up the PORTDIR_OVERLAY. An HOWTO should explain at least the minimum required to work. PORTDIR_OVERLAY seems to be part of that minimum but isn't in the howto. In the 6th section ("Testing and deploying"), there should be a reference to PORTDIR_OVERLAY since one can't test without it. Without it, it's like having a "Linux-Kernel HOWTO" that doesn't talk at all of Lilo or Grub or the /boot partition. As for the portage manual, there isn't much about PORTDIR_OVERLAY in it. The "portage user guide" is slightly better but not by much.
OK, you're right... the information about how to test your own ebuilds isn't mentioned very cleary. I'm reopening this bug. You can indeed copy the ebuild in /usr/portage/<category>/<package>, but it's also not mentioned.
I've proposed a change to the Gentoo Linux Developers HOWTO; you can find it on http://cvs.gentoo.org/~swift/gentoo-howto.html (bottom, called "Storing your own ebuilds locally"). If accepted, I'll add it to the CVS.
Sounds good to me. However, can you put something in "4. The Portage scripts and utilities" in "Public scripts"? In there, it is explained how to use the ebuild program but if one try at that step, it will most likely fail because he would not know where to store the ebuild yet. I thing it would be good to put a note saying something like: your ebuild file must reside in portage tree, please refer to "6.Testing and deploying", paragraph "Storing your own ebuilds locally".
That document isn't a step-by-step guide. You should read it at least 10 times before you even want to think starting developing ebuilds :) There are lots of other "inconsistencies" that way in that documents. It's just not written to be a step-by-step guide, but more of a reference.
That's why I proposed to put a reference to section 6th instead of moving the section before the 4th ;) More seriously, I think it still useful to write that down. One may think, especially with the term "storage", that moving the ebuild to the overlay dir is used only once he has tested the ebuild and wants to keep it. But the reality is that he must move the file there in order to test it.
I'll mention that it's for testing too. I'm still against "pointing" to another section; the doc should remain a reference. If you already start testing an ebuild, and it fails, you're first reaction should be reading further. Well, actually that should teach you not reading the whole document :)
Well... How many programmer do you know who reads a full document before hacking around a simple test program? Have you read the full C/C++ reference book before writing your first "Hello World!" program? Personnaly I try to do little things while I read a document, it helps a lot for remembering. After that, a second pass can be useful to get the details. I would have prefered to have such a pointer when I did my first ebuild. Nor do I understand what's wrong with having pointers (a.k.a. reference) in a "reference" document. But well, you're the maintainer, the decision is yours.
Committed in CVS.
