	     CILK FREQUENTLY ASKED QUESTIONS WITH ANSWERS
  			     09 Oct 2007
			     Matteo Frigo
			  <athena@fftw.org>
			  Bradley C. Kuszmaul
			  <bradley@mit.edu>

This is the list of Frequently Asked Questions about Cilk, a language for
multithreaded parallel programming based on ANSI C.

===============================================================================

Index

 Section 1.  Introduction and General Information
 Q1.1        What is Cilk?
 Q1.2        How do I obtain Cilk?
 Q1.3        Are there Cilk-related mailing lists?
 Q1.4        Is Cilk free software?
 Q1.5        Which systems does Cilk run on?
 Q1.6        Does Cilk run on networks of workstations?
 Q1.7        Does Cilk run on Windows NT?
 Q1.8        What is Cilkchess?

 Section 2.  Installing Cilk
 Q2.1        How do I install Cilk?
 Q2.2        How do I install Cilk in a directory different from /usr/local?
 Q2.3        The example programs compile, but they do not run.
 Q2.4        `make' says: ``Warning: Clock skew detected. Your build may be inc

 Section 3.  Using Cilk
 Q3.1        How do I compile a Cilk program?
 Q3.2        Cilk seems really slow.
 Q3.3        Can I call Cilk from C/C++/FORTRAN?
 Q3.4        The linker says Cilk_flags_are_wrong_*_please_recompile.

===============================================================================

Section 1.  Introduction and General Information

 Q1.1        What is Cilk?
 Q1.2        How do I obtain Cilk?
 Q1.3        Are there Cilk-related mailing lists?
 Q1.4        Is Cilk free software?
 Q1.5        Which systems does Cilk run on?
 Q1.6        Does Cilk run on networks of workstations?
 Q1.7        Does Cilk run on Windows NT?
 Q1.8        What is Cilkchess?

-------------------------------------------------------------------------------

Question 1.1.  What is Cilk?

Cilk is a language for multithreaded parallel programming based on ANSI C.
Cilk is designed for general-purpose parallel programming, but it is
especially effective for exploiting dynamic, highly asynchronous
parallelism, which can be difficult to write in data-parallel or
message-passing style.  Cilk has been developed since 1994 by the
Supercomputing Technologies Group at the MIT Laboratory for Computer
Science.  Cilk has been used for research, teaching, and for coding
applications such as a virus shell assembly simulator and three chess
programs.

-------------------------------------------------------------------------------

Question 1.2.  How do I obtain Cilk?

Official versions of Cilk can be found at the Cilk web page

We briefly used SourceForge, but they don't know how to stop SPAM, and
eventually gave up.

-------------------------------------------------------------------------------

Question 1.3.  Are there Cilk-related mailing lists?

Yes.  Look for Cilk at SourceForge (www.sourceforge.net).  Three mailing
lists exist:

* <cilk-users@lists.sourceforge.net> is an open discussion list for Cilk
  users.

  However, the Cilk users mailing list is not monitored by the current
  Cilk developers because of spam.  The list is probably useless now.

* <cilk-announce@lists.sourceforge.net> is a read-only, low-traffic
  mailing list where we announce new releases of Cilk.

* Use the <cilk-support@lists.sourceforge.net> mail alias to send mail to
  a restricted set of Cilk developers.

-------------------------------------------------------------------------------

Question 1.4.  Is Cilk free software?

Starting with version 5.3, Cilk is Free Software in the technical sense
defined by the Free Software Foundation (see Categories of Free and
Non-Free Software), and is distributed under the terms of the GNU General
Public License.  Previous versions of Cilk were distributed without fee
for noncommercial use, but were not technically ``free.''

-------------------------------------------------------------------------------

Question 1.5.  Which systems does Cilk run on?

The current Cilk-5.3 system runs on systems that support POSIX threads.
In particular, Cilk has been installed successfully on GNU/Linux, Solaris,
IRIX, Digital Unix, and MacOS X.

Cilk requires certain system software in order to run.  In particular, it
requires a recent gcc, GNU make, and preferably the GNU linker.  GNU/Linux
systems are usually distributed with all these tools.  Cilk should also
work on other systems (*BSD etc.) whenever the appropriate tools are
installed.  If you successfully compile Cilk on these systems, please
contact me <bradley@mit.edu> so that I can update this FAQ.

Cilk-5.3 supports IA-32 (x86), IA-64 (Itanium), AMD64 (x86-64) PowerPC,
SPARC, MIPS, and Alpha processors.  Porting to other processors is not
difficult.  Please contact <cilk-support@lists.sourceforge.net> if you are
interested in running Cilk on other machines.

-------------------------------------------------------------------------------

Question 1.6.  Does Cilk run on networks of workstations?

Cilk-5.3 does not run on distributed-memory machines.  Keith Randall wrote
a distributed-memory variant of Cilk-5.1 as part of his Ph. D. thesis.
See the Cilk web page for a copy of the thesis and for downloading the
distributed-memory Cilk version.  Be warned that this version is
experimental and it has not been updated in a long time.

-------------------------------------------------------------------------------

Question 1.7.  Does Cilk run on Windows NT?

Please do not send questions about Windows NT to the cilk-support mailing
list, because the Cilk maintainer does not know anything about this
system.

-------------------------------------------------------------------------------

Question 1.8.  What is Cilkchess?

Cilkchess is a chess program written in Cilk.  Cilkchess and Cilk are two
distinct things. Cilkchess has never been released, and it is not part of
the Cilk distribution.  For more information about Cilkchess, contact its
author Don Dailey <drd@supertech.lcs.mit.edu>.

===============================================================================

Section 2.  Installing Cilk

 Q2.1        How do I install Cilk?
 Q2.2        How do I install Cilk in a directory different from /usr/local?
 Q2.3        The example programs compile, but they do not run.
 Q2.4        `make' says: ``Warning: Clock skew detected. Your build may be inc

