[cfe-dev] Proposal: libclang code generation

[Gregory Szorc]

On 12/14/2011 7:17 AM, Douglas Gregor wrote:
> On Dec 13, 2011, at 8:34 PM, Gregory Szorc wrote:
>> That being said, I feel that having a higher-level compiler API 
>> that bypasses (or at least abstracts) the translation unit bit 
>> would be more user friendly (not to mention loosely coupled). For 
>> example, consumers would only need to inspect the result of 1 
>> "process input" function as opposed to 2 (the diagnostics 
>> examination is the heavy bit).
> 
> The small number of consumers that only care about going directly 
> from source to generated code

How can you assert knowledge of the number of consumers of a feature
that isn't available yet? I can think of plenty of use cases for people
wanting to go directly from source to generated code, hence why I
proposed a *supplemental* API that does just that.

> but this API doesn't allow any flexibility for people who want to
> inspect the translation unit and later generate code from it.

Correct. If they need to inspect the TU, they can always use the source
-> TU + TU -> generated code APIs instead of the higher-level source ->
generated code one.

> I'd rather not have this source -> generated code function at all.
> It's not sufficient for a significant number of use cases (which will
> need TU -> generated code),

No functionality will be precluded by the existence of this API. See above.

> will be redundant with the more general TU -> generated code version

Correct.

> and saves a total of 1 line of code for those use cases that don't care about the TU.

No, it saves more than 1 line since

> Consumers should be inspecting diagnostic output after parsing and 
> before generating code *anyway*, since codegen will unceremoniously 
> fail if there are any errors in the AST.

I argue that any assistance you can give in the form of
easier-to-consume APIs will be appreciated (especially in the land of C).

Unless my argument rebutting had any convincing effect, I'll just
recognize there is no interest for this higher-level source -> generated
code API and will remove it from the proposal. I do feel that consumers
will independently implement this utility API themselves, adding
justification for its existence in libclang. Time will tell.

> Writing to stderr (when not under some kind of debugging setting) 
> would be a bug in libclang regardless. What are you referring to, 
> specifically?

I was initially referring to
CIndex.cpp:clang_parseTranslationUnit_Impl(). However, upon further
inspection it appears this is conditional on
CIndexer->getDisplayDiagnostics(), so my claim is wrong.

>> clang_compileTranslationUnit() would also work if we're sticking to
>> the monolithic module approach.
> 
> I don't know what you mean by 'monolithic'

I'm trying to ascertain what the vision for the composition of libclang
is in terms of naming and "modularity." Currently, everything is defined
in one "monolithic" header (Index.h) and exists in a single C naming
"namespace" (clang_doSomething). As the scope of libclang is expanded,
there will be naming issues unless a more formal "module" convention is
established. See
https://github.com/indygreg/clang/blob/libclang_compiler/README.libclang_changes#L104
for more details.

My (yet unanswered) question is whether things should continue to be
stapled onto Index.h with the existing naming conventions or whether we
should use this new functionality as an opportunity to start factoring
things into modules that are more clearly denoted and loosely coupled
e.g. clang_codegeneration_generateFromTranslationUnit() as opposed to
clang_generateCode() or clang_generateCodeFromTranslationUnit().

If adopted, I /think/ the code generation features could be implemented
without breaking ABI compatibility. But, it would certainly look
inconsistent from a style perspective. Hence my open question. I feel
you'll probably say "just use the existing convention." But, I had to
ask because I feel that things will eventually blow up and I don't like
compounding an existing problem if it can be avoided, especially when it
comes to API design.

Greg