Gentoo Forums
Gentoo Forums
Gentoo Forums
Quick Search: in
Howto configure portage.
View unanswered posts
View posts from last 24 hours

Reply to topic    Gentoo Forums Forum Index Documentation, Tips & Tricks
View previous topic :: View next topic  
Author Message

Joined: 23 Dec 2004
Posts: 790
Location: under a car or on top of a keyboard

PostPosted: Thu Mar 03, 2005 9:55 am    Post subject: Howto configure portage. Reply with quote

Portage is a wicked package manager once it's setup right on your box. It seems that many new gentooers don't have all the features straightened out. I am even unclear on a couple of features, not to mention the dozens of USE flags that aren't documented ANYWHERE central.

Before we get into portage, we need to know that portage uses ebuild to do the actual package installations (which is but a part of what portage does :)). Portage is, though at simplest, just a nice wrapper for ebuild that does dependency calculations, etc.

Here's how portage works: When you emerge sync, a bunch of directories are created in /usr/portage which are package categories. For each package portage supports, a sub directory is created which contains an ebuild for each version supported by portage, the common files they all will use (init scripts and such) in a subdirectory called files, a changelog, and a metadata.xml file that includes information about the package, developer, and homepage.

After the actual sync is done, portage builds a database of these packages that contains information about use flags, and interdependencies. This database is queried when issueing the emerge command to determine the packages that will be involved with the emerge. Portage then calls ebuild to perform specific actions on packages, whether they need to be cleaned, upgraded, or an additional version of the same package installed in a slot. To get an idea of the package heirarchy on your system, try
emerge -tpve world

When installing packages with portage, sometimes you'll want to build a package that isn't in the portage tree or may not even have an ebuild. If the first is the case, what you'll want to do is create a portage overlay dir by adding a line to /etc/make.conf such as the following:
My portage overlay is in /usr/local/portage, which is usual. Placing ebuilds that are not in the standard portage tree in a portage overlay means that your portage tree can be synced regularly and automatically without worrying about packages no longer being in portage after a time (as they age). A recommendation for any box that you're planning on not upgrading for a time is to copy the ebuilds for EVERY PACKAGE on the system into the portage overlay. This will also allow the portage tree (/usr/portage) to be shared via NFS, samba, whatever without causing headaches for certain boxes with dated packages.

If you build a package from source that is not in portage or is in portage, but you wanted to build it from cvs or some such, you'll want to add it to /etc/portage/package.provided. This process is covered in the next section.

The main configuration for portage is in a few files in /etc. Most important of these is make.conf. Make.conf.example is thoroughly documented and I won't get into what all the settings do because that's what man is for.
***Exception: I'm going to mention the ROOT= option because it's not in the example and damn is it handy. If you have a system up and you want to install just a package to another system mounted at /mntpoint, set ROOT=/mntpoint and emerge the package. It will be emerged into the secondary system instead of your own! ***
I like to leave my make.conf alone once the system is installed. This has given me the best success over many, many installs on many boxes (notice more installs than boxes :)). Any properly installed system should be able to emerge -e world completely unattended and without intervention. I'll get into how to assure this in a bit.

Portage takes a number of things into account when you emerge a package and these are all defined in make.conf. First and foremost is USE flags. These are documented (well, some of them) in /usr/portage/profiles/use.{local.}desc. Portage has predecided that the USE flags in /etc/make.globals will be a good startingpoint. DON'T modify this file as it's uninteractively overwritten whenever you emerge sync. You can see what USE flags a package will take with
emerge -pv $package
Normally, you can get an idea of what a USE flag does for a package simply by it's name. If you are wanting to emerge a package and there are a bunch of dependencies it's trying to take with it, or the build fails unable to compile something that sounds like one of it's USE flags, try disabling the use flag and emerging again. Also, if you want to see what a packages bare dependencies are, try
USE="-*" emerge -pv $package
Please be aware, some of the 'dependencies' are only needed to build the package and can safely be unmerged afterwards without effecting the package's functionality. This must be determined on a case by case basis using trial and error until portage integrates such a feature. Generally, adding USE flags will mean a package is compiled against more and more libraries and consequentially, load time for the resulting binaries increases. Including minimal USE flags in make.conf, and in fact overriding the defaults will often give you a speedier system.

