[cfe-dev] Tips for optimising libclang

Miguel Guedes miguel.a.guedes at gmail.com
Wed Apr 3 22:20:56 PDT 2013

On Wed, 2013-04-03 at 14:30 -0400, Sean Silva wrote:
> Can you suggest a specific improvement to the documentation that would
> help avoid this issue in the future?

Well, I find that a difficult question to answer because my mother
tongue isn't English and so you could argue that the documentation is
clear enough and it was I who failed to understand it.

However, my personal opinion is that indeed it could do with some
improvements designed to remove (what I think are) ambiguities and to
make it easier for users who lack in-depth knowledge of clang, libclang
or compiler technologies in general, as is my case, to use (lib)clang
and develop. My personal opinion is the clearer the documentation is the
less noise (like this very thread) the core cfe-devs would (perhaps) get
in this mailing list; noise, which I'm sure is annoying - it took me
awhile before I finally convinced myself I should post here.

As requested, here's a few suggestions based on my (most) limited
knowledge of libclang:

* Creation of precompiled preamble

  There's no mention in the documentation about the issue that Tobias
raised in this thread; that the preamble is only created after the TU is
parsed a second time. IOW, the documentation should make it clear that
one must issue clang_parseTranslationUnit, followed by
clang_reparseTranslationUnit to ensure the preamble is created.

  BTW, no one has commented on whether this is a bug or a feature. I
take it it's the former?
* clang_reparseTranslationUnit

  The documentation doesn't make it clear that the TU is re-created (or
something to that effect) when reparsing a source file in which
preprocessor directives have been modified or added, which results in
parsing times identical to the time it takes to create the TU (first

* Code completion

  The documentation for the TU parameter of clang_codeCompleteAt states
that the "source files for this translation unit need not be completely
up-to-date (and the contents of those source files may be overridden via
unsaved_files)". As I stated at the start of my reply, English isn't my
first language, and so I may be at fault here. But it does seem like an
ambiguous statement as it doesn't explicitly state that in the case when
the source files have been edited since the last TU parse, the TU
doesn't need to be reparsed. Also, what happens if a preprocessor
directive has been added/modified in the source file in question and how
does that affect code completion?

* `Code' as a second language 

  I think most people would agree that `code' is a programmers' second
language (if not first in some cases!). Why not complement the
documentation with more code examples to reinforce the textual
description? While I have come across some snippets of code in the
documentation, I believe certain core aspects of (lib)clang that lack
code examples would greatly benefit from them. This measure should
further help iron out whatever ambiguities linger in the text as well as
make it easier for non English speakers to understand the documentation.

Should the above prove useful in any way, I would be more than willing
to help in any way.


More information about the cfe-dev mailing list