[cfe-commits] r171656 - in /cfe/trunk/docs: FAQ.rst index.rst

[Dmitri Gribenko]

Author: gribozavr
Date: Sun Jan  6 07:38:34 2013
New Revision: 171656

URL: http://llvm.org/viewvc/llvm-project?rev=171656&view=rev
Log:
Clang docs: add some information about the difference between 'clang' and 'clang -cc1'

This is coming up again and again on the mailing list and IRC.

Added:
    cfe/trunk/docs/FAQ.rst
Modified:
    cfe/trunk/docs/index.rst

Added: cfe/trunk/docs/FAQ.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/FAQ.rst?rev=171656&view=auto
==============================================================================
--- cfe/trunk/docs/FAQ.rst (added)
+++ cfe/trunk/docs/FAQ.rst Sun Jan  6 07:38:34 2013
@@ -0,0 +1,52 @@
+================================
+Frequently Asked Questions (FAQ)
+================================
+
+.. contents::
+   :local:
+
+Driver
+======
+
+I run ``clang -cc1 ...`` and get weird errors about missing headers
+-------------------------------------------------------------------
+
+Given this source file:
+
+.. code-block:: c
+
+  #include <stdio.h>
+
+  int main() {
+    printf("Hello world\n");
+  }
+
+
+If you run:
+
+.. code-block:: console
+
+  $ clang -cc1 hello.c
+  hello.c:1:10: fatal error: 'stdio.h' file not found
+  #include <stdio.h>
+           ^
+  1 error generated.
+
+``clang -cc1`` is the frontend, ``clang`` is the :doc:`driver
+<DriverInternals>`.  The driver invokes the frontend with options appropriate
+for your system.  To see these options, run:
+
+.. code-block:: console
+
+  $ clang -### -c hello.c
+
+Some clang command line options are driver-only options, some are frontend-only
+options.  Frontend-only options are intended to be used only by developers.
+Users should not run ``clang -cc1`` directly.
+
+If you want to use a frontend-only option ("a ``-cc1`` option"), for example
+``-ast-dump``, then you need to take the ``clang -cc1`` line generated by the
+driver and add the option you need.  Alternatively, you can run
+``clang -Xclang <option> ...`` to force the driver pass ``<option>`` to
+``clang -cc1``.
+

Modified: cfe/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index.rst?rev=171656&r1=171655&r2=171656&view=diff
==============================================================================
--- cfe/trunk/docs/index.rst (original)
+++ cfe/trunk/docs/index.rst Sun Jan  6 07:38:34 2013
@@ -21,6 +21,7 @@
    AddressSanitizer
    ThreadSanitizer
    MemorySanitizer
+   FAQ
 
 Using Clang as a Library
 ========================