Importing ebuilds in Gentoo Prefix

Jeremy Olexa Author

Updated August 1, 2009

1. Importing ebuilds with ecopy

Ebuilds for Gentoo Prefix need some minor modifications from those that exist in the "regular" Gentoo tree (known as the gentoo-x86 tree). Spelling out those modifications is out of scope for this document, feel free to browse here: http://www.gentoo.org/proj/en/gentoo-alt/prefix/techdocs.xml

The ecopy script

ecopy is a script created by the Gentoo Prefix team, and located in ${EPREFIX}/usr/portage/scripts. Its intention is to save people time and is mainly a wrapper for other scripts which will be discussed later. Its usage can be described by running: ecopy (without options).

ecopy expects the following:

Expects to be ran from the root of your overlay If you do not know about overlays then please see: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=1#doc_chap6.
Expects to have one and only one valid category and package as an argument. It should be in the form of "/" ie. app-office/openoffice.
Expects an up-to-date Prefix tree to reliably have the latest scripts.

The use of ecopy is best explained by a simple example.

Code Listing 1.1: ecopy example

% cd "${EPREFIX}"/usr/local/portage/my-overlay
% ecopy app-office/openoffice
openoffice-3.1.0-r1.ebuild
2009-08-01 18:41:23 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/ChangeLog [98520/98520] -> "ChangeLog" [1]
2009-08-01 18:41:23 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/metadata.xml [704/704] -> "metadata.xml" [1]
2009-08-01 18:41:24 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/Manifest [17937/17937] -> "Manifest" [1]
2009-08-01 18:41:24 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/openoffice-3.1.0-r1.ebuild [13564/13564] -> "openoffice-3.1.0-r1.ebuild" [1]
2009-08-01 18:41:25 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/files/gentoo-3.1.0.diff [173/173] -> "files/gentoo-3.1.0.diff" [1]
2009-08-01 18:41:25 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/files/ooo-env_log.diff [617/617] -> "files/ooo-env_log.diff" [1]
2009-08-01 18:41:25 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/files/base64.diff [770/770] -> "files/base64.diff" [1]
2009-08-01 18:41:25 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/files/buildfix-gcc44.diff [611/611] -> "files/buildfix-gcc44.diff" [1]
2009-08-01 18:41:25 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/files/solenv.workaround-for-the-kde-mess.diff [17556/17556] -> "files/solenv.workaround-for-the-kde-mess.diff" [1]
2009-08-01 18:41:26 URL:http://tinderbox.dev.gentoo.org/portage/app-office/openoffice/files/xulrunner-1.9.1.diff [325/325] -> "files/xulrunner-1.9.1.diff" [1]
Processing openoffice-3.1.0-r1.ebuild
  replacing ${D} -> ${ED} ... 2 occurences
  replacing ${ROOT} -> ${EROOT} ... not found
Processing openoffice-3.1.0-r1.ebuild ... ~amd64-linux ~x86-linux
openoffice-3.1.0-r1.ebuild
>>> Creating Manifest for usr/local/portage/my-overlay/app-office/openoffice
<snip for brevity>

What is ecopy doing? In that above code snippet, ecopy first directly downloads the required files from tinderbox.dev.gentoo.org. Then, ecopy runs eapify on the ebuild. eapify basically does the needed gentoo-x86 -> Prefix conversion. This can generally be automated and works right the first time about 85% of the time. After eapify, some keyword cleanup is done by ecleankw to make it match the Prefix keywords. The Prefix keywords are more strictly defined than those of the gentoo-x86 tree. For more information on that see GLEP 53. Last, ecopy re-digests the ebuild to accommodate any changes. Let it be known that you can do all this manually as well because ecopy is just a wrapper script in itself.

While eapfiy (the tool that does the actual transformation of the ebuild) succeeds doing its job in many cases, it cannot be trusted to always do the right thing. Common mistakes made by eapify are related to either adding or omission of the ${EPREFIX} for some component in the ebuild. eapify doesn't catch all instances of what needs to be changed. If there is e.g. any path hardcoded in the configure call you will need to prepend ${EPREFIX} to it. Also, ${D} can be improperly expanded to ${ED} in certain cases. Manual review is always necessary. For more details on these issues see the Ebuild modifications chapter of the Gentoo Prefix Techdocs page.

2. Bug Reporting

Great, your package works...now what? The Gentoo Prefix team relies on users submitting bug reports stating if a new package works. We simply do not have the man power to get to our goal of having most of the packages in the Prefix tree without your help.

When submitting bug reports, please follow these guidelines:

Use the "Gentoo/Alt" Product with the "Prefix Support" component.
Include the method of your porting efforts. Did you use ecopy, manually, etc.
Include which changes you made *after* ecopy, preferably using a diff -u
Include which patches you added, preferably attached uncompressed, not bundled with anything else.
Include emerge --info, or at least what ARCH you are on. Otherwise, we will commit the package and have to re-visit it to add your arch.
Do not submit reports about ecopy not porting your package correctly, it is a best effort script only! Manual work probably is needed.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.