Installation

Compile a Program

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 extension .dll or .so, a shared library is created instead of an executable. The extensions .lib and .a create a static library.

All source files (.cpp, .c, .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 an 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 to the build directory, which can safely be deleted at any time by hand or using the command 'icompile --clean'.

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.

Compile a Library

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'.

Customizing Projects

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 directory!). 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.

Customizing System

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 ~/.icompile can be overridden by individual project ice.txt files.

The default files will work correctly for most projects and changing ~/.icompile and ice.txt is not recommended. It can be hard to debug the compiler and linker errors that result from an improperly configured system.

Command Line

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[0] 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.
iCompile was created by Morgan McGuire with additional programming by
Robert Hunter and Corey Taylor.
       

Linking

• Recognizing specific headers, such as GL.h
• Recognizing specific unresolved symbols such as glBegin
• Known dependencies of other libraries
• The presence of a .dylib or .so in the data-files directory

• The C++ Standard Library
• OpenGL
• Certain LGPL libraries, such as FFMPEG
• Libraries only available in dynamic (.so, .dll, .dylib) format
• Sibling directories ending in .so or .dll that contain an ice.txt file
• Dynamic libraries found in the data-files subdirectory of the current project

How Linking Works

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.

Other Build Tools