Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Document last modified: Tue, 15 Jun 2010, 20:20 UTC
Parents: BlackboxDocumentation/

Blackbox Documentation/Compiling Blackbox

This page teaches you what you need to know in order to produce a working Blackbox binary from the Blackbox source or from BlackboxCVS.

Note: You only need to do this if you use a source package. You don't have to. Many operating systems and distributions offer a binary package ready for consumption.

See also: BlackboxRequirements lists several packages whose presence on your system may facilitate compilation or expand the Blackbox feature set. BlackboxFAQ/InstallAndCompilation may occasionally hold useful Q&A's.

1 Preparations
1.1 Get the source
1.2 The command line
1.3 Compilation requirements
2 How to use patches
3 How to compile Blackbox
3.1 Preparations
3.2 Compilation
3.3 Recompilation
3.4 Installation
3.5 System integration
3.6 Deinstallation
4 Common compilation issues
4.1 mk.sh fails when trying to compile CVS
5 System- and architecture- specific compilation issues
5.1 Cygwin
5.2 OpenBSD
5.3 Slackware
5.4 Solaris

1) Preparations

1.1) Get the source

You will need the Blackbox source code for this, obviously. See DownloadBlackbox or BlackboxCVS.

1.2) The command line

Most of the compilation is done from the command line.

The command line is a text-only interface where you enter commands as words and the interpreter uses various programs installed on your machine to execute them and reports the outcome.

If you don't know how to reach the command line, it's probably not a good idea to attempt to compile anything from source. But here's a hint anyway: look for something called a terminal.

If you are fairly familiar with the command line, please proceed. Note however that you will be expected to change directories, unpack tarballs, execute commands and know the difference between being root or a regular user.

1.3) Compilation requirements

The following pieces of software are needed in order to be able to compile Blackbox from source. Your distribution/operating system should provide packages for them. These requirements regard the latest Blackbox release only.

PackageMinimum versionHow to tell version
automake1.9+automake --version
libtool1.5.6-3+libtool --version
makerecentmake -v
binutilsrecentld -v
C++ compiler (GNU or Intel)recentgcc -v, icpc -V

FIXME: are there minimum required versions of make and binutils? Are there other packages which should be present and checked for?

Note: Some distributions (Debian) may ship an automake which reports version 1.4, but is actually a patched and improved 1.4, which will still work. You can proceed with the compilation if this is the case.

2) How to use patches

Source patches are text files which describe differences between the "official" Blackbox source code and whatever their creator wanted to achieve. Using patches means applying these differences to a Blackbox source copy before you compile it.

There are many source patches* made available by various contributors, but not all of them are accepted into the Blackbox source. BradleyHughes is the one who gets to decide whether what a patch does is "good" or "desirable".

Note: A clean, official source, without any patches applied, is sometimes referred to as vanilla source.

What to be careful about:

Here's how you use a patch:

  1. Unpack a source package somewhere, and go under the main directory.
  2. Run this:
    patch -F100 -p1 --dry-run < /path/to/patch/file
  3. If you don't see FAILED anywhere, you can safely repeat the command without --dry-run.
  4. If any part failed, you're out of luck. The patch doesn't apply to the source you have for some reason. Don't use the source you've patched half-way, it won't work well or at all.

If everything worked out well, proceed with compiling Blackbox. Please note that even the patching is successful, there are no guarantees to how the resulting Blackbox will behave.

3) How to compile Blackbox

3.1) Preparations

First, you must make sure you meet the requirements described above. We will assume that you have all the proper packages installed, and that you obtained a source copy and unpacked it somewhere.

3.2) Compilation

FIXME: Describe the various configure options fully?

You can perform these commands as an unpriviledged user, in the privacy of your own /home.

  1. Go under the main source directory (blackbox/).
  2. This step is only needed if you got Blackbox from CVS, because in this case you need to generate the configure script. So run the mk.sh script to generate configure. You might want to adjust the path for aclocal first, see below. You know that mk.sh was successful if after you run it you obtain a configure executable in the same directory.
  3. Run the configure script. This is needed for automatically configuring build settings. Run ./configure --help to see interesting additional options. Pay special attention to --prefix, because it decides the install directory; it's a good idea to choose a separate one, such as /opt/blackbox.
  4. Run make to begin the build process. This may take a few minutes.

3.3) Recompilation

This section only applies if you intend to compile Blackbox from the same directory, again. It does not apply to clean (freshly unpacked) source copies!

You may want to recompile Blackbox from the same source directory at some point, for various reasons (lazyness, mostly). If you do, there are some things you must observe.

We can assume that the source has already passed through a mk.sh, configure and make (possibly make install, too). This process produces certain extra files that weren't there in the original source, and which are highly dependent on the particular state of your machine and the packages on it at the moment of the previous compilation. You need to revert this state and eliminate these files before you can recompile safely.

To do this, go under the main directory of the source code and issue one of the following commands.

Warning: running either of the cleaning commands will destroy the possibility of performing a deinstallation.

3.4) Installation

After compilation (mk.sh, configure, make) you can run the following command to install Blackbox. It must be run from under the main source directory.

