Beagle on Gentoo

Introduction

Beagle is available in Gentoo's package tree ("the portage tree"), in app-misc category.

As well as this, Beagle also benefits greatly from certain operating system features, if they are available. This guide details how to configure your system for the optimal Beagle environment.

You can view the latest versions of Beagle available in portage, and on which architectures they are available, here.

Kernel Setup

As mentioned previously, Beagle benefits from having certain features available. Enabling the two kernel features described below is optional but highly recommended.

First, you must be running a kernel with version 2.6.13 or newer. You can check the version of the running kernel by executing:

# uname -r

If your kernel is older than 2.6.13, then you must upgrade. gentoo-sources is the recommended kernel here. See the Gentoo Linux Kernel Upgrade Guide for more information. You may wish to read the rest of this section before starting the upgrade process, so that you do not have to return to the kernel configuration once again to enable the features detailed here.

We must now enter the kernel configuration interface. Typically, this is done by:

# cd /usr/src/linux
# make menuconfig

Inotify

Inotify is a kernel feature which allows applications such as Beagle to monitor file system events very closely. For example, Beagle likes to know when a new file is created, so that it can be processed and added to Beagle's indexes immediately.

Inside the kernel configuration interface, navigate and select the following option:

File Systems -->
 [*] Inotify file change notification support

Inotify is actually on by default, but it is worth checking that it has not been disabled.

Extended Attributes

Extended Attributes (xattrs) are metadata pairs which can be applied to files. Beagle uses these internally for easy access to important information, such as when the file in question was last indexed.

Extended attributes must be enabled for the filesystems you wish beagle to index. This usually includes at least /home (or the filesystem that contains it). You may also wish to index data elsewhere such as system documentation. If so, enable extended attributes for every filesystem with indexable data.

If you use XFS or JFS as your root, then you do not need to do anything, extended attributes are unconditionally available. For other filesystems, navigate and select the relevant options, by looking at the samples below:

File Systems -->
 <*> Second extended fs support
  [*]   Ext2 extended attributes

 <*> Ext3 journalling file system support
  [*]   Ext3 extended attributes

 <*> Reiserfs support
  [*]   ReiserFS extended attributes

NOTE: You only need to select extended attributes for the filesystem(s) that you wish to index data on (usually /home). For example, you do not need to select Reiserfs at all if you do not use it!

Recompiling the Kernel

If any of the instructions above resulted in you modifying your kernel configuration, then you must recompile it and reboot into the new kernel now.

Again, refer to the Gentoo Linux Kernel Upgrade Guide for how to do this. Sample instructions are given here for guidance, but be aware that these may vary depending on your setup and/or personal preference!

# cd /usr/src/linux
# make
# make modules_install
# mount /boot
# cp arch/i386/boot/bzImage /boot/bzImage-2.6.13-gentoo-r4
# nano -w /boot/grub/grub.conf
  ## add a new bootloader entry now!
# umount /boot
# reboot

Enabling Extended Attributes

If you use XFS or JFS, extended attributes are unconditionally available, so you may skip this stage completely. Otherwise, carry on!

Now that we're booted into a kernel with inotify and extended attributes available, we must enable extended attributes for any indexed filesystems (typically /home). This is done with the command:

# mount -o remount,user_xattr /home

That command should complete without error. If your /home is not a separate filesystem, mount the filesystem that contains it (such as /) with the user_xattr mount option.

If you want filesystems other than /home to be indexed by beagle you should enable extended attributes for them also.

Now we need to make this happen automatically upon bootup. To do this, you modify /etc/fstab in your favourite text editor, adding user_xattr to the opts field of your /home filesystem. For example, my /home filesystem had an entry which looked like:

/dev/hda3               /home               reiserfs        noatime                0 0

After modification, it now looks like:

/dev/hda3               /home               reiserfs        noatime,user_xattr      0 0

Now save and exit your text editor.

Unmasking packages

NOTE: If you run your entire system on the testing tree, e.g. you have ACCEPT_KEYWORDS="~x86" in /etc/make.conf, then you may skip this stage. If you are unsure, chances are you run your system primarily on the stable tree, in which case, carry on reading...

Beagle depends on certain packages only available in the testing tree. We must inform Portage that we want to use the testing tree for these required packages.

First, create the profile overlay directory if it does not already exist:

# mkdir -p /etc/portage

Now, open /etc/portage/package.keywords in your favourite text editor, creating the file if it does not already exist, or appending to it if one is already there.

Add the following lines to the file:

