Gentoo fundamentals

Gentoo is (per default) always compiling the source. It would be possible to install rpm's or deb's, but this is highly not recommended on a Gentoo system, since it is highly probable that this would cause a conflict with the Gentoo package management database.

To allow automatic compilation and installation Gentoo has introduced ebuilds, that contain all necessary tasks to make those steps. Ebuilds can be considered as packages, but instead of having the actual binaries and data inside, they hold the information where to retrieve the source and how to create a binary. However some ebuilds install also binary packages and others even debian deb packages. Gentoo is flexible for that however many Gentoo developers are not.

The program emerge is used to install packages. emerge<ebuildname> installs packets. emerge umerge<ebuild> removes the packet. This way dependencies are resolved and the updates will work.


On of the fundamental concepts of Gentoo is that the packages are not directly installed into the system. They are first installed in a temporary location and then copied (merged) file by file to the real system. This way Gentoo remembers all the files installed (merged, copied) and knows what to remove when the package gets updated or removed.

All ebuilds are in the in the portage. If an ebuild does not exist it is better to write yourself an ebuild and put it in a portage overlay (your own portage) than use an other method and run into a conflict with different packet managers.

The ebuilds can be grouped in three categories :

  1. The system ebuilds, emerge -p system shows them. The selected profile in /usr/portage/profiles defines them, but the profile uses a cascading directory and file structure, therefore it is not as easy as opening a file and look at the system ebuilds.

  2. The ebuilds you installed manually that are listed in /var/lib/portage/world and cat /var/lib/portage/world shows them or emerge -p world shows them plus the system ebuilds

  3. Ebuilds that depend on the above and got installed automatically. To see everything installed: system, world and depending ebuilds do equery list "*" or cd /var/db/pkg/ && ls -dl */* or emerge -pe world. The numbers of ebuild listed should be consistent otherwise something is corrupt in /var/db/pkg

To get an overview emerge --depclean --pretend.

Gentoo uses the term sets emerge --list-sets to group ebuilds. To differentiate that a set is meant the @ character has to be put in front of the set name.

Installing Gentoo

Download a gentoo live DVD (64bit for 64bit systems or 32bit for 32bit systems). Set the key board layout at boot and then open the gentoo handbook and copy and paste the commands from the handbook into the console. To be root do sudo su in the console window.


With efi and gtp questions arise how to partition the disk and how to boot. If so changing the sequence and installing the boot loader and testing boot can be performed before the gentoo system gets installed. With efi lots of options exist as not use a boot loader at all, use grub or an other installer, have other efi apps installed, use the old fashion MBR boot process.

Consider to have swap and have it activated. This might be necessary just during installation since the RAM must share both the life filesystem and the the RAM required to run the applications. The swap can also be a swapfile that simply can be deleted after the installation is done (swap partitions can not be deleted so easily).

Some rules when working with Gentoo Linux

This section is here to remind about the few things when working with Gentoo Linux without going into the details. The reason why it is here at the beginning, is to prevent that you make a mess in your installation. If you read this book the first time and you understand none of the commands, just skip it.

  1. It is recommended to call emerge -pv before emerging a ebuild. The useflags that the package supports are shown: The ones enabled and the ones disabled. Check what they mean by e.g. ufed and modify them as appropriate.

  2. For the ebuilds that depend on the ones you know or the ones that make troubles use emerge -1 <ebuild> or emerge --oneshot <ebuild> this prevents that garbage gets registered in /var/lib/portage/world.

  3. Emerge something as portato to search for ebuilds in the portage and when installed, where the files are (executables, documentations, ... .)

The world file

To have a clean installation, watch out what is in /var/lib/portage/world there should be just files there that you installed intentionally and manually and that you should know all of them. For the ones you do not know use a gui portage tool (as porthole) to find out about them and if you still do not remember that you have emerged them, consider to wipe them off the world file (do not unmerge them since they are probably be used as dependencies for other packages).

It happens that packages depending on the ones you like to install fail during updates and you like to re-emerge such packages manually. It is highly recommended to use the --oneshot or-l option in the emerge command, so they will not be registered in the /var/lib/portage/world file. If you don't use these options, then the world file collects all trouble packages and you will not get rid of them in the future. Except you unmerge them or delete them manually in the world file.

If you loose this file you can recover some of it, emerge gentoolkit and run regenworld (it is a python script that does nothing else than trying to restore data from /var/log/emerge.log ) to restore.

The contents of the world file can be made visible in the console using emerge -pv world or cat /var/lib/portage/world or open it in an editor.

To verify that the world does not contain packages that depend on other emerged packages or if your world file has a couple of hundred packages, then unmask and emerge udept and run dep -wvp. If you are sure that you want to clean it run dep -w. However when later on deleting a front end the back-end is no longer registered in the world file and could be wiped off when running emerge --depclean. Therefore run previously emerge --depclean --pretend. Type dep -h to get the full list of options for the powerful dep command.

System packages

Those ebuilds are defined in the profile. Since profiles are cascading there is no single file to see those ebuilds. The list of basic ebuilds is /usr/portage/profiles/base/packages . To see the complete list type emerge -pv system.

Note the /var/lib/portage/world contains no system files, except you have emerged them manually.

The package data base

Everything that is installed can be found in /var/db/pkg . Those directories contain lot of information relevant during the installation and information about the packages themselves. Portage tools (as porthole) read this database and show the content in a user friendly GUI.


The magic Gentoo command is emerge.

emerge <packetname>

Compiles and installs new package, use this just for packages that you have selected.

emerge –1 <packetname>

Compiles and installs a package, but does not add it to /var/lib/portage/world use this when you run in to problems with packages that depend on the ones you like to be installed. --oneshot is the long version of the option

emerge “<<name>-1.2”

Installs earlier version (>newer, =exact)

Options with long parameter form:

emerge --depclean

Remove not used packages

emerge --help

Help about emerge

emerge --help config

Help about config files

emerge --info

Shows configuration of your system libraries use flags and many more

emerge --pretend --update world

Checks what is up to do

emerge --search <name>

Looks for packets containing name

emerge --searchdesc <name>

Looks for packets and description containing name

emerge --sync

Updates the portage tree on the computer to see what new packages are available. Net etiquette do not more than once a day

emerge --unmerge <packetname>

De-installs packets

emerge --update --deep --newuse world

When you have added new use flags and want to update all

emerge --update --deep world

Does the update including dependencies

emerge --update system

Updates just the system not the packages

emerge --update world

Does the update

emerge --usepkg <name>

Installs prebuild packet (when available, when not build from source code)

emerge --usepkgonly <name>

Installs prebuild packet

Options with short parameter form:

emerge -e system

To recompile all with e.g. new compiler version

emerge -e world

To recompile all with e.g. new compiler version

emerge -epv <name>

Pretend installing a package, be verbose and show the (empty)tree to see all dependencies

emerge -K <name>

Short form of --usepkgonly

emerge -k <name>

Short form of --usepkg

emerge -pv<name>

Pretend installing a package and be verbose

emerge -pvt <name>

Pretend installing a package, be verbose and use tree formatting

emerge -u world

Short form of update

emerge -u world

Updates all packets to last version

Usually emerge takes the newest stable package (e.g. x86 keyword). However this default behavior can be changed. There are different options.

Unfortunately the same verb mask is used for two different things and creates therefore confusion. To avoid that the term hard mask has been introduced. Packages can be hard masked by the Gentoo developers. You as system administrator can just (soft) mask them. On the other side you as system administrator can unmask hard masked packages and unmask unstable packages (packages under test). In the worst case a package is masked and unstable. To use it you must hard unmask it and (soft) unmask it.

The emerge command shows information (man emerge for a complete description) about what it is doing with the package:

N new package to be installed

U update already installed package

D Downgrade package

S Slotted package

R Reemerging with same version

f fetch restricted (e.g. due to license) but already downloaded

~ unstable package

Slotted packages are packages where different versions can be installed at the same time.

Using emerge --update world does not necessary update everything as emerge -pe world shows. Files depending on the ones listed in /var/lib/portage/world might not be updated. Such file scan manually be updated using emerge -u<ebuild> but such updates usually have no noticeable effect.

Use a unstable package

To use a unstable package that is under test instead of the stable one, use the following command to appended a line to /etc/portage/package.keywords

echo "<=sci-electronics/eagle-4.16_p2-r2 ~x86" >> /etc/portage/package.keywords


A package.accept_kewords file has been introduced that will replace the package.keywords file. Or even worse /etc/portage/package.keywords became a directory on new systems and is no more a file, since the /etc/portage/package.keywords got too long. To convert the file to a directory, rename the file and move it to /etc/portage/package.keywords/package.keywords.file .

To enable just to the current version, it is wise to do it as show above. Therefore in the future the line gets obsolete when newer stable versions are in portage and therefore the line can be wiped out.

Alternatively to the echo command the file /etc/portage/package.keywords can be edited:

        <=x11-drivers/ati-drivers-8.26.18-r1 ~x86

An unstable package could require to unmask very many additional unstable packages. There was the program autounmask to do this job, but now also emerge can do it: emerge --autounmask-write<ebuild> and then run etc-update.

Do not use the default package

To not use a specific version that caused troubles, create the file

/etc/portage/package.mask . To mask the default files add lines as:


Since this way of masking packages is done by the system administrator it is called soft masking.

Use masked packages

Masked packages are different from unstable packages. Masked packages are known to have troubles, this is why they got masked by the Gentoo developers. Since this way of masking packages is done by the Gentoo developers it is called hard masking. Masked packages and the reasons why they got masked can be found in /usr/portage/profiles/package.mask .

Note that overlays can also mask packages. Therefore look to directories as:

/usr/locale/portage/layman/<name of overlay>/profiles/package.mask

It is therefore recommend to read those files before unmasking masked packages.

To unmask a package that got masked by the Gentoo developers edit the file /etc/portage/package.unmask and since it is probably unstable you need to unmask it in /etc/portage/package.keywords as well => double unmasking.



This is an important note, since read and setup storing elogs is a must. Unfortunately the Gentoo manuals do not enough point out this important steps. If not, then the system will get sooner or later errors and requires troubleshooting.

During emerge a lot of information appears on the screen and can obviously not be read. Some of this information is vital to the Gentoo installation.

The logs can be read inside the directory /var/log/portage/elog .

Usually just the file summary.log is found in this directory, but adding the following in /etc/portage/make.conf causes individual files being created:

PORTAGE_ELOG_CLASSES="warn info error log"

On the console, those files can be viewed directly. More user friendly is to use mc and have in on window the quick view.

For a gui emerge elogviewer to have a list of all them to look and delete them individually.

Virtual packages

There are also virtual packages. Virtual packages allow the use of different implementations for the same purpose. As example there are different implementations of java. A program written in java requires java being installed but does not require a specific java implementation. The dependency to the virtual java package resolves this issue and allows to choose different java implementations.

The virtual java package depends on at least one out of the java package. emerge virtual/jdk will get the default java vm

Slotted packages

Gentoo allows that different versions of the same packages can be installed at the same time. This is necessary when a package gets a major release with incompatibilities and other packages still depend on the older version. To those packages a slot number is assigned.

Package sets

With portage 2.2 a new feature is introduced. Multiple ebuilds can be emerged with a single command: emerge -av @kde

Finding what has been installed

Gui tools as porthole show you easily what has been installed. However if the list is to big, then the command line tool equery files<packagename> in combination with grep can be used. If the package documentation speaks about some files that can not be found, then the files might be still on the computer but not installed. Go to /usr/portage/distfiles and browse through the zipped package.


Portage is a list of packets (programs, ebuilds) maintained by Gentoo that can be installed and managed on your computer. The portage is /usr/portage . There are also other directories inside that contain no ebuilds as:

  1. distfiles holds the source code downloaded from the internet

  2. eclass holds functions often be called by the ebuilds (as a library for ebuilds)

  3. licenses holds what the name says

  4. metadata holds a lot of different stuff as cache, dtd, glsa, news, timestamp

  5. packages hold binary packages

  6. profiles hold the profiles

  7. scripts holds what the name says

The official portage can be expanded by overlays. Overlays are collections of non-official ebuilds.

Settings can be done in /etc/make.conf .

The FEATURE variable has direct influence on how portage behaves. The following line in /etc/make.conf

      FEATURES=”noman noinfo nodoc”

prevents that documentation is installed. However saving 100MB less compared to the rest is not worth losing the documentation.

The program emerge is used to deal with the portage.

To find what is in portage the following can be done:

  1. emerge --search<criteria>

  2. Check out

  3. use a portage GUI front end as porthole, himerge, kuroo, ... .

As time goes by, everything can be improved, but it can also become worse. A replacement of portage with promised improvements is in preparation, lets see what the future brings.

Once the web site contained a lot to browse and search throughout portage, but it disappeared due to a security issue. So a GUI front ends for portage is helpful:

Portage tools

Obsolete portage tools

Nice tools got outdated: portato, himerge, kuroo. Maybe in the future they will get maintainers to become reactivated.


Easy, stable and well maintained GTK front end

Use flags

If a package is installed, Gentoo downloads the source code and compiles it. You can influence what and how it is compiled and what is added. You might want to add or remove certain functionalities and support for other stuff (as adding IP6 support). This is archived by the use flags. Considering those use flags, the ebuilds add or skip certain items. Use flags are defined (enabled or considered) in the ebuilds or eclasses (see /usr/portage/eclass ).

Available useflags

To know what use flags are available for a package and their status type: emerge -pv<ebuild>

To see for what a useflag (e.g. useflag ldap) is used by a package, emerge euses and type

euses ldap.or use equery hasuse ldap found in gentoolkit


There are the following kinds of use flags and places where there are defined:

  1. Global useflags /usr/portage/profiles/use.desc

  2. Local use flags for specific packages /usr/portage/profiles/use.local.desc

    (This file is deprecated as per GLEP 56 in favor of metadata.xml)


    Some useflag names are ambiguous since they exist as global as well as local use flag as mtp.

  3. Expanded use flags /usr/portage/profiles/base/make.defaults (See USE_EXPAND: VIDEO_CARDS, LIRC_DEVICES, LINGUAS, ...) . Regular use flags have just two conditions set or not set. The expanded use flags are a list of items.

To find use flags:

cat /usr/portage/profiles/use.desc |grep lirc

cat /usr/portage/profiles/use.local.desc |grep lirc

Activate and deactivate use flags

Useflags should just be set when necessary. As example the profile for desktop computers /usr/portage/profiles/targets/desktop/make.defaults hold the X useflag, so there is no need to set it again manually. emerge -pv<ebuild> shows what the default settings do. Also activating useflags that are not used does not make sense.

emerge ufed the use flag editor to change use flag settings. If no package is shown, it is a global use flag, if a package is shown it is a local useflag

emerge profuse to get a graphical tool.

Once the default where in a single file /etc/make.profile/make.defaults but in newer versions /etc/make.profile is a link to cascading profiles as /usr/portage/profiles/default/linux/x86/10.0/desktop.

Useflags can be set global, so they apply for every package emerged or they can be set just for a single package.


When setting useflags globally side effects might happen as troubles with other packages. Setting them package based is therefore less problematic.

Global useflags should be set Global useflags are set in /etc/portage/make.conf . If a – is put in front then it is disabled.

Package specific use flags can be set to /etc/portage/package.use as

media-tv/xmltv de_tvtoday

Or cleared to avoid that a certain package uses a useflag that has been globally set

        dev-java/blackdown-jdk -doc

This example emerged blackdown java without the documentation that gets loaded from Sun Microsystems thats very often causes problems.

Working with use flags

It is wise to do first an emerge -pv that means pretend verbose. Nothing happen but you see what use flags are there and if they are set or not set.

Sometime some programs rely on other programs and how they got complied (their use flag settings), this can give some problems and error messages during the emerge. To get rid, you have to find the program an recompile (reemerging) with the appropriate use flag setting. Or do a radical step by:

emerge --update --deep --newuse world

emerge --p --depclean

Then if nothing dangerous shows up do

emerge --depclean

emerge @preserved-rebuild

To see whats up with the use flags set or clear one useflag and check its impact with

emerge --update --deep --pretend world

Or to see all of them being used:

emerge -evp system

emerge -evp world

Or for a package

emerge<package> -pv

- are use flags not set

red are active use flags

blue are inactive use flag

% after the use flag shows that an update of a package has introduced this new use flag

  1. * after the use flag shows that use flag status does not match with what has been installed.

    yellow are use flags that will be added by new emerges

    green are use flags that have been used previously for the package


Gentoo has the tool eselect to do semi automatic configuration task as selecting the desired version of different packages (kernel sources, Gcc, OpenGl, …. ).

It is also used to pass news to gentoo users that usually act as system administrators.

eselect news list will list the news and eselect news read new will show the news.

Linurs Servernest startpage