X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=README.txt;h=1982c6ad29c1723e7e65256337a598d66cd1937d;hb=eab819b41d64ab9624030437ca289cf864ba9f77;hp=9ec1cc4a3d531877fe0cdde925a28d8cc89c6d09;hpb=5f016e2cb5d11daeb237544de1c5d59f20fe1a6e;p=clang diff --git a/README.txt b/README.txt index 9ec1cc4a3d..1982c6ad29 100644 --- a/README.txt +++ b/README.txt @@ -23,41 +23,61 @@ I. Introduction: carefully designed as the following components: libsupport - Basic support library, reused from LLVM. + libsystem - System abstraction library, reused from LLVM. libbasic - Diagnostics, SourceLocations, SourceBuffer abstraction, file system caching for input source files. This depends on libsupport and libsystem. + libast - Provides classes to represent the C AST, the C type system, builtin functions, and various helpers for analyzing and manipulating the AST (visitors, pretty printers, etc). This library depends on libbasic. - + + liblex - C/C++/ObjC lexing and preprocessing, identifier hash table, pragma handling, tokens, and macros. This depends on libbasic. + libparse - C (for now) parsing and local semantic analysis. This library invokes coarse-grained 'Actions' provided by the client to do stuff (e.g. libsema builds ASTs). This depends on liblex. + libsema - Provides a set of parser actions to build a standardized AST for programs. AST's are 'streamed' out a top-level declaration at a time, allowing clients to use decl-at-a-time processing, build up entire translation units, or even build 'whole program' ASTs depending on how they use the APIs. This depends on libast and libparse. - + + librewrite - Fast, scalable rewriting of source code. This operates on + the raw syntactic text of source code, allowing a client + to insert and delete text in very large source files using + the same source location information embedded in ASTs. This + is intended to be a low-level API that is useful for + higher-level clients and libraries such as code refactoring. + + libanalysis - Source-level dataflow analysis useful for performing analyses + such as computing live variables. It also includes a + path-sensitive "graph-reachability" engine for writing + analyses that reason about different possible paths of + execution through source code. This is currently being + employed to write a set of checks for finding bugs in software. + libcodegen - Lower the AST to LLVM IR for optimization & codegen. Depends on libast. + clang - An example driver, client of the libraries at various levels. This depends on all these libraries, and on LLVM VMCore. - This front-end has been intentionally built as a DAG, making it easy to - reuse individual parts or replace pieces if desired. For example, to build a - preprocessor, you take the Basic and Lexer libraries. If you want an indexer, - you take those plus the Parser library and provide some actions for indexing. - If you want a refactoring, static analysis, or source-to-source compiler tool, - it makes sense to take those plus the AST building and semantic analyzer - library. Finally, if you want to use this with the LLVM backend, you'd take - these components plus the AST to LLVM lowering code. + This front-end has been intentionally built as a DAG of libraries, making it + easy to reuse individual parts or replace pieces if desired. For example, to + build a preprocessor, you take the Basic and Lexer libraries. If you want an + indexer, you take those plus the Parser library and provide some actions for + indexing. If you want a refactoring, static analysis, or source-to-source + compiler tool, it makes sense to take those plus the AST building and semantic + analyzer library. Finally, if you want to use this with the LLVM backend, + you'd take these components plus the AST to LLVM lowering code. In the future I hope this toolkit will grow to include new and interesting components, including a C++ front-end, ObjC support, and a whole lot of other @@ -77,28 +97,36 @@ II. Usage of clang driver: - To make diagnostics more gcc-like: -fno-caret-diagnostics -fno-show-column - Enable metric printing: -stats - * -fsyntax-only is the default mode. - - * -E mode gives output nearly identical to GCC, though not all bugs in - whitespace calculation have been emulated (e.g. the number of blank lines - emitted). + * -fsyntax-only is currently the default mode. - * -fsyntax-only is currently partially implemented, lacking some semantic - analysis. + * -E mode works the same way as GCC. - * -Eonly mode does all preprocessing, but does not print the output, useful for - timing the preprocessor. + * -Eonly mode does all preprocessing, but does not print the output, + useful for timing the preprocessor. - * -parse-print-callbacks prints almost no callbacks so far. + * -fsyntax-only is currently partially implemented, lacking some + semantic analysis (some errors and warnings are not produced). + + * -parse-noop parses code without building an AST. This is useful + for timing the cost of the parser without including AST building + time. - * -parse-ast builds ASTs, but doesn't print them. This is most useful for - timing AST building vs -parse-noop. + * -parse-ast builds ASTs, but doesn't print them. This is most + useful for timing AST building vs -parse-noop. - * -parse-ast-print prints most expression and statements nodes, but some - minor things are missing. + * -parse-ast-print pretty prints most expression and statements nodes. + + * -parse-ast-check checks that diagnostic messages that are expected + are reported and that those which are reported are expected. + + * -dump-cfg builds ASTs and then CFGs. CFGs are then pretty-printed. + + * -view-cfg builds ASTs and then CFGs. CFGs are then visualized by + invoking Graphviz. + + For more information on getting Graphviz to work with clang/LLVM, + see: http://llvm.org/docs/ProgrammersManual.html#ViewGraph - * -parse-ast-check checks that diagnostic messages that are expected are - reported and that those which are reported are expected. III. Current advantages over GCC: @@ -128,15 +156,16 @@ Potential Future Features: * Fast #import with a module system. * Dependency tracking: change to header file doesn't recompile every function that texually depends on it: recompile only those functions that need it. + This is aka 'incremental parsing'. IV. Missing Functionality / Improvements clang driver: - * Include search paths are hard-coded into the driver. + * Include search paths are hard-coded into the driver. Doh. File Manager: - * Reduce syscalls, see NOTES.txt. + * Reduce syscalls for reduced compile time, see NOTES.txt. Lexer: * Source character mapping. GCC supports ASCII and UTF-8. @@ -156,16 +185,14 @@ Preprocessor: * Add support for -M* Traditional Preprocessor: - * All. + * Currently, we have none. :) Parser: * C90/K&R modes are only partially implemented. - * __extension__, __attribute__ [currently just skipped and ignored]. - * "initializers", GCC inline asm. + * __extension__ is currently just skipped and ignored. Semantic Analysis: - * Perhaps 75% done. - -Code Gen: - * Mostly missing. + * Perhaps 85% done. +LLVM Code Gen: + * Most of the easy stuff is done, probably 65.42% done so far.