CMake/README

WELCOME TO CROSS-PLATFORM MAKE (CMake)
-------------------------------------

CMake is a cross-platform, extensible build environment. It currently
generates Unix makefiles and Microsoft Visual C++ projects/workspaces. Other
OS/compiler targets are being added to this open-source system, and you can
add your own, if desired.

To use CMake, create CMakeLists.txt in each directory that makes up your
source repository. The CMakeLists.txt file contains commands. Each command
does something different, like defining a list of source code, include
directories, makefile targets, rules, etc. Once CMake has processed all the
commands in all the CMakeLists.txt files, it generates the appropriate
"makefile(s)" for the system/compiler that you are on.

CMake Commands
--------------

The key to using CMake is to learn the commands. Each command has the 
same format:

    NAME_OF_COMMAND(args....)

where args is a white-space separated listed of arguments. (Arguments 
containing spaces should be quoted). For example:

    INCLUDE_DIRECTORIES(./ d:/include "c:/Program Files/include")

note that Unix-style slashes are used. The commands may reference CMake
variables, either built-in or defined variables. Two important variables
are built-in to CMake:

    CMAKE_SOURCE_DIR - The root directory of the source code 
                       directory tree.

    CMAKE_BINARY_DIR - The root directory of the build tree 
                       where binaries are placed. This includes 
                       object files, libraries, and executables.

A rule might reference these as follows:

    INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR})

using the ${} delimiters.
        
Here is a list of current commands. You may also wish to view
the Doxygen documentation (if available) or generate it with
the doxygen.config file in this directory.

Rules: (Generated with cmDumpDocumentation.cxx)
------------------------------------------

    ABSTRACT_FILES - A list of abstract classes, useful for wrappers.
    Usage: ABSTRACT_FILES(file1 file2 ..)

    ADD_TARGET - Add an extra target to the build system.
    Usage: ADD_TARGET(Name "command to run")

    AUX_SOURCE_DIRECTORY - Add all the source files found in the specified
    directory to the build.
    Usage: AUX_SOURCE_DIRECTORY(dir)

    EXECUTABLES - Add a list of executables files.
    Usage: EXECUTABLES(file1 file2 ...)

    FIND_INCLUDE - Find an include path.
    Usage: FIND_INCLUDE(DEFINE try1 try2 ...)

    FIND_LIBRARY - Find a library.
    Usage: FIND_LIBRARY(DEFINE try1 try2)

    FIND_PROGRARM - Find an executable program.
    Usage: FIND_PROGRAM(NAME executable1 executable2 ...)

    INCLUDE_DIRECTORIES - Add include directories to the build.
    Usage: INCLUDE_DIRECTORIES(dir1 dir2 ...)

    LIBRARY - Set a name for a library.
    Usage: LIBRARY(libraryname)

    LINK_DIRECTORIES - Specify link directories.
    Usage: Specify the paths to the libraries that will be linked in.
    LINK_DIRECTORIES(directory1 directory2 ...)
    The directories can use built in definitions like 
    CMAKE_BINARY_DIR and CMAKE_SOURCE_DIR.

    LINK_LIBRARIES - Specify a list of libraries to be linked into executables 
    or shared objects.
    Usage: LINK_LIBRARIES(library1 library2)
    Specify a list of libraries to be linked into
    executables or shared objects.  This command is passed
    down to all other commands. The library name should be
    the same as the name used in the LIBRARY(library) command.

    PROJECT - Set a name for the entire project. One argument.
    Usage: PROJECT(projectname)

    SOURCE_FILES - Add a list of source files.
    Usage: SOURCE_FILES(file1 file2 ...)

    SOURCE_FILES_REQUIRE - Add a list of source files if the required 
    variables are set.
    Usage: SOURCE_FILES_REQUIRE(var1 var2 ... SOURCES_BEGIN file1 file2 ...)

    SUBDIRS - Add a list of subdirectories to the build.
    Usage: SUBDIRS(dir1 dir2 ...)
    Add a list of subdirectories to the build.
    This will cause any CMakeLists.txt files in the sub directories
    to be processed by CMake.

    TESTS - Add a list of executables files that are run as tests.
    Usage: TESTS(file1 file2 ...)

    UNIX_DEFINES - Add -D flags to the command line for Unix only.
    Usage: UNIX_DEFINES(-DFOO -DBAR)
    Add -D flags to the command line for Unix only.

    UNIX_LIBRARIES - Add libraries that are only used for Unix programs.
    Usage: UNIX_LIBRARIES(library -lm ...)

    WIN32_DEFINES - Add -D define flags to command line for Win32 environments.
    Usage: WIN32_DEFINES(-DFOO -DBAR ...)
    Add -D define flags to command line for Win32 environments.

    WIN32_LIBRARIES - Add libraries that are only used for Win32 programs.
    Usage: WIN32_LIBRARIES(library -lm ...)


USING / BUILDING WITH CMAKE
---------------------------

Windows:
-------
These programs are used to drive CMake on Windows:

    CMakeSetup.exe      -> window MFC based GUI for configure on windows

    CMakeSetupCMD.exe   -> windows command line version of CMakeConfigure

To build a project on Windows:

    load CMake/Source/CMakeSetup.dsw
    Build it
    Run it
    Specify paths (i.e., CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR)

    Load (project).dsw (the PROJECT(project) command specified the name)
    Build the appropriate workspaces wihin the project.


Unix:
----
These programs/files are used to drive CMake on Unix:

    configure             -> run on unix to configure for build
    CMakeBuildTargets     -> Unix program to read CMakeLists.txt and 
                             generate CMakeTargets.make

    makefile fragments:
    CMakeMaster.make      -> main file to be included by makefiles
    CMakeVariables.make   -> all make varibles are set in this file
    CMakeRules.make       -> All build rules are here (except Simple Rules)
    CMakeSimpleRules.make -> simple build rules for .o to .cxx, this is 
                             separate to be able to build CMakeBuildTargets 
                             itself.
    CMakeLocal.make       -> Place for hand configuration
    CMakeTargets.make     -> generated rules for make style build in each 
                             directory
    MakefileTemplate.make -> master makefile template used by configure to 
                             generate Makefiles


Unix install:
In-place builds (object files end up in source code directory):

    ./configure
    make

Other-directory builds (object files are in another directory, and
assuming that the source code is in ./project and the following
procedure is performed starting in directory ./):

    mkdir project-build (project is the name of your project)
    cd project-build
    ../project/configure
    make


ADDING COMMANDS
---------------
Rules can be added to CMake by deriving new commands from the class cmCommand 
(defined in CMake/Source/cmCommand.h/.cxx).


ADDING MAKEFILE SUPPORT
-----------------------
Different types of makefiles (corresponding to a different compiler and/or
operating system) can be added by subclassing from cmMakefileGenerator 
(defined in cmMakefileGenerator.h/.cxx). Makefile generators process the 
information defined by the commands in CMakeLists.txt to generate the 
appropriate makefile(s).


FOR MORE INFORMATION
--------------------
Contact Bill Hoffman bill.hoffman@kitware.com (principal developer)
or Will Schroeder will.schroeder@kitware.com (documentation grunt).