From: Chris Lattner Date: Mon, 20 Apr 2009 04:37:38 +0000 (+0000) Subject: slurp some content from the PTH doc into the user's doc. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5c3074f3cd4c33e30c55e851a3ecf21ebec0769e;p=clang slurp some content from the PTH doc into the user's doc. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@69569 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/PTHInternals.html b/docs/PTHInternals.html index 2d2e1e3e1b..832d3b0a97 100644 --- a/docs/PTHInternals.html +++ b/docs/PTHInternals.html @@ -14,74 +14,15 @@
-

Pretokenized Headers

-

Precompiled -headers are a general approach employed by many compilers to reduce -compilation time. The underlying motivation of the approach is that it is -common for the same (and often large) header files to be included by -multiple source files. Consequently, compile times can often be greatly improved -by caching some of the (redundant) work done by a compiler to process headers. -Precompiled header files, which represent one of many ways to implement -this optimization, are literally files that represent an on-disk cache that -contains the vital information necessary to reduce some (or all) of the work -needed to process a corresponding header file. While details of precompiled -headers vary between compilers, precompiled headers have been shown to be a -highly effective at speeding up program compilation on systems with very large -system headers (e.g., Mac OS/X).

+

Pretokenized Headers (PTH)

-

Clang supports an implementation of precompiled headers known as -pre-tokenized headers (PTH). Clang's pre-tokenized headers support most -of same interfaces as GCC's pre-compiled headers (as well as others) but are -completely different in their implementation. This first describes the interface -for using PTH and then briefly elaborates on its design and implementation.

+

This document first describes the low-level +interface for using PTH and then briefly elaborates on its design and +implementation. If you are interested in the end-user view, please see the +User's Manual.

-

Using Pretokenized Headers with clang

- -

The high-level clang driver supports an interface to use PTH files -that is similar to GCC's interface for precompiled headers.

- -

Generating a PTH File

- -

To generate a PTH file using clang, one invokes clang using -the -x <language>-header option. This mirrors the -interface in GCC for generating PCH files:

- -
-  $ gcc -x c-header test.h -o test.h.gch
-  $ clang -x c-header test.h -o test.h.pth
-
- -

Using a PTH File

- -

A PTH file can then be used as a prefix header when a --include option is passed to clang:

- -
-  $ clang -include test.h test.c -o test
-
- -

The clang driver will first check if a PTH file for test.h -is available; if so, the contents of test.h (and the files it includes) -will be processed from the PTH file. Otherwise, clang falls back to -directly processing the content of test.h. This mirrors the behavior of -GCC.

- -

NOTE: clang does not automatically used PTH files -for headers that are directly included within a source file. For example:

- -
-  $ clang -x c-header test.h -o test.h.pth
-  $ cat test.c
-  #include "test.h"
-  $ clang test.c -o test
-
- -

In this example, clang will not automatically use the PTH file for -test.h since test.h was included directly in the source file -and not specified on the command line using -include.

-

Using Pretokenized Headers with clang-cc (Low-level Interface)

The low-level Clang compiler tool, clang-cc, supports three command diff --git a/docs/UsersManual.html b/docs/UsersManual.html index 8f8951f87e..cfed51a202 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -180,6 +180,66 @@ other high level options like -c, -g, etc.

Precompiled Headers

+

Precompiled +headers are a general approach employed by many compilers to reduce +compilation time. The underlying motivation of the approach is that it is +common for the same (and often large) header files to be included by +multiple source files. Consequently, compile times can often be greatly improved +by caching some of the (redundant) work done by a compiler to process headers. +Precompiled header files, which represent one of many ways to implement +this optimization, are literally files that represent an on-disk cache that +contains the vital information necessary to reduce some of the work +needed to process a corresponding header file. While details of precompiled +headers vary between compilers, precompiled headers have been shown to be a +highly effective at speeding up program compilation on systems with very large +system headers (e.g., Mac OS/X).

+ +

Clang supports an implementation of precompiled headers known as +pre-tokenized headers (PTH). Clang's pre-tokenized headers support most +of same interfaces as GCC's pre-compiled headers (as well as others) but are +completely different in their implementation. If you are interested in how +PTH is implemented, please see the PTH Internals + document.

+ +

Generating a PTH File

+ +

To generate a PTH file using Clang, one invokes Clang with +the -x <language>-header option. This mirrors the +interface in GCC for generating PCH files:

+ +
+  $ gcc -x c-header test.h -o test.h.gch
+  $ clang -x c-header test.h -o test.h.pth
+
+ +

Using a PTH File

+ +

A PTH file can then be used as a prefix header when a +-include option is passed to clang:

+ +
+  $ clang -include test.h test.c -o test
+
+ +

The clang driver will first check if a PTH file for test.h +is available; if so, the contents of test.h (and the files it includes) +will be processed from the PTH file. Otherwise, Clang falls back to +directly processing the content of test.h. This mirrors the behavior of +GCC.

+ +

NOTE: Clang does not automatically used PTH files +for headers that are directly included within a source file. For example:

+ +
+  $ clang -x c-header test.h -o test.h.pth
+  $ cat test.c
+  #include "test.h"
+  $ clang test.c -o test
+
+ +

In this example, clang will not automatically use the PTH file for +test.h since test.h was included directly in the source file +and not specified on the command line using -include.