Install and usage

Work in progress... soon will be ready.

Here you will find instructions in many ways to install, test and use Bumblebee.

Install

The best an recommended way to install Bumblebee is through your distribution repositories. If not such packages exist, then you can still install Bumblebee from git.

Install from packages

WIP

ArchLinux

Ubuntu

Install from Git

Here are some instructions on how to build the Bumblebee daemon (bumblebeed) and client (optirun). Whenever you see a command preceded by # means it must be run as root (i.e. with sudo).

Prerequisites

You will need the following:

Your card's drivers with 3D acceleration enabled (either nvidia or nouveau)
VirtualGL software (www.virtualgl.org)
pkg-config
autotools (2.68+ recommended)
libX11 and developer headers
git
bbswitch (optional for Power Management)

Build and install

Now go to a directory of our liking, clone the repository and build the binaries

$ git clone git://github.com/Bumblebee-Project/bumblebeed.git
$ cd bumblebeed
$ autoreconf -fi
$ ./configure
$ make

Note: for system-wide installations, additional arguments must be passed to ./configure script. Most times $ ./configure --prefix=/usr --sysconfdir=/etc is enough. Run $ ./configure --help for more information

To install just run

# make install

Then you must create group bumblebee on your system and add yourself to it

# groupadd bumblebee
# usermod -a -G bumblebee $USER

Log out and in again to apply changes.

Usage

First you would like to take a look at Configuration to tweak Bumblebee to your liking. Then you must run the Bumblebee daemon

# bumblebeed -vv

Run $ bumblebeed --help for more options.

To run a program you just run

$ optirun <program-name>

Example

$ optirun glxgears

will run glxgears on your dedicated GPU.

WIP

#Deprecated below

Post-installation steps

When installed this way. Bumblebee needs some distribution-specific and machine-specific configurations.

Add the user to the `bumblebee`group

For a user to be able to run Bumblebee, (s)he needs to be part of the bumblebee group. To do so:

# usermod -a -G bumblebee <username>

Setting up the daemon handler

You must install a daemon handler and register it to the system services for Bumblebee to work. There is a distro-agnostic handler located on the data directory (default to /usr/local/share/bumblebee) that can be used when no distribution-specific handler is present. You should copy the handler executable file to your init directory (/etc/init.d/ in Ubuntu, /etc/rc.d/ in ArchLinux) and register it to start at boot.

Setting up bash completion (optional)

There is a file for bash completion on the data folder, that must be installed manually on the appropriate directory. Under Archlinux is /etc/bash_completion.d/optirun

Configuring the BusID of the nvidia card

Then you will need to edit the files CONFDIR/xorg.conf.{nvidia,nouveau} to set the PCI BusID of your nvidia card. To get the BusID of your card:

$ lspci -d 10de: -n | grep '030[02]:' | cut -d' ' -f1 | tr . :

Then copy the output in this manner:

...
Section "Device"
    ...
    BusID "PCI:<BUISID>"
EndSection
...

TODO: AUTOMATING POST INSTALL

Here is an example post installation script for the ArchLinux package:

_replace_busid() {
    NVIDIABUSID=$(lspci -d 10de: -n | grep '030[02]:' | cut -d' ' -f1 | tr . :)

    case $(wc -l <<<"$NVIDIABUSID") in
      0)
        echo "The BusID of the nVidia card can't be determined."
        ;;
      1)
        NVIDIABUSID="PCI:$NVIDIABUSID"
        echo "Detected Bus ID: $NVIDIABUSID"
        ;;
      *)
        # You'll never know.
        echo "Multiple graphics cards are not supported by Bumblebee yet. The"
        echo "following PCI Bus IDs have been detected:"
        echo "$NVIDIABUSID"
        echo "If this information is wrong, please report it to:"
        echo "https://github.com/Bumblebee-Project/Bumblebee/issues"
        # empty the ID so we can detect this as error
        NVIDIABUSID=
        ;;
    esac

    re_busid='^( *BusID +")[^"]*'

    sed -E -i "$1" -e "s,${re_busid},\1${NVIDIABUSID},"
}
post_install() {
    if [ -f /etc/bumblebee/xorg.conf.nvidia ]; then
        _replace_busid /etc/bumblebee/xorg.conf.nvidia
    fi
    if [ -f /etc/bumblebee/xorg.conf.nouveau ]; then
        _replace_busid /etc/bumblebee/xorg.conf.nouveau
    fi
    groupadd bumblebee && echo "Bumblebee group created"
    echo
    echo "Installation complete..."
    echo "Visit ArchWiki page on Bumblebee for documentation on how to finish setup,"
    echo "configure and run applications with Bumblebee:"
    echo "http://wiki.archlinux.org/index.php/Bumblebee"
    echo
}

About the former (deprecated) installer

Warning: This installer is to be deprecated and it's usage is discouraged.

The installer is divided into steps and has several configurable variables to make it as flexible as possible. Each stage is grouped into categories according to their task. Some stages can be skipped. For a description of each stage see "Stages" below.

Stages and their groups

setvars
checkprivileges [precheck]
builddir [build]
determinedistro [precheck, build, install, postconfig]
DISTRO/setvars [precheck, build, install, postconfig]
detectoldversion [precheck]
welcome
DISTRO/checkdependencies [precheck]
uninstall
buildfiles [build]
copyfiles [install]
createuninstaller [installuninst]
configure [postconfig]
DISTRO/configure [postconfig]
finish

Variables like paths are fully configurable giving arguments to the installer, but be aware that the stage "DISTRO/setvars" may overwrite them. See Varaibles below.

Directory tree variables