make install

If the installation PREFIX is a location where only the root has access (such as the default) then you need to be root when you do this.

Warning! The installation process doesn't care about overwriting files! Generally, it is considered a bad idea to let Blackbox install wherever it wants, because it may break something else, or it may be hard to uninstall. See the --prefix option for configure.

The installation process will take a directory (called the PREFIX) and put Blackbox files in certain subdirectories. The default PREFIX is system-specific. You can find out what it is by running ./configure --help and looking for --prefix.

Usually, it defaults to /usr/local. If you want to change this, pass the --prefix option to configure.

Here are the typical subdirectories used by installation:

3.5) System integration

Once installed, you need to make sure that all the Blackbox bits are known to the system.

Note: by PREFIX we mean the directory that it resolves to during compilation, NOT literally "PREFIX".

Executable files
  • Executable files are the ones installed under PREFIX/bin/. You need to have this directory in your PATH environment variable, so that Blackbox-specific executables can be found by the system.
    • You can check this by running echo $PATH from the command line. If PREFIX/bin appears in it, it's alright.
    • You can also check by trying to run bstyleconvert or bsetroot and see if they run.
  • If the executables are not in the PATH, you can add them. Edit either /etc/profile or ~/.bash_profile and add the following line at the end. You will need to re-login for the changes to take effect.
    export PATH="${PATH}:/usr/local/bin"
  • The files installed under PREFIX/lib. Blackbox (and other 3rd party applications which use the libraries) will not run if they are not properly integrated.
  • To check if they are already integrated, run ldconfig -v as root and look for "libbt".
  • If they are not, edit /etc/ld.so.conf, add the directory, then run ldconfig again.
  • Alternatively, if you don't have root access, put the directory in the environment variable LD_LIBRARY_PATH, in a manner similar to PATH (described above).
Manual pages
  • UNIX manual pages, installed under PREFIX/man. You need to add this directory to /etc/man.config or /etc/manpath.config, with a line such as this:
    MANDATORY_MANPATH /usr/local/man
  • If you don't have root access to do the above you can simply read the manual page by passing it directly to man:
    man /usr/local/man/man1/blackbox.1
Header files
  • These are .h files (C++ source code) which are placed under PREFIX/include.
  • You only need to worry about these if you attempt to compile 3rd party Blackbox tools yourself. It can happen, most often with bbkeys.
  • You only need to make sure that, before you start compilation of that tool, the LDFLAGS environment variable contains the location of the headers. To do it, run this command (replace PREFIX as needed):
    export LDFLAGS="-I /usr/local/include"

You don't have to worry about PREFIX/share. Blackbox will remember where it was installed and attempt to deduce the location of the share/ subdirectory on the fly.

3.6) Deinstallation

If you were thoughtful and used the --prefix option with configure with a separate directory, you can achieve uninstall by simply going and deleting that directory (example: /opt/blackbox).

If you went with the default, the Blackbox files are now mingled with many many others on your system. You can take a look at the install section above and try to infer what they are and then remove them by hand.

If you still have the source directory around and you haven't performed any of the cleaning commands on it, you can obtain uninstall by going under the main source directory and issuing this command:

make uninstall

You need to be root if the target directories are system directories (ie. not under your /home).

If you broke or deleted your source directory, all is not lost. Get another (of a similar Blackbox version), and compile Blackbox again (without installing). Then issue a make uninstall.

4) Common compilation issues

4.1) mk.sh fails when trying to compile CVS

Sometimes mk.sh will fail with error messages that look like the ones below and get gradually worse:

aclocal: couldn't open directory `/usr/local/share/aclocal': No such file or directory
You should add the contents of `/usr/share/aclocal/libtool.m4' to `aclocal.m4'.

The problem is caused by aclocal not finding the required .m4 files.

By default, mk.sh tells it to look only in /usr/local/share/aclocal, but the correct location may vary from system to system. Sometimes the operating system or distribution maintainers choose a different location. Sometimes people relocate these files themselves (common for people running their custom distributions, such as LFS).

Solution: Edit mk.sh and look for the following line:

${ACLOCAL-aclocal} -I /usr/local/share/aclocal

Find out what the correct location is for your system and either fix the above or (safer) add extra -I options on that line, pointing to directories which contain .m4 files. Remember: you want directories, not files.

In order to figure out the correct location, you can use either of the following commands. Looking for libtool.m4 is usually a safe bet. Prefer locations starting with /usr over others, should you find several.

locate share/aclocal/libtool.m4
locate libtool.m4
find / -type f -name libtool.m4
find /usr -type f -name libtool.m4

5) System- and architecture- specific compilation issues

Add solutions too, please, not just problems! If you have a problem only, please add it to BlackboxFAQ/NewQuestions instead!

Please keep the list below ordered alphabetically.

When you are absolutely sure that an issue affects only a particular version, place it in a subsection (ie. make a Red Hat 9 subsection under Red Hat). But only if you are positive.

When several issues gather in a subsection, use horizontal breakers to separate them. It helps people find stuff faster.

5.1) Cygwin

