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

[Jordan Rose]

This is good to have. I think we should explain the word "frontend" as well; a user of clang who doesn't know how it interacts with LLVM wouldn't understand that term.

(Actually, given that all of LLVM is statically linked into the clang binary, clang -cc1 is not just an LLVM frontend from the user perspective...)

Jordan


On Jan 6, 2013, at 5:38 , Dmitri Gribenko <gribozavr at gmail.com> wrote:

> 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
> ========================
> 
> 
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130107/80055c0e/attachment.html>