icecream

Icecream was created by SUSE based on distcc. Like distcc, Icecream takes compile jobs from a build and distributes them among remote machines allowing a parallel build. But unlike distcc, Icecream uses a central server that dynamically schedules the compile jobs to the fastest free server. This advantage pays off mostly for shared computers, if you're the only user on x machines, you have full control over them.

Table of Contents

• Installation

• How to use icecream

  • make it persistent

• TroubleShooting

  • Firewall
  • C compiler
  • osc build
  • some compilation nodes aren't used
  • build with -Werror fails only when using icecream
  • clang 4.0 tries to read /proc/cpuinfo and fails

• Supported platforms

• Using icecream in heterogeneous environments

• Cross-Compiling using icecream

• Creating cross compiler package

• Cross-Compiling for embedded targets using icecream

• Cross-Compiling for multiple targets in the same environment using icecream

• How to combine icecream with ccache

• Debug output

• Some Numbers

• What is the best environment for icecream

• Some advice on configuration

• Network setup for Icecream (firewalls)

• I use distcc, why should I change?

• Icecream on gentoo

• Bug tracker

• Repository

• Mailing list

Installation

We recommend that you use packages maintained by your distribution if possible. Your distribution should provide customized startup scripts that make icecream fit better into the way your system is configured.

We highly recommend you install icemon or icecream-sundae with icecream.

If you want to install from source see the instructions in the README file provided in the source package.

How to use icecream

You need:

• At least one machine that runs the scheduler ("./icecc-scheduler -d")
• Many machines that run the daemon ("./iceccd -d")

It is possible to run the scheduler and the daemon on one machine and only the daemon on another, thus forming a compile cluster with two nodes.

If you want to compile using icecream, make sure $prefix/lib/icecc/bin is the first entry in your path, e.g. type

 export PATH=/usr/lib/icecc/bin:$PATH

(Hint: put this in ~/.bashrc or /etc/profile to not have to type it in everytime.)

Then you just compile with make -j <num>, where <num> is the amount of jobs you want to compile in parallel. As a start, take the number of logical processors multiplied with 2, or a larger number if your compile cluster can serve all the compilation jobs. But note that too large numbers may in fact make the build slower (for example if your local machine gets overloaded with preparing more jobs than it can handle at a time).

Here is an example:

 make -j6

WARNING: Never use icecream in untrusted environments. Run the daemons and the scheduler as unprivileged user in such networks if you have to! But you will have to rely on homogeneous networks then (see below).

If you want an overview of your icecream compile cluster, or if you just want funny stats, you might want to run "icemon" (from a separate repository/package).

make it persistent

If you restart a computer, you still want it to be in the icecream cluster after reboot. Consult your distribution's documentation on this. If you use packages provided by your distribution this should be automatic (or a simple configuration change).

make scheduler persistent:

By adding options --scheduler-host for daemon and --persistent-client-connection for scheduler, the client connections are not disconnected from the scheduler even if there is an availability of better scheduler.

TroubleShooting

Most problems are caused by firewalls and by make using the wrong C compiler (e.g. /usr/bin/gcc instead of /usr/lib/icecc/bin/gcc).

Firewall

For testing purposes, you can stop your firewall like this:

 rcSuSEfirewall2 stop

To open the right ports in your firewall, call

 yast2 firewall

Choose "allowed services" -> Advanced. Enter for TCP 10245 8765 8766 and for UDP 8765.

If you have the scheduler running on another system, you should open broadcasting response:

 yast2 firewall

Choose "Custom Rules" -> Add. Enter Source Network 0/0, Protocol UDP, Source Port 8765.

C compiler

To make sure your compile job uses /usr/lib/icecc/bin/gcc (gcc is used as an example here, depending on your compile job it can also be g++, cc or c++) start your compile using

 make VERBOSE=1

and wait for a typical compile command to appear, like this one:

 cd /root/kdepim/kode/libkode && /usr/lib/icecc/bin/c++  -DTest1Area=5121 -D_BSD_SOURCE
 -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -DQT_NO_STL
 -DQT_NO_CAST_TO_ASCII -D_REENTRANT -DKDE_DEPRECATED_WARNINGS
 -DKDE_DEFAULT_DEBUG_AREA=5295 -DMAKE_KODE_LIB -Wnon-
 virtual-dtor -Wno-long-long -ansi -Wundef -Wcast-align
 -Wchar-subscripts-Wall -W -Wpointer-arith -Wformat-security
 -fno-exceptions -fno-check-new

