Blackbox Documentation/Installing Blackbox

This section explains how to get Blackbox installed in various distributions and operating systems, and how to integrate it in various desktop environments. It assumes that you already got hold of a Blackbox binary package, and that you can install binary packages (it also explains how).

If you have a Blackbox source package go to /CompilingBlackbox to learn how to obtain a binary. You can come back here after that.
If you wonder where to get binary packages, or want to quickly check the latest binary version published for your system, see DownloadBlackbox.
If you want keyboard handling (yes, you most likely do), then don't forget that Blackbox 0.70+ needs bbkeys version 0.9+. Older versions will NOT work. Install and update bbkeys along with Blackbox all the time.

Try to keep the entries in each subsection ordered alphabetically.

1 Desktop environments

1.1 Gnome

1.2 KDE

2 Operating systems and distributions

2.1 Debian

2.2 Fedora Linux

2.3 Gentoo Linux

2.4 Mac OS X

2.5 Slackware Linux

1) Desktop environments

This section explains how to use Blackbox together with various desktop environments. Usually this means you have to find a way to retain as much as possible from the environment, while replacing its usual window manager with Blackbox.

1.1) Gnome

It is perfectly possible to use Blackbox 0.70+ together with Gnome 2+, because they both follow the NetWM standard.

You can use Blackbox to replace Gnome's standard window manager (Metacity, most likely). Be advised that Blackbox will not pick up theme changes from Gnome, like Metacity does. You will have to adjust its looks separately.

There are two scenarios involved: one is where you start the graphical environment from the console yourself, by typing startx. In this case, you need to edit the file .xinitrc (yes, with a dot) in your home directory. You can use any text editor for this. Create the file if it doesn't exist. This is what you should put in it:

#!/bin/bash
gnome-session &
exec blackbox

If you use a graphical login manager (ie. after you start the computer you are greeted by a nice graphical login prompt) the situation changes somewhat. First, instead of .xinitrc you need to edit .xsession and put the same as above in it. Second, at the login screen you have a menu called "Options" somewhere; go inside and choose the "default session".

For the more advanced users: it's probably a good idea to symlink one of .xinitrc and .xsession to the other.

Reportedly, Blackbox works fine with Gnome in this manner, and it even causes the environment to start faster.

Please note that in order to be able to access the Blackbox menu by right-clicking on the desktop you need to start the Configuration editor/Apps/Nautilus/Preferences and uncheck "Show desktop".

1.2) KDE

It is perfectly possible to use Blackbox 0.70+ together with KDE 3+, because they both follow the NetWM standard.

If you're using startx from the console, or XDM, Blackbox can be run instead of the KDE 3+ window manager (kwin) by setting the KDEWM environment variable to blackbox before executing startkde. For example, in your ~/.xinitrc and/or ~/.xsession:

#!/bin/sh
KDEWM=blackbox
export KDEWM
exec startkde

Note that if blackbox is not in your $PATH, you may need to set KDEWM to the full path where the blackbox binary executable is installed.

If you want to run the KDM and use Blackbox with it, please read how to use new window managers with KDM*. Also read about the session program* which allows you to start various applications when the KDM session starts.

Notes

Blackbox does not support session management. Saving and restoring sessions will not work.
Even though Blackbox is running in KDE, Blackbox will use your chosen style. It will not use the KDE color scheme.
KDE uses an application called kdesktop to display the background and desktop icons. This application completely covers the root window, which means:
1. You cannot access the root and workspace menus unless you explicitly kill kdesktop.
2. The rootCommand in your preferred style will not seem to have any effect, since kdesktop will soon replace the background or wallpaper.

2) Operating systems and distributions

2.1) Debian

Why not "Debian Linux"? Because Debian is a generic distribution. There is a Debian Linux, but there's also Debian BSD or Debian Solaris. The instructions below should work in any kind of Debian.

Blackbox is available via the apt repositories. The latest version is usually part of the unstable distribution. See the official Debian unstable*, testing*, or stable* pages for Blackbox, for more Debian-specific information.

To install Blackbox on Debian, open a terminal and follow the instructions below. Please remember that you must have the apropriate repositories configured in your /etc/apt/sources.list file in order to be able to use apt properly.

Please note that there are many other tools that you can use to update packages on Debian. Besides apt-get there are also graphical updaters, such as synaptic for the desktop, or aptitude for the console.

First, update your installed package base:
```
apt-get update
```

Next, if you are installing Blackbox for the first time:
```
apt-get install blackbox
```

If you want a Blackbox version from another distribution branch from the one you currently have installed, append the distribution name (mind those dependencies!):
```
apt-get install blackbox/unstable
```

If you already have Blackbox installed, you can only upgrade it to the latest version:
```
apt-get upgrade blackbox
...or...
apt-get upgrade blackbox/unstable
```

Finally, you can just bring your entire Debian installation up to date, doing one of the following:
```
apt-get upgrade
...or...
apt-get dist-upgrade
```

Tip: Don't forget to also install or update bbkeys, using similar commands.

2.2) Fedora Linux

Fedora installs the Gnome Display Manager (gdm) by default when you install X Windows, whether or not you install the Gnome Desktop. Whether you install Blackbox from source or an rpm, it's common to find that it's not integrated well into the gdm login screen's Sessions menu.

An easy per-user solution is to leave the session set to Default System Session and create an executable .Xclients file in the $HOME directory. In the example below, a startup script is used to avoid code duplication with the .xsession file, and twm is indicated as a fallback window manager.

~/.Xclients
#!/bin/bash
if which blackbox >/dev/null 2>&1; then
    $HOME/.blackbox/startup &
    exec blackbox
else
    exec twm
fi

~/.blackbox/startup
#!/bin/bash
sleep 1 && bbpager -w &
sleep 2 && bbkeys

2.3) Gentoo Linux

Downloading, compiling and installing from Blackbox source code using emerge tool.
```
# emerge blackbox
```
In your home directory, edit .xinitrc, add line exec blackbox and comment out your previous one. It looks like the following in mine:
```
exec blackbox
#exec gnome-session
```
Run startx to begin the X-windows:
```
$ startx
```
Enjoy! :)

2.4) Mac OS X

Sao's Place* aims to provide documentation for installing X11 on Apple computers with the means provided by the Fink project*. It recommends* Blackbox among the preferred window managers, and offers a few tips* for installing and using it.

2.5) Slackware Linux

The latest Blackbox package for Slackware Linux* is provided here*. If you are running another version of Slackware Linux, you can use the blackbox-slackbuild archive* to build your own Slackware package for Blackbox.