Compilation guide updates: OS X, Clang/LLVM, MinGW

doc/doxygen/Doxyfile

@@ -623,7 +623,7 @@ INPUT_ENCODING         = UTF-8
 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
 # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
 
-FILE_PATTERNS          = *.h *.cpp *.txt
+FILE_PATTERNS          = *.h *.cpp *.txt *.dox
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.
@@ -635,7 +635,7 @@ RECURSIVE              = YES
 # excluded from the INPUT source files. This way you can easily exclude a
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                = 
+EXCLUDE                =
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
 # directories that are symbolic links (a Unix filesystem feature) are excluded
@@ -1300,7 +1300,7 @@ MACRO_EXPANSION        = YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = YES 
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # in the INCLUDE_PATH (see below) will be search if a #include is found.

doc/doxygen/build.dox

@@ -8,7 +8,11 @@ This guide contains instructions for compiling Cantera on the following operatin
     - Ubuntu 10.04 LTS (Lucid Lynx) or newer
     - Debian 5.0 (Lenny) or newer
 - Windows Vista or Windows 7 (32-bit or 64-bit versions)
-- [planned] OS X 10.6 (Snow Leopard) or newer
+- OS X 10.6 (Snow Leopard) or newer
+
+In addition to the above operating systems, Cantera should work on any
+Unix-like system where the necessary prerequisites are available, but some
+additional configuration may be required.
 
 \section prereqs Installation Prerequisites
 
@@ -52,12 +56,28 @@ build and what architecture (32-bit or 64-bit) you want to use.
   python setup.py install \endverbatim
 - It is generally helpful to have SCons and Python in your PATH. This
   can usually be accomplished by adding the top-level Python directory
-  (e.g. C:\Python27) to your PATH. This is acccessible from:
+  (e.g. C:\Python27) to your PATH. This is accessible from:
   \verbatim
    Control Panel > System and Security > System > Advanced System Settings > Environment Variables \endverbatim
 
 \subsection osx OS X
-Cantera's build system has not yet been tested on OS X.
+- Download and install Xcode from the Apple Developer site:
+  \verbatim
+  https://developer.apple.com/xcode/index.php \endverbatim
+- Cantera can be compiled with the command line tools that ship with either
+  Xcode 3.x or Xcode 4.x.
+- If you don't have numpy version >= 1.3, you can install a recent version with:
+  \verbatim
+  sudo easy_install -U numpy \endverbatim
+- If you want to build Cantera with Fortran 90 support, download gfortran from:
+  \verbatim
+  http://gcc.gnu.org/wiki/GFortranBinaries#MacOS \endverbatim
+- Download scons-2.1.0.tar.gz from scons.org and extract the contents. Install with either
+  \verbatim
+  sudo python setup.py install \endverbatim
+  to install for all users, or
+  \verbatim
+  python setup.py install --user \endverbatim
 
 \section download-cantera Download the Cantera source code
 
@@ -96,7 +116,7 @@ Cantera's build system has not yet been tested on OS X.
 
 \see \ref configCantera
 
-\subsection Windows
+\subsection Windows (MSVC)
 - In Windows there aren’t any proper default locations for many of the
   packages that Cantera depends on, so you will need to specify these
   paths explicitly.
@@ -112,7 +132,33 @@ Cantera's build system has not yet been tested on OS X.
   you’re building the 64-bit toolbox, the correct option will be
   something like:
   \verbatim
