Emerge: custom builds

This is a wiki page. Be bold and improve it!

If you have any questions about the content on this page, don't hesitate to open a new ticket and we'll do our best to assist you.


Being a source-based distribution, Gentoo is the perfect platform for developing and hacking software. You can easily install any third-party software, hack the code and have a custom build installed on your machine, which is useful for testing patches before submitting changes upstream.

There are many ways to customize the builds of some software. The optimal solution will depend on the use case: the software itself (its size, dependencies and complexity), whether you want to add a one off patch or you plan to hack it regularly, etc.

The first main goal is to keep portage aware of your build, so that it can manage your files. It also means avoid installing stuff under /usr/local/. Sometimes a custom .ebuild file is the best solution, but not necessarily so.

The second goal is to optimize the compile time, especially if you are going to regularly hack the software and will test a succession of many small changes. For builds using cmake, only the modified files need to be recompiled.


Custom patches

You can keep custom patches under /etc/portage/patches/.
This solution is very easy to implement and is especially suited when you only want to keep one or two patches for a specific software.

Regular hacking

See man make.conf and
Set up a custom environment for the package you want to build:
In this case we want to have:

FEATURES="keepwork noclean"

Let's say you want to hack kde-apps/kmail.
If you emerge kmail with the above FEATURES set, you'd be left with the emerge working directory somewhere at /var/tmp/portage/kde-apps/kmail-4.14/work
which would include two sub-directories:

# ls -1 /var/tmp/portage/kde-apps/kmail-4.14/work/

Alternatively, instead of completely emerging the package as described above, you can use ebuild to simply prepare the source:

ebuild  /usr/portage/kde-apps/kmail/kmail-4.14.ebuild prepare

You can hack the code directly in the kmail-4.14, but the changes will not be kept.
In order to keep track of your changes and commit them to git, you may want to git clone the official repository, checkout the branch compatible with the installed version, then remove the code directory used by emerge, and symlink to your checkout.

# rm -fR /var/tmp/portage/kde-apps/kmail-4.14/work/kmail-4.14/
# ln -s /home/user/git/kmail/ /var/tmp/portage/kde-apps/kmail-4.14/work/kmail-4.14

Then, you can hack, test in a separate build directory, commit to git, and when you are ready, emerge again:

# ebuild  /usr/portage/kde-apps/kmail/kmail-4.14.ebuild merge

For finer control, check ebuild ... configure|compile|install. Check man ebuild for all the actions taken and the order they are taken.

See also

man make.conf

Gentoo-Fu: Optimizing the build process

Issues related to this page:

ProjectSummaryStatusPriorityCategoryLast updatedAssigned to
Web siteMerge two wiki pages on portage and software de…activenormaltask6 years 40 weeks