The second thing portage looks at when picking your packages is ARCH or ACCEPT_KEYWORDS. If you're installing binary packages, than you need to set ARCH. If you're installing from source only, you can get away with just setting ACCEPT_KEYWORDS. These are the stability keywords for the packages that will be accepted on your system (that's the only way I can make sense of the name). There are a couple of levels of 'stability' in portage. arch (x86, sparc, etc) means that a package has been tested very thoroughly and doesn't have any known bugs that will cause 'interesting' things to happen when you emerge it. To set portage to include these package, set ACCEPT_KEYWORDS=x86 and ARCH=x86 in make.conf for example, for the x86 architecture. The next level of stability is ~arch (~x86, ~sparc). This keywords is given to packages that may have unresolved dependency or compatibility issues, although there is nothing wrong with the packages themselves, there might be some issues because of the way portage deals with them. If you're reading this document, it probably isn't best to set this in make.conf as it will make gentoo a more trying experience. The 3rd level is -arch (-x86,-sparc). This keyword indicates that there is something wrong with a package and it is not recommended to install the package unless one familiarizes oneself with the shortcoming and understands it's implications. Examples would be a gaping security problem with default configuration, poor default configuration and little-to-no documentation, source tarballs that need specific conditions to build without error, or packages known to cause sudden data corruption of your disk and massive processor damage due to overheating. The reasons for a package being ~arch or -arch is most always listed on Please note that sometimes a package is ~arch simply because not enough people have tested it and it may, in fact, work perfectly.

###/etc/portage is your friend
By default, the critical settings in make.conf can be overwritten in /etc/portage, the portage configuration directory. These are package.use, package.keywords, package.mask, package.unmask and package.provided. By using a bashrc in /etc/portage like this one, one can also have package.cflags, package.cxxflags, and package.features. package.use contains an entry on each line of the form
cate-gory/pack-age enabled use flags -disabled -use -flags in any order
One should be constantly checking the USE variables of the packages on your system with emerge -pv to make sure these settings are optimized. package.keywords contains an entry on each line of form:
cate-gory/pack-age ~arch -arch ~* -etc
entries like ~* would scare me in real life, but they are accepted by portage. package.mask and package.unmask are both syntaxed identically and are used to prevent portage from merging packages older or newer than a certain version number. This is incredibly useful for emerging packages in your overlay that aren't in portage yet. The form of these files is:
>=cate-gory/pack-age-3.2.1-r27 #all pack-age greater or equal to 3.2.1-r27
Valid symbols are >, >=, =, =<, <, =!, which should be self explanatory. package.provided is a file used when you've built a package on your system that is not in portage or you've built it outside portage. This will tell portage the file exists on your system for the purpose of calculating dependencies, etc. Say I build kdrive from the freedesktop cvs and I want to emerge fluxbox. I would put the following in package.provided to prevent portage from emergeing Xorg with I emerge fluxbox:

###Special Considerations
Special consideration should be given when updating: glibc, linux{,26}-headers, gcc, libstdc++-v3, python, or glib.
If any of those packages are updated, the administrator should promtly do a
emerge glibc gcc libstdc++-v3 glibc gcc libstdc++-v3 && emerge -e system && emerge -e system && emerge -e world && emerge -e world
The duplicate emerge -e system and world are intentional and not per-se necessary, but for the paranoid and the hyper-cautious, are important steps to make sure your entire system is installed against the current resident libraries. Failure to do this may cause problems down the line.

Special consideration should also be given when updating another part of system (emerge -e system to find out what your system packages are as it varies with USE). The administrator should
emerge -e world && emerge -e world
. These processes can be done transparently in the background by setting a high PORTAGE_NICENESS in make.conf. I like to set the niceness around 10 as when I'm building the system, there's nothing else going on anyways, and when I'm upgrading something, the users shouldn't notice this.

###How to make sure you can emerge -e world without messing around:
1) Make your make.conf as simple as possible and reduce the number of USE flags asserted by make.profile. Put packages and USE flags in package.use.
2) Don't put ~x86 in make.conf. Put those packages in package.keywords on a case by case basis as you need them.
3) Don't put fancy CFLAGS in make.conf.[/url] Most importantly, because a lot of CFLAGS work well for some packages and slow down or break others.
4) put userpriv usersandbox sandbox in FEATURES in make.conf and disable them in package.features for the packages that break with those settings. This is a better policy in general than disabling them altogether and prevents the breakage during emerge -e $package.
5) Reitteration of the above 4: Only put gross generalizations in make.conf. Hammer down the particulars in /etc/portage. You can grep -R "package" /etc/portage and get an immediate view of what settings are enabled for the package. You can cp -a /etc/portage and /var/lib/portage/world to another installation and emerge -e world to generate an exact duplicate of the donor system. You won't have to fiddle with make.conf ever again. Your system will be faster overall because things aren't being linked that don't need to be. If you should have to change make.conf at any point during your gentoo experience, I recommend doing an emerge -e world to make sure everything still compiles cleanly.
6) This is more of a tweaker's tip than anything else: instead of using -O2 or -O3 in CFLAGS, use the equivilent string from the gcc man page, ie: -O2 is equal to "-fforce-mem -foptimize-sibling-calls -fstrength-reduce -fcse-follow-jumps -fcse-skip-blocks -frerun-cse-after-loop -frerun-loop-opt -fgcse -fgcse-lm -fgcse-sm -fgcse-las -fdelete-null-pointer-checks -fexpensive-optimizations -fregmove -fschedule-insns -fschedule-insns2 -fsched-interblock -fsched-spec -fcaller-saves -fpeephole2 -freorder-blocks -freorder-functions -fstrict-aliasing -funit-at-a-time -falign-functions -falign-jumps -falign-loops -falign-labels -fcrossjumping" The reasoning for this is that a LOT of ebuilds strip "-O#" from your CFLAGS and replace it with -O1. They normally won't replace the equivilent in individual flags, though, unless it's simply stripping ALL your CFLAGS like mplayer does, for example.

ToDo: tricks with gentoolkit, suggestions?
Back to top
View user's profile Send private message

Joined: 10 Apr 2004
Posts: 824
Location: Texas

PostPosted: Thu Mar 03, 2005 2:47 pm    Post subject: Reply with quote

nice howto. i think i'm going to write a howto that describes a rationale for using portage (rather than listing commands and what they do like most howtos). i think it would go hand in hand with this howto.


1) i like your section on /etc/portage/, but maybe you could give a summary sentence describing what each file in that directory is for.

2) you might want to do some research on emerge -e. i don't think it's necessary to have a stable system unless you use an unstable gcc. i don't do it on my systems and they are completely stable. here's my thread on it:
and further down in this one:
Back to top
View user's profile Send private message
Display posts from previous:   
Reply to topic    Gentoo Forums Forum Index Documentation, Tips & Tricks All times are GMT
Page 1 of 1

Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum