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 :
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.
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
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.
Use the official handbook https://wiki.gentoo.org/wiki/Handbook:Main_Page
The following are hints to be used with the handbook.
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.
When decided to use efi, use a live CD that supports booting from efi (as the gentoo minimal installation CD) and make sure it has booted from efi.
To be very sure that the efi installation will successful test it further as:
Load the driver modprobe efivars
Check if there is a efi directory ls /sys/firmware/efi/
Use efibootmgr (if not available on the live DVD just do emerge efibootmgr.
Partitioning the disk for gtp and efi can be simple using 2 partitions as:
Number Start End Size File system Name Flags
1 1049kB 134MB 133MB fat32 boot boot, esp
2 134MB 120GB 120GB ext4 rootfs
No mysterious partitions are required. Starting the first partition from 0 might not be possible.
Partitioning a disk with mbr can also be simple
Device Boot Start End Sectors Size Id Type
/dev/sda1 * 2048 264191 262144 128M 83 Linux
/dev/sda2 264191 <rest of it>
<rest of it>
83 Linux
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.
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.
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.
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
.
emerge --noreplace <ebuild>
add an already emerged ebuild to the world file.
Emerge something as portato to search for ebuilds in the portage and when installed, where the files are (executables, documentations, ... .)
To have a clean installation, watch out what is in
/var/lib/portage/world
there should be just packages listed that got installed manually and intended. All packages should be known.
For the unknown a gui portage tool or the internet can help to find out about them. If it is still unknown why they got emerged manually wipe them off the world file (do not --unmerge them since they are probably be used as dependencies for other packages).
Failures and troubles during updating gentoo ask to retry and 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 those
options are not used, then the world file collects all trouble packages and it gets difficult to get rid of them in the future. Cleaning means --unmerge or deleting them manually in the world file.
A lost world file can be recovered using 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 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 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.
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.
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 |
Compiles and installs new package, use this just for packages that you have selected. |
emerge –1 |
Compiles and installs a package, but does not add it to
|
emerge “< |
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 |
Looks for packets containing name |
emerge --searchdesc |
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 |
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 |
Installs prebuild packet (when available, when not build from source code) |
emerge --usepkgonly |
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 |
Pretend installing a package, be verbose and show the (empty)tree to see all dependencies |
emerge -K |
Short form of --usepkgonly |
emerge -k |
Short form of --usepkg |
emerge -pv |
Pretend installing a package and be verbose |
emerge -pvt |
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.
EMERGE_DEFAULT_OPTS="--jobs=<n>
--load-average=<m>
can be added to adjust how many jobs in parallel and how much load is used for the compilations.
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. emerge can do it: emerge --autounmask-write<ebuild>
and then run etc-update.
To not use a specific version that caused troubles, create the file
/etc/portage/package.mask
. To mask the default files add
lines as:
=sys-apps/busybox-1.00-r4 =sys-libs/glibc-2.3.5 =net-misc/unison-2.12.0
Since this way of masking packages is done by the system administrator it is called soft masking.
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_SYSTEM="save" 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 or emerge elogv for text based to have a list of all them to look and delete them individually.
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
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.
With portage 2.2 a new feature is introduced. Multiple ebuilds can be emerged with a single command: emerge -av @kde
Gui tools as kuroo 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
or for newer installation /var/cache/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 directory can be found in the /etc/portage.make.conf file
PORTDIR="/var/db/repos/gentoo"
or on older systems /usr/portage
. There are also other directories inside that contain no ebuilds as:
distfiles holds the source code downloaded from the Internet, newer installations have it in /var/cache/distfiles
eclass holds functions often be called by the ebuilds (as a library for ebuilds)
licenses holds what the name says
metadata holds a lot of different stuff as cache, dtd, glsa, news, timestamp
packages hold binary packages
profiles hold the profiles
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:
emerge --search<criteria>
Check out https://www.gentoo.org/
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 https://www.gentoo.org/ 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:
Instead of using a tool that disappear due to lack of maintenance try gpo.zugaina.org/
Nice tools got outdated: portato, himerge and porthole. Maybe in the future they will get maintainers to become reactivated.
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
).
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
See: https://www.gentoo.org/support/use-flags/
There are the following kinds of use flags and places where there are defined:
Global useflags
/usr/portage/profiles/use.desc
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.
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.
CURL_QUIC="openssl" can also be written and is used as by emerge as curl_quic_openssl
To find use flags:
cat /usr/portage/profiles/use.desc |grep lirc
cat /usr/portage/profiles/use.local.desc |grep lirc
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
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.
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
* 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.
License groups are defined in /usr/portage/profiles/license_groups
Licenses are controlled by the ACCEPT_LICENSE variable in /etc/portage/make.conf
ACCEPT_LICENSE="* -@EULA"
* the wild-card means all known licenses
- means minus
@ means that the following is a name of a group of licenses and not a single license
All together mean all known licenses are automatically accepted except the licenses the require a End User License Agreement
Licenses can also be accepted by per-package basis in /etc/portage/package.license
If the license is not accepted messages pop up as:
!!! All ebuilds that could satisfy "app-emulation/virtualbox-bin" have been masked. !!! One of the following masked packages is required to complete your request: - app-emulation/virtualbox-bin-3.1.2 (masked by: PUEL license(s)) A copy of the "PUEL" license is located at "/usr/portage/licenses/PUEL".
Then it is due to the lawyers out there. Especially sun Microsystems and now Oracle that owns them tries to give you a hard time. Maybe worth to use an other java implementation as Alternatives are switching to dev-java/icedtea-bin:6 or the source-based dev-java/icedtea:6?
To accept the license put something as
ACCEPT_LICENSE="${ACCEPT_LICENSE} PUEL"
into /etc/portage/make.conf
.
Or add it to the license file /etc/portage/package.license
>=dev-java/sun-jdk-1.6.0.29-r1 Oracle-BCLA-JavaSE
Example 14.1. License blockage example
!!! The following updates are masked by LICENSE changes: - www-plugins/adobe-flash-11.2.202.262::gentoo (masked by: AdobeFlash-11.x license(s)) A copy of the 'AdobeFlash-11.x' license is located at '/usr/portage/licenses/AdobeFlash-11.x'. For more information, see the MASKED PACKAGES section in the emerge man page or refer to the Gentoo Handbook.
Does not give a useful hint what to do. To solve it add the following:
>=www-plugins/adobe-flash-11.2.202.262 AdobeFlash-11.x
to:
/etc/portage/package.license