-------------------------------------------------------------------------------

Question 2.1.  How do I install Cilk?

Cilk uses the standard GNU installation tools.  To install Cilk, type
$ ./configure
$ make
$ make check   # run test programs
# make install

-------------------------------------------------------------------------------

Question 2.2.  How do I install Cilk in a directory different from /usr/local?

Type
$ ./configure --prefix=<installation directory>
$ make
# make install

The following commands *do not* work:
$ ./configure
$ make
# make install prefix=<installation directory>  # DOES NOT WORK

-------------------------------------------------------------------------------

Question 2.3.  The example programs compile, but they do not run.

If the example programs do not run, and they complain about libcilk.so not
being found, then Cilk does not know how to hardcode the path to the Cilk
shared library into Cilk programs.  Try one of the following suggestions:

* Try to set the environment variable LD_LIBRARY_PATH to
  <cilk-dir>/runtime/.libs, where  <cilk-dir> is the top-level Cilk-5.3
  directory.

* Try installing Cilk in a standard directory, such as /usr or /usr/local.

* Install the GNU linker.  Cilk knows how to set the correct
  shared-libraries path if the GNU linker is used.

* Disable shared libraries completely, using the command
$ ./configure --disable-shared

-------------------------------------------------------------------------------

Question 2.4.  `make' says: ``Warning: Clock skew detected. Your build may be incomplete''.

This warning occurs on a NFS client whose time is not synchronized with
the NFS server.  The build should be correct nevertheless, but it is a
good idea to adjust the system clock anyway.

===============================================================================

Section 3.  Using Cilk

 Q3.1        How do I compile a Cilk program?
 Q3.2        Cilk seems really slow.
 Q3.3        Can I call Cilk from C/C++/FORTRAN?
 Q3.4        The linker says Cilk_flags_are_wrong_*_please_recompile.

-------------------------------------------------------------------------------

Question 3.1.  How do I compile a Cilk program?

Use the cilkc command in the same way you would use gcc.  For example,
cilkc -O2 program.cilk -o program -lm.

cilkc should accept all gcc options, and in addition it accepts the
following three options.

* -cilk-debug: Enable consistency checks in the Cilk runtime system.

* -cilk-profile: Enable collection of profile information within the Cilk
  runtime system.  You can print this information by invoking a Cilk
  program with the --stats} flag.

* -cilk-critical-path: Enable fine-grain collection of the program
  critical path.  See the Cilk manual for a definition of the critical
  path and an explanation of why you may want to know it.

All files that comprise an executable must be compiled and linked with the
same set of -cilk-* flags.  If not, the linker prints an error message and
fails.

Additional cilkc arguments are documented in the programming manual.

-------------------------------------------------------------------------------

Question 3.2.  Cilk seems really slow.

Normally, a spawn is 2--6 times slower than a function call, but Cilk
becomes much slower when the critical-path measurements are enabled.  This
problem occurs because Cilk reads the system clock at every thread
boundary (i.e. at every spawn, sync, return).  Some systems, such as
Solaris, have fast user-level clock routines, but other systems, such as
Linux, require a system call.  If Cilk programs are still unacceptably
slow (when compared to the C version), please contact
<cilk-support@lists.sourceforge.net>.

-------------------------------------------------------------------------------

Question 3.3.  Can I call Cilk from C/C++/FORTRAN?

Not with Cilk-5.3.  We have an experimental ``library version'' of
Cilk-5.2 which can be called by C, but it was not incorporated into
Cilk-5.3.

-------------------------------------------------------------------------------

Question 3.4.  The linker says Cilk_flags_are_wrong_*_please_recompile.

All Cilk files that comprise your program must be compiled and linked with
the same Cilk flags.  (See Q3.1 `How do I compile a Cilk program?' for a
description of the Cilk flags.)  If the flags differ, the linker issues
and error message like the following:
undefined reference to `Cilk_flags_are_wrong_NODEBUG_NOTIMING_NOSTATS_please_recompile'

