Re: [Vala] Header file generation

[Philip Van Hoof <spam pvanhoof be>]

On Sun, 2009-01-11 at 14:14 +0100, Jürg Billeter wrote:
> I want to finally solve issues we're having related to generation of C
> header files. The current situation is that valac generates a .h file in
> addition to a .c file for each .vala source file. The .h files describe
> both, the public and the internal, C API.
>
> There are various issues with the current approach:
>
>  * Header file interdependencies

[ CUT ]

>    While this works in many cases, there are situations that cannot be
>    solved with the current approach, depending on what type you declare
>    in what .vala file. There are also situations that could be solved
>    with the current approach but are not implemented yet; it would
>    complicate the code even further.

Make a project-forward-typedefs.h or a internal-common.h and include it
at the top of each .c file. It will contain typedefs for all circular
cases that couldn't be reordered to avoid having to do this.

>  * Internal API
>    The whole point of an internal API is that it is internal, and we
>    should therefore aim to separate public from internal header files.

-priv.h files. If you generate these, please add this to it and tell
people to add -DPROJECT_COMPILATION if they use "valac -C" themselves.

#if !defined (PROJECT_COMPILATION)
#error "PROJECT_COMPILATION not defined, this must be defined to use project's internal functions"
#endif


>  * Build performance
>    As the internal API is in the header file as well, small changes can
>    lead to a rebuild of the whole library or application. As the C
>    compilation takes more time than the Vala compilation for larger
>    projects, developers could profit from a vastly increased rebuild
>    performance if we can solve this issue.

-priv.h files

>  * No single header file for users
>    The trend in GLib-based libraries is to only provide a single header
>    file per library for public use. The advantage is that it is easier
>    to provide a stable include mechanism and provides more flexibility
>    to the internal header organization of libraries.
>
>    This is currently not directly supported by the Vala compiler,
>    leading to extra work for people that want to provide that.

Generate a project.h that includes all non-priv.h files

> It is important that we find a permanent solution as changes to this can
> lead to broken build systems, and I intend to finish upstream automake
> integration as soon as we have a stable solution.

Cool! Awesome!

> Possible solution steps and their issues:
>
>  * Centralize type declarations
>    Interdependencies only occur among type declarations (typedefs and
>    struct declarations). If we move type declarations to a central
>    place and include that before any function and global variable
>    declarations, we solve the dependency issues. However, this change
>    might decrease build performance, especially if we also do this for
>    internal types.

nod.

>  * Generate two sets of header files
>    For each source file foo.vala, we could generate foo-priv.h in
>    addition to foo.c and foo.h and move the internal C API there. One
>    issue with this approach is that it clutters the source directory
>    with even more files. The compiler will always have to generate all
>    three files, even if some are empty, to not break build system
>    integration.

nod.

>  * Generate one additional header file for the internal API
>    We could avoid generating many -priv.h by just generating one big
>    foo-priv.h file that contains the full internal. However, in some
>    projects you have a large internal API, for example, in applications
>    without plugin support. This means that rebuild performance would get
>    a lot worse.

nod. But make sure it's clear for integrators what files might possibly
be generated (spec it). Some integrators (packagers, etc) add generated
files to a repository or tarball, and they surely want to know which
files can be among the ones being generated, and which ones are to be
ignored.

Also note the _build directory for make-distcheck. People generally want
to know what should be in EXTRA_DIST and things like that (if generated
files are impossible to be added as part of _SOURCES and/or _HEADERS for
some reason).

>  * Minimize use of header files
>    A more radical approach would be to not use header files where not
>    necessary. The Vala compiler could insert required declarations at
>    the top of each generated .c file and only use include directives for
>    external libraries. This would lead to optimal rebuild performance at
>    the cost of a bit larger .c files.
>
>    We obviously still need to support generating header files to use
>    libraries written in Vala. I would propose to add an option -H foo.h
>    to valac to generate a single header file with the full public C API.

So let valac copy what would end up in -priv.h files into each .c file
being generated?

Well, the .c is not for human eyes nor hands to see nor modify, so
that's okay for me.

You kinda loose the capability of interfering from a manual .c file,
like I described in this example (although the particular example
wouldn't be affected): http://live.gnome.org/Vala/MultiImplementInC

I kinda like that nature of Vala. But I can see that it's not (not
really) the purpose of Vala for your or other people's POV (and I'll
accept that).

Also, I understand that it's near to impossible to spec the layout of
such a -priv.h file for a given class, until the end of times. As that
might block Vala's innovation significantly.

So, generally ... sure, go ahead. We who want to hack should cope,
instead of whine about it, when doing hacks. Right?

nod.

> I'm leaning towards the last solution as this solves all of the issues
> mentioned above and should also provide the simplest way to integrate
> into build systems such as automake. I can understand that some people
> might not like that solution as it deviates from the traditional way how
> you would do it in C. However, Vala is about practical solutions, not
> traditions.

nod.


Cheers

-- 
Philip Van Hoof, freelance software developer
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
http://pvanhoof.be/blog
http://codeminded.be