app-misc/beagle ~x86
dev-lang/mono ~x86
dev-dotnet/libgdiplus ~x86
dev-dotnet/gtk-sharp ~x86
dev-dotnet/glade-sharp ~x86
dev-dotnet/gecko-sharp ~x86
dev-dotnet/gnome-sharp ~x86
dev-dotnet/gconf-sharp ~x86
dev-dotnet/art-sharp ~x86
dev-dotnet/gnomevfs-sharp ~x86
dev-libs/gmime ~x86
media-libs/libexif ~x86
app-text/wv ~x86
app-office/gnumeric ~x86
gnome-extra/libgsf ~x86
x11-libs/goffice ~x86
dev-dotnet/taglib-sharp ~x86
dev-libs/libbeagle ~x86
dev-dotnet/dbus-glib-sharp ~x86
dev-dotnet/dbus-sharp ~x86

Note that the package list above may differ from what is required to emerge beagle on your machine (depending on package versions and USE flag settings).

Save the file and exit your text editor.

gmime and the Mono USE-flag

Beagle requires gmime-sharp, a component included inside dev-libs/gmime which is only installed when the mono USE-flag is set.

If gmime was built without mono support, then the beagle installation will fail later on.

Open /etc/portage/package.use in your favourite text editor, creating the file if it does not already exist. Add this line:

dev-libs/gmime mono

Save and exit the file.

Alternatively, you can add mono to your global USE variable, found in /etc/make.conf

Now (re-)install gmime:

# emerge --oneshot -av gmime

Configuring USE flags

Beagle responds to a number of USE flags to customise the available features. Note that some of these flags will introduce extra dependencies (although this will be handled automatically by portage).

Once you have decided which flags you would like to enable, if any, then you can modify /etc/portage/package.use. For example, if I wanted to enable CHM and PDF file indexing, I would add a line that reads:

app-misc/beagle pdf chm

Alternatively, if you wish to make these flags a global preference, you can add them to the USE variable in /etc/make.conf.

Installing Beagle

This is the easy part. Run:

# emerge -av app-misc/beagle

After confirming your choice by entering "Yes", Beagle and its dependencies will be built. This may take a while.

If the merge process exit during dev-util/dialog configure script because it find a problem with ncurses library you may recompile ncurses with the USE flag unicode. Probably ncurses library has been already installed on your Gentoo system but you must reinstall it (see Gentoo Bugzilla to find more information).

Starting the Beagle Daemon

You are now in a position to start Beagle. Beagle works as a daemon and a client.

On first run, it is worthwhile running it in the foreground to check that no immediate errors appear. You can do this with:

# beagled --debug --fg

You'll see a fair amount of text fly up the screen, this is normal, as long as there aren't any obvious errors or exceptions. Within a few seconds, you should see beagle start to index your data.

Once you are happy that Beagle is running OK, then you can shut it down from another console:

# beagle-shutdown

You can now run beagled as a background process, where it is best suited.

# beagled

Autostarting the Beagle Daemon

You'll probably want to set the beagle daemon to be executed when your desktop environment loads. Note that its best to do it this way rather than loading it on bootup, as beagle likes to be able to connect to an X server to determine if the screensaver is running (beagle will index your files faster when it detects the system is not in use).

GNOME users can do this by clicking on the Desktop menu, going to Preferences, then Sessions. In the Sessions dialog, choose the Startup Programs tab, and add an entry which executes beagled.

If you use KDE, you need create a link to the beagle daemon in your KDE autostart directory. This is found at ~/.kde/Autostart. The following commands create the link:

cd ~/.kde/Autostart
ln -s /usr/bin/beagled beagled

Installing the Browser extensions

Beagle also includes Firefox and Epiphany extensions which will allow beagle to index the web pages that you visit. To install them, just enable the corresponding USE flags as explained above.

Optional crawling locations

In /etc/beagle/ there are files named crawl-* which allow static queryables such as Portage and system documentation to be indexed. They are all disabled by default.

To enable them, set CRAWL_ENABLED to "yes" for each item you want indexed and then restart beagled. It may take several hours for the data to be added to the beagle index.

More info

No doubt you have lots of questions how Beagle works and how to customise it. You should probably spend some time looking around the rest of this site.

Have fun!

Bug reports

If you have any questions about Beagle on Gentoo Linux you can send an email to the maintainers. Beagle is maintained by Daniel Drake <dsd@gentoo.org>. If you have any bugs please file them at http://bugs.gentoo.org/

Authors

Originally written by Daniel Drake (dsd@gentoo.org). Other contributors are listed in the page history.

Additional thanks to the contributors to the original guide found on the Gentoo Wiki.