-   matlab_cmd="C:/Program Files/MATLAB/R2009a/bin/win64/MATLAB.exe" \endverbatim
+  matlab_cmd="C:/Program Files/MATLAB/R2009a/bin/win64/MATLAB.exe" \endverbatim
+
+\subsection Windows (MinGW)
+- To compile with MinGW, use the SCons command line option:
+  \verbatim
+  toolchain=mingw \endverbatim
+- The version of MinGW from www.mingw.org is 32-bit only, and therefore
+  cannot be used to build a 64-bit Python module.
+- MinGW cannot be used to build the Matlab toolbox because the "mex -setup"
+  command does not recognize MinGW.
+
+\subsection config-osx OS X
+
+- The available compilers to compile Cantera will depend on the version
+  of Xcode that is installed.
+  - If Xcode 3 is installed, you can use either GCC by leaving the
+    \b CC and \b CXX options unspecified, or setting them to
+    \verbatim
+    CC=gcc CXX=g++ \endverbatim
+    You can also use LLVM with the GCC frontend by specifying
+    \verbatim
+    CC=llvm-gcc CXX=llvm-g++ \endverbatim
+  - If Xcode 4 is installed, then you can either use LLVM-GCC as above
+    or Clang by specifying:
+    \verbatim
+    CC=clang CXX=clang++ \endverbatim
+
 
 \section compile-test Compile Cantera & Test
 - Run scons with the list of desired configuration options, e.g.:
@@ -121,7 +167,7 @@ Cantera's build system has not yet been tested on OS X.
 - If Cantera compiles successfully, you should see the message:
   \verbatim
   **************************************************************
-  Compiliation complete. Type '[sudo] scons install' to install.
+  Compilation complete. Type '[sudo] scons install' to install.
   ************************************************************** \endverbatim
 - If you do not see this message, check the output for errors to see
   what went wrong.
@@ -137,6 +183,20 @@ Cantera's build system has not yet been tested on OS X.
     - Messages printed to the console while running scons test
     - Output files generated by the tests
 
+\subsection compile-mingw MinGW Compilation problems
+
+- If you get a compiler error while compiling some of the "f2c" code, then
+  your version of MinGW has a problem with the order of its internal include
+  paths, such that it sees the GCC float.h before its own special version. To
+  fix this problem edit the GCC float.h located at (roughly):
+  \verbatim
+  c:\MinGW\lib\gcc\mingw32\4.6.1\include\float.h \endverbatim
+  and add the following just before the end (before the final #endif):
+  \verbatim
+#ifndef _MINGW_FLOAT_H_
+#include_next <float.h>
+#endif \endverbatim
+
 \section software-sources Sources and versions of software used by Cantera:
 
 You must have one of the following C++ compilers installed on your
@@ -145,6 +205,9 @@ from a Fortran program.
 
 - GNU compilers (C/C++/Fortran)
     - Known to work with version 4.6; Expected to work with version >= 4.3
+- Clang/LLVM (C/C++)
+    - Known to work with version 2.9
+    - This is the version included with Apple Xcode 4.x
 - Intel compilers (C/C++/Fortran)
     - Known to work with version 11.0; Expected to work with versions >= 11.0
 - Microsoft compilers (C/C++)
@@ -152,9 +215,11 @@ from a Fortran program.
       This is equivalent to Visual Studio 2008. It is a free download.
     - Known to work with version 9.0 (Visual Studio 2008) and version 10.0 (Visual Studio 2010).
 - MinGW (C/C++/Fortran)
-    - Supported versions of MinGW be the same as the supported versions of GCC
+    - http://www.mingw.org
+    - Known to work with version 4.6.
+    - Supported versions of MinGW should be the same as the supported versions of GCC
 
-Other Required software:
+\subsection software-other Other Required software:
 
 - Subversion
     - For Windows: http://tortoisesvn.net/downloads.html
@@ -169,12 +234,13 @@ Other Required software:
     - http://www.boost.org/users/download/
     - Known to work with version 1.46; Expected to work with versions >= 1.40
 
-Optional Programs
+\subsection software-optional Optional Programs
 
 - Numpy
     - Required to build the Cantera Python module.
     - http://sourceforge.net/projects/numpy/
     - Known to work with versions 1.3 and 1.5; Expected to work with version >= 1.1
+    - Test suite requires version >= 1.3
 - Matlab
     - Required to build the Cantera Matlab toolbox.
     - Known to work with 2009a, 2010a, and 2011b. Expected to work with versions >= 2009a.