iCompile is a zero-configuration build system that automates the creation of executables, static and shared libraries, and HTML documentation for their source code. iCompile is easy to use. Unlike a Makefile or other build system, it requires no per-project configuration. It finds your source code, dynamically computes dependencies, and infers the correct options for the compiler and linker.
Platforms and features:
Download the latest version of iCompile
from http://ice.sf.net and put
it in a directory (such as
/usr/bin) that is listed in
PATH environment variable.
iCompile is a Python script and requires at least
Python 2.6 to
run. You can check the version of your Python version using the
python -V". If you are running an old
version of Python, iCompile will print the error "
syntax" for the "
If you use any libraries that are not installed in
/usr/include, set the
INCLUDE variables as shown in
the example at the top of this manual, or run iCompile once in an empty directory and
then edit the
that it generates to contain those paths.
iCompile can generate HTML reference documentation for your program automatically by reading your program structure and comments. To do so, you must have Doxygen installed. To use equations within the generated documention you must also install Latex and Ghostscript.
To start a new project, create an empty directory and run iCompile inside it with no arguments. You will be prompted to confirm the creation of the default main.cpp and directories during project creation. You can also run iCompile on an existing project that previously used a different build system. In that case, iCompile will not create any new directories or source files.
iCompile determines how to build your project by examining the
directory structure. The name of the binary executable produced
by the build is the same as the name of the project directory.
If the project directory name has the
.so, a shared
library is created instead of an executable. The
.a create a static
All source files (
.cxx, etc.) in the project directory and its
subdirectories are considered part of the project and will be compiled
during the build. There are exceptions for temp directories and the
like discussed later.
The first time it is run in a directory, iCompile generates
ice.txt file telling the build system that this
is the root of a project and a
Doxygen file for the
documentation generator. All other generated files are written
build directory, which can safely be deleted
at any time by hand or using the
Because the build directory could be deleted, keep any data files that
are part of your program's installation in the special directory named
data-files. These will be copied into the distribution
directory during the build. A sample directory tree for an executable
project is shown below.
A project that builds a static library is in a directory ending with '.lib' or '.a'. Dynamic (shared) library projects are configured in exactly the same manner except the root directory name ends with '.dll' or '.so'.Gray files and directories are automatically generated.
The first time that you build a project,
ice.txt is generated.
This file tells iCompile where the root of your project is (which also
allows it give you a warning if you try to build from the wrong
ice.txt also contains setting information,
like include paths. The default settings are fine for most projects
and you do not need to edit this file.
However, you may want to set per-project paths, compiler options,
and link libraries. To do this, open
ice.txt in any text
editor. The comments in the file explain what each of the settings is
for and how to modify them. If you corrupt the file you can delete
it and iCompile will generate a new one for you.
The first time you run iCompile, the file
~/.icompile is generated.
This file specifies the default compiler, paths, and some optional
behavior like beeping after compilation succeeds. The file contains
comments explaining each option. Settings in
can be overridden by individual project
The default files will work correctly for most projects and
ice.txt is not
recommended. It can be hard to debug the compiler and linker errors
that result from an improperly configured system.
iCompile: the zero-configuration build system icompile [--doc] [--opt | --debug] [--clean] [--version] [--config
] [--verbosity n] [--help] [--noprompt [--template <tname>]] [--info] [--deploy | --run | --gdb ] iCompile can build most C++ projects without options or manual configuration. Just type 'icompile' with no arguments. Run in an empty directory to generate a set of starter files. Options: --config <file> Use <file> instead of ~/.icompile as the user configuration file. This allows you to build certain projects with a different compiler or include paths without changing the project ice.txt file, e.g., when installing a 3rd party library --debug (Default) Create a debug executable (define _DEBUG, disable optimizations). --deploy Create a distributable application in the build directory. This should only be used for GUI applications, not command-line tools. Changes the target default to --opt. OS X Specific: data-files/icons.icns will automatically become the application icon. Your program will launch with Applications as the current working directory. Look at argv to change to the directory of your project. --doc Generate documentation before building. --gdb Run the program under gdb if compilation succeeds, passing all further arguments (...) to the program. gdb will look in the directories in the ICE_EXTRA_SOURCE environment variable for library and other source files, in addition to the ones from your program. You can also just run gdb yourself after using iCompile. --info Read configuration files and command line options, but instead of building, print out information about where the generated file will go. --noprompt Run even if there is no ice.txt file, don't prompt the user for input. This is handy for launching iCompile from automated build shell scripts. If --template is specified as well, a default set of files will be built. The only legal templates are 'hello', 'G3D', 'tinyG3D', and 'empty' (default). --opt or -O Generate an optimized executable. --run Run the program if compilation succeeds, passing all further arguments (...) to the program. --verbosity n Change the amount of information printed by icompile n | Result ----|--------------------------------------------------- 0 | Quiet: Only errors and prompts are displayed. | 1 | Normal (Default): Filenames and progress information | are also displayed 2 | Verbose: Executed commands are also displayed | 3 | Trace: Additional debugging information is also | displayed. Exclusive options: --help Print this information. --clean Delete all generated files (but not library generated files). --version Print the version number of iCompile. Special file and directory names: build Output directory data-files Files that will be needed at runtime doc-files Files needed by your documentation (Doxygen output) tmp Object files are put here icon.* Becomes the program icon on OS X iCompile will not look for source files in directories matching: ['^\\.', '^#', '~$', '^\\.svn$', '^\\.git$', '^CVS$', '^Debug$', '^Release$', '^graveyard$', '^tmp$', '^temp$', '^\\.icompile-temp$', '^\\.ice-tmp$', '^build$'] Generated file ice-stats.csv contains a history of the size of your files at compilation times that is interesting for tracking development progress. For convenience, if run from the source or data-files directory, iCompile will automatically step up to the parent directory before compilation. Edit ice.txt and ~/.icompile if your project has specific configuration needs. See manual.html or http://ice.sf.net for full information. iCompile was created by Morgan McGuire with additional programming by Robert Hunter and Corey Taylor.
.dylibon OS X, it copies the
.dylibfile to the
builddirectory and rebases it using
install_name_toolso that the distribution will work on any computer--except for
libpthread.dylib, which is unstable when rebased. The following section gives a more detailed overview of linking.
Libraries can be linked statically or dynamically. Dynamic libraries are loaded at runtime. The primary drawback of dynamic libraries is that the process for loading them is fragile. If they cannot be found at runtime, or the wrong version is found, then the program will malfunction or crash. Both of these can happen due to incorrectly configured end-user machines and are fairly common problems. iCompile prefers static linking because it leaves you with an executable that is more likely to work on a different computer.
.a(Unix archive) or
.lib(Windows static library) files are statically linked. The path to the library must be known to iCompile at compile time. It most commonly appears in the
LIBRARYenvironment variable but iCompile will also look in
LD_LIBRARY_PATH, the project directory, and sibling directories (if they are libraries). The names of archives on Unix must begin with "
.so(Unix shared object) files are dynamically linked. The files must be present at runtime. The path to the file is embedded in the executable that loads them, making them machine specific, although it is possible to embed a relative path. See the Unix
.dll(Windows dynamic link library) files are dynamically linked. They are always accompanied by a small .lib file that is statically linked and manages the runtime process. At runtime, Windows looks for the .dlls in locations specified by the
PATHenvironment variable. iCompile does not currently support Windows.
.dylib (OS X dynamic library) files are dynamically
linked, but are also needed at compile time for a preliminary
static linking process. Both the
.dylib and the executable that
uses it embed the path to the
These files are also known as "frameworks" when they are stored within
a specific directory structure.
See also OS X Application Linking and
Some libraries, such as OpenGL, can't be statically linked because they are designed to be loaded like a plugin that provides different implementations on different machines. LGPL libraries like FFMPEG are dynamically linked because that is required by the LGPL (the alternative is releasing all of your own source code.)
The standard library is also dynamically linked. This is necessary so that other dynamically linked libraries will allocate memory in the same memory space. Your program will only work if the user has installed these libraries and set their LD_LIBRARY_PATH to point to them or updated /etc/ld.so.conf. You can see what dynamic libraries an executable needs with the Unix command "ldd".