Gentoo Logo

The GPE Configuration Guide


1.  Introduction

The GPE Palmtop Environment

Figure 1.1: GPE on PDA.

Fig. 1: GPE Session on gentoo-embedded

From the GPE homepage: "The GPE Palmtop Environment (GPE) is a collection of integrated software components optimized for (but not limited to) handheld and other input constrained and resource limited devices. GPE provides PIM (calendaring, todo management, contact management and note taking), Multimedia (audio playback and image viewing) and connectivity solutions (web browsing). Another major goal of GPE is to encourage people to work on free software for mobile devices and to experiment with new technologies."

Note: The gpe environment available on the portage tree is currently incomplete and experimental.

This guide will show you how to install and configure GPE, so that you will end up with a working GPE login, session manager and desktop.

2.  Installing GPE

Unmasking GPE ebuilds

Note: At the time of writing, there isn't a GPE meta ebuild to pull in all gpe related packages.

GPE is being slowly tested and stabilized, so you might find some masked ebuilds:

Code Listing 2.1: Find masked ebuilds

(Replace ARCH by your running architecture.)
# cd /usr/portage/
# grep "~ARCH" -lr gpe-* $(find ./games-* -name "gpe-*") | \
  awk -F '/' '{ print "="$2"/"$3" ~ARCH" }' | \
  sed -e 's/\.ebuild//'

Next, grab the command output and write it to /etc/portage/package.keywords.

Installing a minimal GPE

To install a minimal GPE (login and session manager), you will need to emerge the following packages:

Code Listing 2.2: Emerging GPE

# emerge -avq gpe-base/gpe

This meta ebuild will install all available GPE packages currently available on the tree. Notice the available USE flags for additional software.

3.  Configuring GPE

Note: People on PDA should follow the gentoo-embedded handbook to create a proper init script for gpe-dm if /etc/init.d/xdm is not available for them.

Code Listing 3.1: /etc/conf.d/xdm


Now, you should instruct the session manager to start matchbox (GPE uses it for the panel and desktop). For that, edit etc/X11/Xsession.d/99xWindowManager this way:

Code Listing 3.2: /etc/X11/Xsession.d/99xWindowManager


# This will launch matchbox-panel, matchbox-desktop. ...
exec /usr/bin/matchbox-session

People (mostly) on PDA should also look at the following files to fine tune their platform:

  • /etc/X11/gpe-dm/Xserver People not using xorg-server will have to edit this file for instructing the display manager how to start the Xserver. The file is well commented with some examples.
  • /etc/X11/gpe-dm/Xinit.d/ You can put scripts in here that are to be executed before the login manager.
  • /etc/X11/gpe-login.setup This script is executed during the gpe login manager initialization.
  • /etc/X11/gpe-login.pre-session You can also put some code in here that is to be executed before the user session.
  • /etc/X11/Xsession.d/ Finally, scripts in here are executed using the user session's environment.

4.  Starting GPE

If the force is with you, your platform should now be ready to start GPE for the first time.

Code Listing 4.1: Starting the GPE display manager

  # /etc/init.d/xdm restart

We remind PDA people that they should start their own gpe-dm init script instead.

5.  Summary

This is an experimental handbook with experimental ebuilds in the tree. There are a lot of things that can go wrong, including meteors hitting your computer. If you found problems following this handbook, please contact the GPE maintainers at

Congratulations! We promisse there is more to come in the future.


For more information about GPE, try Google and the following references:


Updated July 27, 2009

Summary: This guide provides an introduction to GPE, a fast, low-resorce, desktop environment appropriate for PDAs and netbooks.

Angelo Arrifano

Donate to support our development efforts.

Support OSL
Gentoo Centric Hosting:
Tek Alchemy
Global Netoptex Inc.
Online Kredit Index
Copyright 2001-2009 Gentoo Foundation, Inc. Questions, Comments? Contact us.