This explains how to install and use Blackbox with Cygwin. First, you will need a Blackbox binary compiled for Cygwin. You can find one at StokeBloke.com*, or you can compile your own.

You also need Cygwin/XFree, naturally. You can start X with a sh script from the bash console, but you can also start the X server with a .bat file such as /usr/X11../bin/starxwin.bat. The .bat solution will use TWM as the default window manager, so you'll need to edit the .bat file to use Blackbox instead of TWM.

You may want to consider some of the Blackbox ports under RelatedProjects, such as bb4win. These can replace the Windows shell completely, and are native Windows applications, so you wouldn't need neither Cygwin nor X.

5.2) OpenBSD

Note: This problem was FIXED in 0.70.1, with a configure check. Update!

The CODESET compile error:

 -DLOCALEPATH=\"/usr/local/share/blackbox/nls\" -I/usr/local/include \
 -I/usr/X11R6/include -g -O2 -Wall -W -pedantic -Woverloaded-virtual -Wshadow \
 -I/usr/X11R6/include -I/usr/X11R6/include/freetype2 -I/usr/X11R6/include \
 -MT Unicode.lo -MD -MP -MF .deps/Unicode.Tpo -c Unicode.cc -o Unicode.o
Unicode.cc: In function `bool bt::hasUnicode()':
Unicode.cc:170: error: `CODESET' undeclared (first use this function)
Unicode.cc:170: error: (Each undeclared identifier is reported only once for 
   each function it appears in.)
*** Error code 1

Unfortunately, OpenBSD doesn't fully implement POSIX in this respect. CODESET is supposed to be defined* in langinfo.h, and it isn't on OpenBSD.

However, there's a workaround. By replacing the following code in lib/Unicode.cc:


with the following:

#if defined(HAVE_NL_LANGINFO) && ! defined(__openbsd__)

...you will disable the problematic code.

5.3) Slackware

On Slackware (10.1 at least), the aclocal files are in a "non-standard" location. It's one of the common compilation pitfalls, see above. So if you attempt to compile CVS, you will need to edit the mk.sh file and change line #3 to include /usr/share/aclocal:

${ACLOCAL-aclocal} -I /usr/share/aclocal

This problem is not present on Slackware 11.

5.4) Solaris

Install GNU iconv and set LDFLAGS to -liconv before running configure. Yes, even though iconv_* are in libc on Solaris.

Compiling under Solaris 9 with gcc produces these errors:

/usr/openwin/include/X11/Xutil.h:117: error: 'Bool' is used as a type, but is not defined as a type.
/usr/openwin/include/X11/Xutil.h:120: error: 'Pixmap' is used as a type, but is not defined as a type.
/usr/openwin/include/X11/Xutil.h:121: error: 'Window' is used as a type, but is not defined as a type.

Fix it by adding #include <X11/Xlib.h> before the line #include <X11/Xutil.h> in BlackboxResource.cc.

Would someone confirm if this issue is Solaris 9 specific or appears on other versions too?
I just compiled Blackbox 0.70.1 on Solaris 8, and did not encounter this issue. -- AndyReitz
I did not run into the above issues (Pixmap and Window), but had to install gnu libiconv and use -liconv.--JoeLenox?

Compiling on Solaris 10 05/09:

I made the following changes and used -liconv to compile blackbox on gcc 4.4.0 on Solaris 10 (x64).

diff -r blackbox-0.70.1/lib/Image.cc blackbox-0.70.1.new/lib/Image.cc
> #include <cstring>
Only in blackbox-0.70.1.new/lib: Makefile
diff -r blackbox-0.70.1/lib/Resource.cc blackbox-0.70.1.new/lib/Resource.cc
> // Added for solaris 10
> #include <strings.h>
diff -r blackbox-0.70.1/lib/XDG.cc blackbox-0.70.1.new/lib/XDG.cc
> // Added for Solaris 10
> #include <string>

diff -r blackbox-0.70.1/src/BlackboxResource.cc blackbox-0.70.1.new/src/BlackboxResource.cc
> // Added for Solaris 10
> #include <strings.h>
Only in blackbox-0.70.1.new/src: Makefile
diff -r blackbox-0.70.1/src/Screen.cc blackbox-0.70.1.new/src/Screen.cc
> // Added for solaris 10
> #include <cstring>
diff -r blackbox-0.70.1/src/ScreenResource.cc blackbox-0.70.1.new/src/ScreenResource.cc
> // Included for Solaris 10
> #include <strings.h>
diff -r blackbox-0.70.1/src/main.cc blackbox-0.70.1.new/src/main.cc
> // included for Solaris 10
> #include <strings.h>
Only in blackbox-0.70.1.new/util: .deps
Only in blackbox-0.70.1.new/util: Makefile
diff -r blackbox-0.70.1/util/bsetroot.cc blackbox-0.70.1.new/util/bsetroot.cc
> // Next line for Solaris 10
> #include <stdlib.h>
> #include <strings.h>

eXTReMe Tracker Hosted by SourceForge.net
Document last modified: Tue, 15 Jun 2010, 20:20 UTC
Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Hosted by SourceForge. Powered by Wikki Tikki Tavi. About the website. Terms of use.