In this example, the right c compiler is chosen, /usr/lib/icecc/bin/c++. If the wrong one is chosen, delete CMakeCache.txt (if existing) and start the build process again calling ./configure (if existing).

osc build

You can tell osc build to use icecream to build packages by appending --icecream=<n> where n is the number of processes which should be started in parallel. However, for integration with icecream to work properly, you must install icecream on the host where you will run "osc build" and you must start icecream daemon.

some compilation nodes aren't used

If, when using icecream monitor (icemon), you notice some nodes not being used at all for compilation, check you have the same icecream version on all nodes, otherwise, nodes running older icecream versions might be excluded from available nodes.

build with -Werror fails only when using icecream

This problem should not exist with a recent icecream version. If it does, try using ICECC_REMOTE_CPP=1 (see icecc --help).

clang tries to read /proc/cpuinfo and fails

This is a problem of clang 4.0 and newer: https://bugs.llvm.org/show_bug.cgi?id=33008. The most recent Icecream version works around this problem.

Supported platforms

Most of icecream is UNIX specific and can be used on most platforms, but as the scheduler needs to know the load of a machine, there are some tricky parts. Supported are:

  - Linux
  - FreeBSD
  - DragonFlyBSD
  - OS X

Note that all these platforms can be used both as server and as client - meaning you can do full cross compiling between them.

The following platforms are known to work at least as a client, meaning that you can run compilation on them that will compile on remote nodes using cross compilation.

  - Cygwin

Using icecream in heterogeneous environments

If you are running icecream daemons in the same icecream network but on machines with incompatible compiler versions, icecream needs to send your build environment to remote machines (note: they all must be running as root. In the future icecream might gain the ability to know when machines can't accept a different env, but for now it is all or nothing).

Under normal circumstances this is handled transparently by the icecream daemon, which will prepare a tarball with the environment when needed. This is the recommended way, as the daemon will also automatically update the tarball whenever your compiler changes.

If you want to handle this manually for some reason, you have to tell icecream which environment you are using. Use

  icecc --build-native

to create an archive file containing all the files necessary to setup the compiler environment. The file will have a random unique name like "ddaea39ca1a7c88522b185eca04da2d8.tar.bz2" per default. Rename it to something more expressive for your convenience, e.g. "i386-3.3.1.tar.bz2". Set

  ICECC_VERSION=<filename_of_archive_containing_your_environment>

in the shell environment where you start the compile jobs and the file will be transferred to the daemons where your compile jobs run and installed to a chroot environment for executing the compile jobs in the environment fitting to the environment of the client. This requires that the icecream daemon runs as root.

Cross-Compiling using icecream

SUSE got quite some good machines not having a processor from Intel or AMD, so icecream is pretty good in using cross-compiler environments similar to the above way of spreading compilers. There the ICECC_VERSION variable looks like <native_filename>(,<platform>:<cross_compiler_filename>)*, for example like this:

 /work/9.1-i386.tar.bz2,ia64:/work/9.1-cross-ia64.tar.bz2,Darwin_PowerPCMac:/work/osx-generate-i386.tar.gz

To get this working on openSuse machines there are some packages containing the cross-compiler environments. Here is a sample case showing how to do to get it working. Let's assume that we want to build for x86_64 but use some i386 machines for the build as well. On the x86_64 machine, go to http://software.opensuse.org, search for icecream x86_64 and download and install the version for i586. Then add this to the ICECC_VERSION and build.

 i386:/usr/share/icecream-envs/cross-x86_64-gcc-icecream-backend_i386.tar.gz

Creating cross compiler package

How to package such a cross compiler is pretty straightforward if you look what's inside the tarballs generated by icecc. You basically need a /usr/bin/gcc, a /usr/bin/g++ and a /usr/bin/as. So if you need a cross compiler that uses your OS X running G5 to compile i586-linux for your laptop, you would:

• go to your OS X and download binutils and gcc (of the versions you use on linux)

• first compile and install binutils with --prefix /usr/local/cross --target=i586-linux (I have some problems that required setting CC and AR)

• configure gcc with the same options, go into the gcc directory and make all install-driver install-common - that worked good enough for me.

• now create a new directory where you copy /usr/local/cross/bin/i586-linux-{gcc,g++,as} into as usr/bin/{gcc,g++,as}

• now I copy an empty.c (that is empty) into that dir too and call

  chroot . usr/bin/gcc -c empty.c

that will report an error about