Add a section about clang-cl to UsersManual.rst

Differential Revision: http://llvm-reviews.chandlerc.com/D1881

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@192337 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 108 insertions, 0 deletions

diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index 9e5b8877e2..37eb10c621 100644
--- a/docs/UsersManual.rst
+++ b/docs/UsersManual.rst
@@ -44,6 +44,8 @@ as to improve functionality through Clang-specific features. The Clang
 driver and language features are intentionally designed to be as
 compatible with the GNU GCC compiler as reasonably possible, easing
 migration from GCC to Clang. In most cases, code "just works".
+Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
+to be compatible with the Visual C++ compiler, cl.exe.
 
 In addition to language specific features, Clang has a variety of
 features that depend on what CPU architecture or operating system is
@@ -1403,3 +1405,109 @@ Clang expects the GCC executable "gcc.exe" compiled for
 
 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
 ``x86_64-w64-mingw32``.
+
+.. _clang-cl:
+
+clang-cl
+========
+
+clang-cl is an alternative command-line interface to Clang driver, designed for
+compatibility with the Visual C++ compiler, cl.exe.
+
+To enable clang-cl to find system headers, libraries, and the linker when run
+from the command-line, it should be executed inside a Visual Studio Native Tools
+Command Prompt or a regular Command Prompt where the environment has been set
+up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
+
+clang-cl can also be used from inside Visual Studio  by using an LLVM Platform
+Toolset.
+
+Command-Line Options
+--------------------
+
+To be compatible with cl.exe, clang-cl supports most of the same command-line
+options. Those options can start with either ``/`` or ``-``. It also supports
+some of Clang's core options, such as the ``-W`` options.
+
+Options that are known to clang-cl, but not currently supported, are ignored
+with a warning. For example:
+
+  ::
+
+    clang-cl.exe: warning: argument unused during compilation: '/Zi'
+
+To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
+
+Options that are not known to clang-cl will cause errors. If they are spelled with a
+leading ``/``, they will be mistaken for a filename:
+
+  ::
+
+    clang-cl.exe: error: no such file or directory: '/foobar'
+
+Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
+for any valid cl.exe flags that clang-cl does not understand.
+
+Execute ``clang-cl /?`` to see a list of supported options:
+
+  ::
+
+    /?                     Display available options
+    /c                     Compile only
+    /D <macro[=value]>     Define macro
+    /fallback              Fall back to cl.exe if clang-cl fails to compile
+    /Fe<file or directory> Set output executable file or directory (ends in / or \)
+    /FI<value>             Include file before parsing
+    /Fo<file or directory> Set output object file, or directory (ends in / or \)
+    /GF-                   Disable string pooling
+    /GR-                   Disable RTTI
+    /GR                    Enable RTTI
+    /help                  Display available options
+    /I <dir>               Add directory to include search path
+    /J                     Make char type unsigned
+    /LDd                   Create debug DLL
+    /LD                    Create DLL
+    /link <options>        Forward options to the linker
+    /MDd                   Use DLL debug run-time
+    /MD                    Use DLL run-time
+    /MTd                   Use static debug run-time
+    /MT                    Use static run-time
+    /Ob0                   Disable inlining
+    /Od                    Disable optimization
+    /Oi-                   Disable use of builtin functions
+    /Oi                    Enable use of builtin functions
+    /Os                    Optimize for size
+    /Ot                    Optimize for speed
+    /Ox                    Maximum optimization
+    /Oy-                   Disable frame pointer omission
+    /Oy                    Enable frame pointer omission
+    /O<n>                  Optimization level
+    /P                     Only run the preprocessor
+    /showIncludes          Print info about included files to stderr
+    /TC                    Treat all source files as C
+    /Tc <filename>         Specify a C source file
+    /TP                    Treat all source files as C++
+    /Tp <filename>         Specify a C++ source file
+    /U <macro>             Undefine macro
+    /W0                    Disable all warnings
+    /W1                    Enable -Wall
+    /W2                    Enable -Wall
+    /W3                    Enable -Wall
+    /W4                    Enable -Wall
+    /Wall                  Enable -Wall
+    /WX-                   Do not treat warnings as errors
+    /WX                    Treat warnings as errors
+    /w                     Disable all warnings
+    /Zs                    Syntax-check only
+
+The /fallback Option
+^^^^^^^^^^^^^^^^^^^^
+
+When clang-cl is run with the ``/fallback`` option, it will first try to
+compile files itself. For any file that it fails to compile, it will fall back
+and try to compile the file by invoking cl.exe.
+
+This option is intended to be used as a temporary means to build projects where
+clang-cl cannot successfully compile all the files. clang-cl may fail to compile
+a file either because it cannot generate code for some C++ feature, or because
+it cannot parse some Microsoft language extension.