What is Portage and how to use it

Gentoo Gnu/Linux is a notoriously hard-to-install minimal Linux distribution. Like many Gnu/Linux distributions it has a package manager and repositories that hold software that can be installed onto a system. Gentoo, unlike other distributions, uses a repository of source code as its primary method of installing software (similar to the FreeBSD source trees). Compiling the source code of your programs provides a few benefits, including a performance gain and source-level customization. Here is how Portage works:


Setting up portage
emerge is the Portage's interface. You may see on online guides emerge X (emerge [anything]) and get the "package not found" message. This is because portage does not have the repositories synced by default. To sync the repository, run emerge --sync. This will take some time (it took about 20 minutes at 138 KiB/second). This gets a file with the names of the packages, their categories, and a bit more information. You will see a list of all of the applications available to you fly down your screen. It was moving at such a steady speed that I was unsure of whether or not it was downloading a file, but when I disabled my wireless connection it was indeed relying on the internet for this step.


General Portage Usage
You can now install software with emerge name, where name is the name of the package that you want to install. If you are searching for a package in the repositories, you can use emerge --search query or emerge --searchdesc query to search through the documentation as well.


What to expect when emerging
When you emerge a file, Portage will hide nothing from you. It outputs all the steps, including logging into an FTP server. If it seems to stop working, use the command tail -f /var/log/emerge-fetch.log  in another terminal window. This will repeatedly output the next line in emerge-fetch.log, which is where fetching progress is stored.


After the program has been fetched, it will run through a list of conditions required to install the program. You will see "Checking blah for blah blah" repeated a lot of times, and then it will install the program. Yes, source compilers, it goes through the makefile.


Keeping Portage up-to-date
Always remember to do an emerge --sync every two days or so to keep your repositories up-to-date. When a new version of Portage comes out, emerge portage will install it. To update your system, the command emerge --update --deep --with-bdeps=y --newuse world will update everything on your system, including USE flags and build dependencies. 


Removing Software with Portage
We all have those bad days where we install a rotten package, or it just conflicts with something else on the system. To uninstall it, use emerge --unmerge X where X is the software to remove.


USE flags

Use flags are an important part of the Portage environment. USE flags tell Portage what your tastes are in certain kinds of packages. For instance, if you were to download a flight simulator WITHOUT a "3d" use-flag, it wouldn't download 3d support. If you had "3d" as a use-flag, it would download it if the package recommended it. /etc/portage/make.conf is where your USE flags are stored. You define it like this:

USE="-X -aqua -dvd gnome"

A list of USE flags is stored here: http://www.gentoo.org/dyn/use-index.xml

Extra documentation on USE flags can be found here: http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=2

General Portage usage
Two other useful tricks are emerge --fetchonly X and emerge --pretend X. The first one will only download the software and cache it; it will not install. The second command will not download anything, but it will calculate the dependencies and tell you how much space you need to install it with. Along the same lines of --pretend, --ask will make sure that the user wants to download the software after they see the size.


Test it out
Here are the commands necessary to emerge firefox (yes, it is really this easy):

A Warning to the Impatient

Compilation takes a very long time for large programs like Firefox or qtcreator. It can take hours on a new machine, and the older a processor is the worse it will do. Gentoo is not for you if you cannot wait a few hours for a large piece of software to install. I figure that it is unlikely you sat around for Gentoo to compile if this was the case, but be warned.