DESTDIR
INITDIR
LIBDIR
BINDIR
SBINDIR

Those are variables where the installer will copy files into. To make a package use these variables to put the files in a directory structure that fits the one of your distribution.

The DESTDIR variable will be your "root" (/) and your start point for the directory tree. All other directories will be relative to that path. This directory must exist.

INITDIR will be the place where the handler will be copied. It defaults to /etc/init.d/ and is where the system will find the means to start/stop the daemon automatically.

LIBDIR is the path where the common-functions and common-paths files are copied. It defaults to /usr/local/lib/bumblebee.

BINDIR will be the path where all executable files are copied (except the daemon binary). It defaults to /usr/local/bin.

SBINDIR will be the path where the daemon binary is copied. It defaults to /usr/local/sbin.

Packaging

Here is a practical example of how you can package Bumblebee. Most GNU/Linux distributions need to store a directory tree in some directory to be compressed with the binaries in their final destination. All the configuration for the specific machine is made afterwards. So if your distribution is not supported yet by the installer you must skip the "determinedistro" stage and set the variables manually. Also you must skip the "checkdependencies" stage as the packages names and package query are distro-dependent, the package manager of your distro must handle that (you must specify the dependencies yourself). You might want to skip the "uninstall" stage as the package manager should handle it. Then you must set the variables.

Here is an example on ArchLinux:

Actions to perform (groups of stages): build, install
Stages to skip (this will skip only stages that are in the 'actions' list): uninstall, welcome, finish

Directories (the DESTDIR is set to an existent temporary directory):

INITDIR = etc/rc.d
LIBDIR = usr/lib/bumblebee
BINDIR = usr/bin
SBINDIR = usr/sbin

Then the configuration for specific user/distro should be made with the proper maintainer script. Take a look at the source of the "configure" stage for a guide on it.

Stages

The installer has several stages, each stage performs specific tasks. This is a list of those stages and a brief explanation of what they do:

setvars

This is the most important task and can't be skipped. Here the installer sets variables to be used in the rest of the install process (see Variables for variables description). It will also parse the command line arguments passed to the main script.

checkprivileges

Here the installer checks if it's run by a privileged user (root). You may skip this stage for packaging or when installing on non-system directories.

builddir

This step creates and cleans the BUILDDIR directory used for buildfiles. You may not skip this stage unless there is a good reason and you know what you are doing.

DISTRO/setvars

This stage is optional and may not exist for all GNU/Linux distributions. It will set distribution-specific variables for the installer such as paths. If skipped the installer will assume the defaults in the "setvars" stage. If a variable is set by command argument, this stage may override it.

detectoldversion

Detect if cleanup is needed. Bumblebee 1.7.10 (MrMEEE/bumblebee) or 2.2.0 (ppa:mj-casalogic/bumblebee) and before abused /etc/bumblebee for storing the version. In current versions (Bumblebee-Project/Bumblebee), this is a directory for configuration files. If an old version is detected the installation will fail and warn about this condition.

welcome

Prints a welcome message. You may want to skip this on packaging.

DISTRO/checkdependencies

Here a dependency check is run. If there are dependency packages missing or conflicting packages, the installer will fail but will warn about that condition.

uninstall

This will run an uninstaller from previous version for cleanup before install. If your package manager already does that, you may want to skip this stage.

buildfiles

This is one of the most important stages. Here the files of bumblebee are changed to fit your settings. Paths and file locations are commited here. Don't skip this stage unless you really know what you are doing.

copyfiles

Here is where files get copied to their destinations.

createuninstaller

Every file copied is tracked and put on a list. That list is used by the uninstaller to erase them and get your system bumblebee-free (maybe because you don't love us )':). Skip this stage if your package manager already does it.

configure

Here all the configuration that is specific to your machine is done.

finish

Prints a nice thanks message.

Variables

There are some variables that can be overriden by command arguments. Here is a list of them and the arguments used for setting them.

--driver=DRIVER

--driver DRIVER

Use DRIVER as graphics driver. Currently, the only valid driver is nvidia.
If not specified, nvidia is assumed

--bindir=DIR

--bindir DIR

Install binary files to this directory. Defaults to /usr/local/bin

--sbindir=DIR

--sbindir DIR

Install system binary files to this directory. Defaults to /usr/local/sbin

--libdir=DIR

--libdir DIR

Install library files to this directory. Defaults to
/usr/local/lib/bumblebee

--initdir=DIR

--initdir DIR

Install handler file to this directory. Defaults to
/etc/init.d

--dest-dir=DESTDIR

--dest-dir DESTDIR

Use DESTDIR as root folder instead. Useful for chroot installations. Set it
to an empty value if you do not want to use a different root directory. The
contents of this directory are not cleared before use.

--build-dir=PATH

--build-dir PATH

Use PATH instead of '.build' for storing files built by the installer. PATH
must exist to avoid accidentally overwritting directories. The entries
PATH/stages and PATH/install-files are removed.

Install and usage

Install

Install from packages

ArchLinux

Ubuntu

Install from Git

Prerequisites

Build and install

Usage

Post-installation steps

Add the user to the bumblebeegroup

Setting up the daemon handler

Setting up bash completion (optional)

Configuring the BusID of the nvidia card

TODO: AUTOMATING POST INSTALL

About the former (deprecated) installer

Stages and their groups

Directory tree variables

Packaging

Stages

setvars

checkprivileges

builddir

DISTRO/setvars

detectoldversion

welcome

DISTRO/checkdependencies

uninstall

buildfiles

copyfiles

createuninstaller

configure

finish

Variables

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Add the user to the `bumblebee`group