hackers.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4 <article>
   5   <articleinfo>
   6     <title>Hackers' Guide to Vala</title>
   7
   8     <!-- If you edit this document, list yourself as an author or
   9          contributor, and put an entry in the revision history. -->
  10
  11     <authorgroup>
  12       <author>
  13         <firstname>Rodney</firstname>
  14         <surname>Lorrimar</surname>
  15         <contrib>Document Author</contrib>
  16       </author>
  17
  18       <othercredit>
  19         <firstname>Jürg</firstname>
  20         <surname>Billeter</surname>
  21         <contrib>Vala Author</contrib>
  22       </othercredit>
  23
  24       <othercredit>
  25         <firstname>Raffaele</firstname>
  26         <surname>Sandrini</surname>
  27         <contrib>Vala Author</contrib>
  28       </othercredit>
  29
  30       <othercredit>
  31         <firstname>Philip</firstname>
  32         <surname>van Hoof</surname>
  33         <contrib>Contribution of the building Vala section.</contrib>
  34       </othercredit>
  35
  36       <editor>
  37         <firstname>Rodney</firstname>
  38         <surname>Lorrimar</surname>
  39         <email>rodney@rodney.id.au</email>
  40       </editor>
  41     </authorgroup>
  42
  43     <date>23 Apr 2008</date>
  44
  45     <revhistory>
  46       <revision>
  47         <revnumber>0.11</revnumber>
  48         <date>23 Apr 2008</date>
  49         <revremark>Pre draft</revremark>
  50       </revision>
  51     </revhistory>
  52   </articleinfo>
  53
  54   <para>
  55     The goal of this document is to provide a single point of
  56     information for developers interested in improving Vala.
  57   </para>
  58
  59   <para>
  60     It is hoped that that this document will encourage more Vala users
  61     to contribute to Vala by finding/fixing bugs, writing
  62     documentation, writing test-cases, and implementing new features.
  63   </para>
  64
  65   <para>
  66     In the opinion of this document's author, a quality Vala 1.0 is an
  67     important part of the future of the GNOME Platform, because it
  68     will simplify the task of creating and maintaining excellent
  69     language-neutral libraries, which are necessary for the next
  70     generation of applications.
  71   </para>
  72
  73   <para>
  74     The Vala code is fresh, and easy to read. The variable and class
  75     names are descriptive, and one often has a general feel of what
  76     the code is supposed to do, so the sparse comments are generally
  77     not a problem. However, because it is a compiler, Vala is
  78     inevitably long, and its call stack deep. This document should
  79     provide a high-level view of how Vala is put together.
  80   </para>
  81
  82   <para>
  83     Eventually, most of this document will be merged into the source
  84     code and generated from there. However the necessary tool has not
  85     been written yet.
  86   </para>
  87
  88   <sect1><title>Environment Issues</title>
  89
  90   <sect2><title>Getting the source</title>
  91   <para>
  92     The Vala source code is available from GNOME svn.
  93   </para>
  94
  95   <para>
  96     <ulink url="http://svn.gnome.org/viewcvs/vala/trunk/">http://svn.gnome.org/svn/vala/trunk</ulink>
  97   </para>
  98
  99   <sect3><title>Git</title>
 100
 101   <para>
 102     Git allows developers without SVN access to maintain their own
 103     branches and simplifies the task of submitting patches back to the
 104     project maintainers.
 105   </para>
 106
 107   <para>
 108     It allows all users to participate in development on more equal
 109     terms with the developers who have SVN access.
 110   </para>
 111
 112   <para>
 113     Follow <ulink
 114     url="http://www.flavio.castelli.name/howto_use_git_with_svn">these
 115     instructions</ulink> to get your own git tree from the svn.
 116   </para>
 117
 118   </sect3>
 119   </sect2>
 120
 121   <sect2><title>Getting this document</title>
 122
 123   <para>
 124     For the time being, until this document is of suitable quality to
 125     be released, it will live in a separate git tree. Anyone
 126     interested can make edits on the <ulink
 127     url="http://repo.or.cz/mob.html">mob branch</ulink>.
 128   </para>
 129
 130   <para>
 131     git pull
 132     <ulink url="http://repo.or.cz/w/vala-hackers-guide.git">git://repo.or.cz/vala-hackers-guide.git</ulink>
 133   </para>
 134   </sect2>
 135
 136   <sect2><title>Compiling from SVN</title>
 137
 138   <sect3><title>Prerequisites</title>
 139
 140   <para>
 141     Install packages like a C compiler, glib-2.0. Older versions (0.20
 142     and older) require flex and bison. TODO: complete this list
 143   </para>
 144   </sect3>
 145
 146   <sect3><title>Step One</title>
 147   <para>
 148     Grab yourself a vala to c compiled release of vala. Vala is
 149     self-hosting so it needs another vala compiler to compile
 150     itself. Since vala compiles to C code, you can use a tarball
 151     release of vala to compile the generated C code of such a release
 152     into a working Vala compiler, that will compile the Vala compiler
 153     which you might have checked out from the repository.
 154   </para>
 155   <para>
 156     <ulink url="http://live.gnome.org/Vala/Release">http://live.gnome.org/Vala/Release</ulink>
 157   </para>
 158
 159   <table><title>Required release versions</title>
 160   <tgroup cols='2'>
 161     <thead>
 162       <row><entry>SVN Version</entry><entry>Release required to build</entry></row>
 163     </thead>
 164     <tbody>
 165       <row><entry>1207 and later</entry><entry>0.20</entry></row>
 166       <row><entry>xxxx</entry><entry>0.17</entry></row>
 167     </tbody>
 168   </tgroup>
 169   </table>
 170
 171   </sect3>
 172
 173   <sect3><title>Step Two</title>
 174     <para>
 175       Compiling the release which you just grabbed:
 176
 177     <screen>
 178 tar jxvf vala-x.y.z.tar.bz2
 179 cd vala-x.y.z
 180 ./configure --prefix=/opt/vala-release
 181 make &amp;&amp; sudo make install
 182     </screen>
 183     </para>
 184
 185   </sect3>
 186
 187   <sect3><title>Step Three</title>
 188   <para>
 189     Compiling the newest Vala from the repository:
 190
 191     Fixme: anon SVN
 192
 193     <screen>
 194 svn co svn co svn+ssh://[user]@svn.gnome.org/svn/vala/trunk vala
 195 cd vala
 196 export VALAC=/opt/vala-release/bin/vala
 197 ./autogen.sh --prefix=/opt/vala
 198 make &amp;&amp; sudo make install
 199     </screen>
 200   </para>
 201
 202   <para>
 203     Maybe you want to compile the new Vala with itself. Then you
 204     simply go over it again:
 205
 206     <screen>
 207 make distclean
 208 export VALAC=/opt/vala/bin/vala
 209 ./autogen.sh --prefix=/opt/vala
 210 make &amp;&amp; sudo make install
 211     </screen>
 212   </para>
 213   </sect3>
 214
 215   <sect3><title>Out-of-tree builds</title>
 216
 217   <para>
 218     The build works, but <filename>*.[ch]</filename> files are left
 219     behind in the source directory.
 220   </para>
 221   </sect3>
 222   </sect2>
 223
 224   <sect2><title>Setting up your editor - GNU Emacs</title>
 225   <para>
 226     The csharp-mode available from fixme does a good-enough job of
 227     syntax highlighting.
 228   </para>
 229
 230   <para>
 231     "Intellisense" using the csharp Semantic Wisent parser partially
 232     works.
 233   </para>
 234
 235   <para>
 236     This document's author intends to extend csharp-mode to support
 237     Vala and to create a new Semantic parser for Vala, though no
 238     significant work has been done yet.
 239   </para>
 240
 241   <para>
 242     Here is something you can put in .emacs which will make editing
 243     Vala in emacs easier.
 244   </para>
 245
 246   <programlisting>
 247 ;; C# mode (used for vala!)
 248 (require 'csharp-mode)
 249
 250 (defcustom vala-mode-hook nil
 251   "*Hook called by `vala-mode'."
 252   :type 'hook
 253   :group 'c)
 254
 255 ;; Vala
 256 (defun vala-mode ()
 257   "Vala hack."
 258   (interactive)
 259 ;  (kill-all-local-variables)
 260 ;  (c-initialize-cc-mode t)
 261   (csharp-mode)
 262   (setq mode-name "Vala")
 263   (run-hooks 'c-mode-common-hook)
 264   (c-set-style "linux")
 265   (setq indent-tabs-mode t)
 266   (setq c-basic-offset 4)
 267   (setq tab-width 4)
 268 ; auto stuff isn't good yet
 269   (c-toggle-auto-newline -1)
 270   (c-toggle-hungry-state -1)
 271   (run-hooks 'vala-mode-hook))
 272
 273 (add-to-list 'auto-mode-alist '("\\.vala\\'" . vala-mode))
 274
 275 ;; If you have CEDET or Semantic loaded, uncomment this line
 276 ;(semantic-load-enable-code-helpers)
 277   </programlisting>
 278
 279   </sect2>
 280
 281   <sect2><title>Coding Style</title>
 282
 283   <para>
 284     The coding style used in Vala itself seems to be a variation of
 285     the GTK+ coding style.
 286   </para>
 287
 288   <itemizedlist>
 289     <listitem><para>Tabs rather than spaces.</para></listitem>
 290     <listitem><para>Tab width unspecified, but 4 works
 291     well.</para></listitem>
 292     <listitem><para>Hanging braces.</para></listitem>
 293     <listitem><para>Cuddled else.</para></listitem>
 294     <listitem><para>Braces not necessary for single-line
 295     blocks.</para></listitem>
 296     <listitem><para>Variable and method identifiers in lowercase,
 297     words seperated by underscores.</para></listitem>
 298     <listitem><para>Type identifiers in CamelCase.</para></listitem>
 299     <listitem><para>Enum members and constants in ALL_CAPS, words
 300     seperated by underscores.</para></listitem>
 301     <listitem><para>C-style /* comments. */</para></listitem>
 302     <listitem><para>Hungarian notation not used.</para></listitem>
 303     <listitem><para>Variables often declared without type
 304     (i.e. "var").</para></listitem>
 305     <listitem><para>No line-length limit.</para></listitem>
 306     <listitem><para>No function-length limit.</para></listitem>
 307     <listitem><para>Space between method name and parameters' opening
 308     parenthesis.</para></listitem>
 309     <listitem><para>Property "get", "set", "default" declaration all
 310     on one line, seperated by semicolons, if default implementations
 311     are used.</para></listitem>
 312     <listitem><para>If properties have implementations, then "get {",
 313     "set {" open new lines.</para></listitem>
 314     <listitem><para>Attributes on their own line.</para></listitem>
 315     <listitem><para>JavaDoc-style commenting on types, methods,
 316     variables.</para></listitem>
 317     <listitem><para>Header at top of file contains:
 318     <programlisting>
 319         /* filename.vala
 320          *
 321          * Copyright (C) 20yy-20yy  Copyright Holder &lt;email@address&gt;
 322          *
 323          * License text.
 324          *
 325          * Author:
 326          *      Programmer Name &lt;programmer@email&gt;
 327          */
 328     </programlisting></para></listitem>
 329   </itemizedlist>
 330   </sect2>
 331
 332   <sect2><title>Files</title>
 333   <para>
 334     Vala source files are named in the GTK+ style, i.e. all lowercase,
 335     which no separators between words, in the format
 336     namespaceclassname.vala. For example, the filename for
 337     Vala.FormalParameter is valaformalparameter.vala.
 338   </para>
 339
 340   <para>
 341     Classes can be split across files, and this is often done for
 342     classes with a lot of methods, or very long methods.
 343   </para>
 344
 345   <para>
 346     For the Vala compiler and library there is only one namespace, and
 347     it is called "Vala". Don't put "using Vala;"; instead qualify the
 348     name of types you declare. For example "class Vala.FormalParameter
 349     : Symbol".
 350   </para>
 351   </sect2>
 352
 353   <sect2><title>Website, Mailing List, Bug Tracker, IRC</title>
 354
 355   <itemizedlist>
 356     <listitem><para>http://www.valaproject.org</para></listitem>
 357     <listitem><para><email>vala-list@gnome.org</email></para></listitem>
 358     <listitem><para>GNOME Bugzilla - http://bugs.gnome.org</para></listitem>
 359     <listitem><para>#vala on GIMPnet</para></listitem>
 360   </itemizedlist>
 361   </sect2>
 362
 363   <sect2><title>Project Maintainers</title>
 364   <para>
 365     The principle authors and project maintainers are Jürg Billeter
 366     and Raffaele Sandrini.
 367   </para>
 368   </sect2>
 369
 370   <sect2><title>License</title>
 371   <para>
 372     Vala compiler is licensed under LGPL 2.1, so that proprietary
 373     programs compiled with Vala can be distributed under different
 374     licenses and possibly without source code.
 375   </para>
 376   </sect2>
 377 </sect1>
 378
 379 <sect1 id="ch-valac"><title>The Vala Compiler</title>
 380 <para>
 381   I suppose the best place to start is <command>valac</command>, the
 382   tool which Vala programmers know the best.
 383 </para>
 384
 385 <sect2><title>Vala in a Nutshell</title>
 386 <para>
 387   The Vala compiler <command>valac</command> is a small shell around
 388   libvala which handles command-line arguments, locates the sources
 389   and libraries which are required, and drives the compilation
 390   procedure.
 391 </para>
 392
 393 <figure><title>How <command>valac</command> is linked</title>
 394 <graphic fileref="figures/valac-link.png"/>
 395 </figure>
 396
 397 <para>
 398   All the important work such as parsing, error checking/reporting,
 399   code generation, calling <command>gcc</command>, is done in libvala.
 400 </para>
 401
 402 <para>
 403   The code for <command>valac</command> can be found in
 404   <filename>compiler/valacompiler.vala</filename>.
 405 </para>
 406
 407 <sect3><title>Command-line Options</title>
 408 <para>
 409   These are handled in the normal way by the Vala binding to
 410   <classname>GLib.OptionContext</classname>. Most of the instance
 411   variables in <classname>Vala.Compiler</classname> are referenced in
 412   the options array. It's not very interesting.
 413 </para>
 414 </sect3>
 415
 416 <sect3><title>The Compilation Procedure and Vala.CodeContext</title>
 417 <para>
 418   Vala.Compiler plugs together the classes of libvala in a big
 419   pipeline. This modular design means that different Vala tools can
 420   share their code. Most modules have impressive-sounding names like
 421   AlgorithmicFrobnicator.
 422 </para>
 423
 424 <procedure><title>valac Pipeline</title>
 425   <step><para>Initialize context with command-line
 426   options.</para></step>
 427   <step><para>Plug in a code generator.</para></step>
 428   <step><para>Add packages from command-line and the non-optional
 429 GLib.</para></step>
 430   <step><para>Add sources, Vala, VAPI, and C from command-line.</para></step>
 431   <step><para>Parse everything.</para></step>
 432   <step><para>Process attributes.</para></step>
 433   <step><para>Resolve symbols.</para></step>
 434   <step><para>Setup a DBus Binding Provider.</para></step>
 435   <step><para>Setup the Semantic Analyzer.</para></step>
 436   <step><para>Plug in the DBus Binding Provider to the Semantic Analyzer.</para></step>
 437   <step><para>Do the Semantic Analysis</para></step>
 438   <step><para>Build Config.</para></step>
 439   <step><para>Check that null variables are treated
 440   properly.</para></step>
 441   <step><para>Analyse code with the memory manager. ???</para></step>
 442   <step><para>Use the code generator to emit code.</para></step>
 443   <step><para>Write out VAPI and GIDL files, if a library is being
 444   compiled.</para></step>
 445   <step><para>Compile the generated C code.</para></step>
 446 </procedure>
 447
 448 <para>
 449   The individual steps will be explained later, but first
 450   <classname>Vala.CodeContext</classname>, the data structure which
 451   holds everything together. It stores the compile options which were
 452   specified on the command line, and a list of source files to
 453   compile. There is only one <classname>CodeContext</classname>
 454   instantiated and its reference is passed around a lot, so
 455   effectively it's a global variable.
 456 </para>
 457
 458 <para>
 459      Vala.CodeContext is the root of the code tree, because
 460      it contains the root Namespace, which holds references to all
 461      parsed code nodes. In addition to the code tree, the context
 462      contains a reference to a code generator object. This object
 463      walks the code tree and generates code.
 464 </para>
 465
 466 <para>
 467      Vala.CodeContext contains an important method called accept,
 468      which initiates a depth-first traversal of the code tree. This
 469      method, and the CodeVisitor pattern will be discussed later.
 470 </para>
 471
 472 <para>
 473      ignore_node method contains the logic for the "Conditional"
 474      attribute.
 475 </para>
 476
 477 <para>
 478      For every one of the 77 (or so) code node types, there is a
 479      create_code_node_type method which constructs the code node and
 480      links it with the code generator. The parser will use these
 481      methods to create code nodes as it parses them, which know how to
 482      emit code later.
 483 </para>
 484
 485 <figure><title>Data diagram</title>
 486 <graphic fileref="figures/valac-data.png"/>
 487 </figure>
 488
 489 <para>
 490   The Vala code tree is an abstract syntax tree (AST) built by parsing
 491   the Vala sources. For example, if you see a class called
 492   <classname>Vala.Destructor</classname> which inherits
 493   <classname>Vala.Symbol</classname>, then it is a part of the
 494   AST. Data structures for the AST and the parser which builds it are
 495   in the <filename>vala</filename> directory.
 496 </para>
 497
 498 <para>
 499   Vala also uses a tree to represent the C code that will be
 500   output. Data structures for the C code tree are in the
 501   <filename>ccode</filename> directory.
 502 </para>
 503
 504 <para>
 505   The machinery which transforms the Vala AST into a C code tree is in
 506   the <filename>gobject</filename> directory. The reason it's there is
 507   because Vala outputs "GObject C" rather than plain C. GObject C is
 508   arranged in a particular object-oriented way, uses reference counted
 509   memory management, signals, data-structures, and links with glib.
 510 </para>
 511
 512 <para>
 513   Vala is split upon these lines, most probably to break the system
 514   into conceptually-related, understandable chunks. However, with
 515   suitable modifications, the different modules could be replaced.
 516   Conceivably, Vala could produce non-GObject C code. More
 517   realistically, Vala could produce intermediate code as a <ulink
 518   url="http://gcc.gnu.org/frontends.html">GCC frontend</ulink>.
 519 </para>
 520 </sect3>
 521 </sect2>
 522
 523 <sect2><title>Parser</title>
 524 <para>
 525   The parser reads Vala and VAPI code and outputs an AST. In the eyes
 526   of the parser, Vala and VAPI are the same thing. The difference to
 527   us is that VAPI files never have method definitions, but the parser
 528   will read pretty much everything as long as it seems syntactically
 529   correct. Most errors are caught later by the Semantic Analyzer.
 530 </para>
 531
 532 <para>
 533   Before 0.3.1, Vala's parser was the classic flex scanner and Bison
 534   LALR parser combination. But as of <ulink
 535   url="http://svn.gnome.org/viewvc/vala?view=revision&amp;revision=1194">SVN
 536   1194</ulink>, the parser is a hand-crafted recursive descent
 537   parser. The parser is in <filename>vala/valaparser.vala</filename>
 538   and its lexer is in <filename>vala/valascanner.vala</filename>.
 539 </para>
 540
 541 <para>
 542   The entry point of the parser is
 543   <code>Vala.Parser.parse()</code>. This method is called by
 544   <code>Vala.Compiler.run()</code>. <classname>Vala.Parser</classname>
 545   is an implementation of <classname>Vala.CodeVisitor</classname> for
 546   source files.
 547 </para>
 548
 549 <sect3><title>Visitors and Ping Pong</title>
 550
 551 <para>
 552   <classname>CodeVisitor</classname> is an abstract base class which
 553   provides 75 empty virtual methods for each kind of code node. A
 554   class which inherits <classname>CodeVisitor</classname> is supposed
 555   to do some kind of processing of the code tree. Here are all the
 556   <classname>CodeVisitor</classname> classes in Vala:
 557 </para>
 558
 559 <screen>
 560      public class Vala.CodeVisitor : Object
 561        public class Vala.AttributeProcessor : CodeVisitor
 562        public class Vala.CFGBuilder : CodeVisitor
 563        public class Vala.CodeGenerator : CodeVisitor
 564        public class Vala.GIdlParser : CodeVisitor
 565        public class Vala.GIdlWriter : CodeVisitor
 566        public class Vala.InterfaceWriter : CodeVisitor
 567        public class Vala.MemoryManager : CodeVisitor
 568        public class Vala.NullChecker : CodeVisitor
 569        public class Vala.Parser : CodeVisitor
 570        public class Vala.SemanticAnalyzer : CodeVisitor
 571        public class Vala.SymbolResolver : CodeVisitor
 572 </screen>
 573
 574 <para>
 575   <classname>CodeVisitor</classname> works closely with the different
 576   <classname>Vala.CodeNode</classname> classes to traverse the code
 577   tree. Here are all the code node types in Vala:
 578 </para>
 579
 580 <screen>
 581 public abstract class Vala.CodeNode : Object
 582   public interface Vala.Statement : CodeNode
 583   public class Vala.BreakStatement : CodeNode, Statement
 584   public class Vala.ContinueStatement : CodeNode, Statement
 585   public class Vala.DeclarationStatement : CodeNode, Statement
 586   public class Vala.DeleteStatement : CodeNode, Statement
 587   public class Vala.DoStatement : CodeNode, Statement
 588   public class Vala.EmptyStatement : CodeNode, Statement
 589   public class Vala.ExpressionStatement : CodeNode, Statement
 590   public class Vala.ForStatement : CodeNode, Statement
 591   public class Vala.IfStatement : CodeNode, Statement
 592   public class Vala.LockStatement : CodeNode, Statement
 593   public class Vala.ReturnStatement : CodeNode, Statement
 594   public class Vala.SwitchStatement : CodeNode, Statement
 595   public class Vala.ThrowStatement : CodeNode, Statement
 596   public class Vala.TryStatement : CodeNode, Statement
 597   public class Vala.WhileStatement : CodeNode, Statement
 598
 599   public abstract class Vala.DataType : CodeNode
 600     public abstract class Vala.ReferenceType : DataType
 601       public class Vala.ArrayType : ReferenceType
 602       public class Vala.ClassType : ReferenceType
 603       public class Vala.ErrorType : ReferenceType
 604       public class Vala.InterfaceType : ReferenceType
 605       public class Vala.NullType : ReferenceType
 606
 607     public class Vala.DelegateType : DataType
 608     public class Vala.InvalidType : DataType
 609     public class Vala.MethodType : DataType
 610     public class Vala.PointerType : DataType
 611     public class Vala.SignalType : DataType
 612     public class Vala.TypeParameterType : DataType
 613     public class Vala.UnresolvedType : DataType
 614     public class Vala.ValueType : DataType
 615     public class Vala.VoidType : DataType
 616
 617   public abstract class Vala.Symbol : CodeNode
 618     public abstract class Vala.Typesymbol : Symbol
 619
 620     public class Vala.Block : Symbol, Statement
 621     public class Vala.Constructor : Symbol
 622     public class Vala.Destructor : Symbol
 623     public class Vala.EnumValue : Symbol
 624     public class Vala.ErrorCode : Symbol
 625     public class Vala.FormalParameter : Symbol
 626     public class Vala.Member : Symbol
 627     public class Vala.Namespace : Symbol
 628     public class Vala.TypeParameter : Symbol
 629     public class Vala.VariableDeclarator : Symbol
 630
 631   public abstract class Vala.Expression : CodeNode
 632     public abstract class Vala.Literal : Expression
 633       public class Vala.BooleanLiteral : Literal
 634       public class Vala.CharacterLiteral : Literal
 635       public class Vala.IntegerLiteral : Literal
 636       public class Vala.NullLiteral : Literal
 637       public class Vala.RealLiteral : Literal
 638       public class Vala.StringLiteral : Literal
 639
 640     public class Vala.AddressofExpression : Expression
 641     public class Vala.ArrayCreationExpression : Expression
 642     public class Vala.Assignment : Expression
 643     public class Vala.BaseAccess : Expression
 644     public class Vala.BinaryExpression : Expression
 645     public class Vala.CastExpression : Expression
 646     public class Vala.ConditionalExpression : Expression
 647     public class Vala.ElementAccess : Expression
 648     public class Vala.InitializerList : Expression
 649     public class Vala.InvocationExpression : Expression
 650     public class Vala.LambdaExpression : Expression
 651     public class Vala.MemberAccess : Expression
 652     public class Vala.ObjectCreationExpression : Expression
 653     public class Vala.ParenthesizedExpression : Expression
 654     public class Vala.PointerIndirection : Expression
 655     public class Vala.PostfixExpression : Expression
 656     public class Vala.ReferenceTransferExpression : Expression
 657     public class Vala.SizeofExpression : Expression
 658     public class Vala.Tuple : Expression
 659     public class Vala.TypeCheck : Expression
 660     public class Vala.TypeofExpression : Expression
 661     public class Vala.UnaryExpression : Expression
 662
 663   public class Vala.LocalVariableDeclaration : CodeNode
 664   public class Vala.CatchClause : CodeNode
 665   public class Vala.Attribute : CodeNode
 666   public class Vala.PropertyAccessor : CodeNode
 667   public class Vala.MemberInitializer : CodeNode
 668   public class Vala.SwitchLabel : CodeNode
 669   public class Vala.UnresolvedSymbol : CodeNode
 670   public class Vala.NamedArgument : CodeNode
 671   public class Vala.NamespaceReference : CodeNode
 672 </screen>
 673
 674 <para>
 675   All <classname>CodeNode</classname>s except the root have a non-null
 676   parent CodeNode. Some specializations of
 677   <classname>CodeNode</classname> may have children. The type and
 678   number of children are declared in the specialized class.
 679 </para>
 680
 681 <para>
 682   The two important methods in a <classname>CodeNode</classname> are
 683   <function>accept</function> and
 684   <function>accept_children</function>. <function>accept()</function>
 685   lets the node declare to the <classname>CodeVisitor</classname> what
 686   it is, so the <classname>CodeVisitor</classname> can act on it. For
 687   example, <code>Vala.Struct.accept()</code>
 688 </para>
 689
 690 <programlisting>
 691          public override void accept (CodeVisitor visitor) {
 692              visitor.visit_struct (this);  /* I am a struct! */
 693          }
 694 </programlisting>
 695
 696 <para>
 697   <function>accept_children()</function> lets the node accept all of
 698   its children so they can declare themselves to the
 699   <classname>CodeVisitor</classname>. This is the recursive part of
 700   the traversal. For example, a <classname>Struct</classname> code
 701   node has a list of base types, type parameters, fields, constants,
 702   and methods. <code>Vala.Struct.accept_children()</code> accepts all
 703   of these.
 704 </para>
 705
 706 <programlisting>
 707      public override void accept_children (CodeVisitor visitor) {
 708          foreach (DataType type in base_types) {
 709              type.accept (visitor);
 710          }
 711
 712          foreach (TypeParameter p in type_parameters) {
 713              p.accept (visitor);
 714          }
 715
 716          foreach (Field f in fields) {
 717              f.accept (visitor);
 718          }
 719
 720          foreach (Constant c in constants) {
 721              c.accept (visitor);
 722          }
 723
 724          foreach (Method m in methods) {
 725              m.accept (visitor);
 726          }
 727      }
 728 </programlisting>
 729
 730 <para>
 731   As you can see, the <classname>CodeVisitor</classname> is repeatedly
 732   asked to visit different code nodes. It can do whatever analysis is
 733   necessary and then traverse deeper into the code tree. This is what
 734   a hypothetical implementation of
 735   <code>XmlGenerator.visit_struct()</code> might look like:
 736 </para>
 737
 738 <programlisting>
 739      public override void visit_struct (Struct st) {
 740          /* Do some processing of this struct. */
 741          stdout.printf ("&lt;vala:struct name=\"%s\"&gt;\n", st.name);
 742
 743          /* recurse through struct's children */
 744          st.accept_children (this);
 745
 746          /* Do some more processing of the struct, now that its
 747           * children have been accepted. */
 748          stdout.printf ("&lt;/vala:struct&gt;\n");
 749      }
 750 </programlisting>
 751
 752 <para>
 753   The <function>visit_</function> methods of a
 754   <function>CodeVisitor</function> needn't call
 755   <code>CodeNode.accept_children()</code>, if it isn't necessary to
 756   traverse the whole depth of the code tree. It also isn't necessary
 757   to write <function>visit_</function> methods for every kind of code
 758   node, because empty implementations are already provided in
 759   <classname>CodeVisitor</classname>.
 760 </para>
 761
 762 <para>
 763   What does this have to do with ping pong? Well, the flow of control
 764   bounces between the <classname>CodeVisitor</classname> and the
 765   <classname>CodeNode</classname>s: <function>accept</function>,
 766   <function>visit</function>, <function>accept</function>,
 767   <function>visit</function>, ... When you navigate the code you will
 768   probably find yourself bouncing between different classes.
 769 </para>
 770
 771 </sect3>
 772
 773 <sect3><title>Back to the Parser</title>
 774
 775 <para>
 776   <classname>Vala.Parser</classname> is a highly specialized
 777   <classname>CodeVisitor</classname> - the only type of code node it
 778   visits is a <classname>Vala.SourceFile</classname>. However the
 779   <classname>Parser</classname> calls back to the context and uses it
 780   to create code nodes (mentioned before), then adds these code nodes
 781   into the context's root code node.
 782 </para>
 783 </sect3>
 784
 785 <sect3><title>Error Handling</title>
 786
 787 <para>
 788   I don't want to spoil your fun too much by going into the details of
 789   the parser, other than that every <function>parse_</function>
 790   function can throw a
 791   <classname>ParseError</classname>. <classname>ParseError</classname>
 792   is caught when parsing a block or the declarations of a namespace,
 793   class, struct, or interface. Fixme.
 794 </para>
 795 </sect3>
 796
 797 <sect3><title>Grammar of Vala</title>
 798
 799 <para>
 800   This grammar is hand-generated from
 801   <classname>Vala.Parser</classname>. Sometimes the structure of this
 802   grammar diverges slightly from the code, for example optional
 803   non-terminal symbols. However the non-terminal symbol names usually
 804   match a <function>parse_</function> method in
 805   <classname>Vala.Parser</classname>.
 806 </para>
 807
 808 <programlisting>
 809 input ::=
 810         using_directive* root_declarations
 811
 812 using_directive ::=
 813         "using" symbol ("," symbol)* ";"
 814
 815 // from parse_symbol_name
 816 symbol_name ::=
 817         identifier ("." identifier)*
 818
 819 // from parse_identifier, skip_identifier, get_last_string
 820 identifier ::=
 821         TOKEN
 822
 823 // corresponds to parse_declarations
 824 root_declarations ::=
 825         namespace_declarations
 826
 827 // corresponds to parse_declarations
 828 other_declarations ::=
 829         namespace_declarations
 830            | class_declarations
 831            | struct_declarations
 832            | interface_declarations
 833
 834 // corresponds to parse_declarations
 835 declarations ::=
 836         "{" other_declarations "}"
 837
 838 namespace_declarations ::=
 839         namespace_member*
 840
 841 // from parse_namespace_member
 842 namespace_member ::=
 843         namespace_declaration
 844            | class_declaration
 845            | interface_declaration
 846            | struct_declaration
 847            | enum_declaration
 848            | error_domain_declaration // ???
 849            | delegate_declaration
 850            | method_declaration
 851            | field_declaration
 852            | constant_declaration
 853
 854 // from parse_class_member
 855 class_member ::=
 856          class_declaration
 857            | struct_declaration
 858            | enum_declaration
 859            | delegate_declaration
 860            | method_declaration
 861            | signal_declaration
 862            | field_declaration
 863            | constant_declaration
 864            | property_declaration
 865            | constructor_declaration
 866            | destructor_declaration
 867
 868 // from parse_declaration and parse_namespace_declaration
 869 namespace_declaration ::=
 870         attribute* "namespace" symbol_name declarations
 871
 872 // from parse_declaration and parse_class_declaration
 873 class_declaration ::=
 874         [access_modifier] type_declaration_modifiers
 875         "class" symbol_name [type_parameter_list] ":" type ("," type)*
 876         declarations
 877
 878 // from parse_access_modifier
 879 access_modifier ::=
 880         "private"
 881            | "protected"
 882            | "public"
 883
 884 // from parse_type_declaration_modifiers
 885 type_declaration_modifiers ::=
 886         ("abstract" | "static")*
 887
 888 // from parse_member_declaration_modifiers
 889 member_declaration_modifiers ::=
 890         ("abstract" | "class" | "inline" | "override" | "static" | "virtual")*
 891
 892 // from parse_type_parameter_list
 893 type_parameter_list ::=
 894         "&lt;" identifier ("," identifier)* "&gt;"
 895
 896 // fixme: complete the grammar, check it
 897
 898 </programlisting>
 899
 900 </sect3>
 901
 902 </sect2>
 903
 904 <sect2><title>Attribute Processing</title>
 905
 906 <para>
 907   <classname>Vala.Attribute</classname>s are code tree nodes and have
 908   a name and a possibly empty list of key-value arguments. Some types
 909   of code tree nodes have as children a list of
 910   <classname>Attributes</classname>. The attribute processor's purpose
 911   is to interpret the attributes which were parsed into the code tree.
 912 </para>
 913
 914 <para>
 915   Later in the compilation, the results of attribute processing will
 916   be used, for example the <code>CCode cname</code> attribute affects
 917   what function names are used in emitted C code.
 918 </para>
 919
 920 <para>
 921   All attributes except for <code>Conditional</code> are handled from
 922   <classname>Vala.AttributeProcessor</classname>. I don't know where
 923   and how conditional is handled, but there is a function
 924   <function>ignore_node()</function> in
 925   <classname>Vala.CodeContext</classname>.
 926 </para>
 927
 928 <para>
 929   <classname>Vala.AttributeProcessor</classname> is a
 930   <classname>CodeVisitor</classname> which simply calls the
 931   <function>process_attributes()</function> method on every namespace,
 932   class, struct, interface, enum, method, constructor, parameter,
 933   property, delegate, constant, field, and signal that it visits.
 934 </para>
 935
 936 <para>
 937   Inside the <function>process_attributes()</function> method of each
 938   of these objects, a series of string comparisons will be made to
 939   parse the attributes. If the attribute is called "CCode", then the
 940   <function>process_ccode_attributes()</function> function will be
 941   called to parse the key-value pairs supplied.
 942 </para>
 943
 944 <para>
 945 fixme: mention <function>Vala.Parser.set_attributes()</function>
 946 </para>
 947
 948 <variablelist><title>Attributes Recognized by Vala</title>
 949 <varlistentry>
 950   <term><classname>Vala.Namespace</classname></term>
 951   <listitem><itemizedlist>
 952     <listitem><para>CCode</para></listitem>
 953   </itemizedlist></listitem>
 954 </varlistentry>
 955 <varlistentry>
 956   <term><classname>Vala.Class</classname></term>
 957   <listitem><itemizedlist>
 958     <listitem><para>CCode</para></listitem>
 959     <listitem><para>ErrorBase</para></listitem>
 960   </itemizedlist></listitem>
 961 </varlistentry>
 962 <varlistentry>
 963   <term><classname>Vala.Struct</classname></term>
 964   <listitem><itemizedlist>
 965     <listitem><para>CCode</para></listitem>
 966     <listitem><para>SimpleType</para></listitem>
 967     <listitem><para>IntegerType</para></listitem>
 968     <listitem><para>FloatingType</para></listitem>
 969   </itemizedlist></listitem>
 970 </varlistentry>
 971 <varlistentry>
 972   <term><classname>Vala.Interface</classname></term>
 973   <listitem><itemizedlist>
 974     <listitem><para>CCode</para></listitem>
 975     <listitem>
 976       <para>DBusInterface</para>
 977       <itemizedlist>
 978         <listitem><para>DBusGProxy</para></listitem>
 979       </itemizedlist>
 980     </listitem>
 981   </itemizedlist></listitem>
 982 </varlistentry>
 983 <varlistentry>
 984   <term><classname>Vala.Enum</classname></term>
 985   <listitem><itemizedlist>
 986     <listitem><para>CCode</para></listitem>
 987     <listitem><para>Flags</para></listitem>
 988   </itemizedlist></listitem>
 989 </varlistentry>
 990 <varlistentry>
 991   <term><classname>Vala.Method</classname></term>
 992   <listitem><itemizedlist>
 993     <listitem><para>CCode</para></listitem>
 994     <listitem><para>ReturnsModifiedPointer</para></listitem>
 995     <listitem><para>FloatingReference</para></listitem>
 996     <listitem><para>NoArrayLength</para></listitem>
 997     <listitem><para>PrintfFormat</para></listitem>
 998     <listitem><para>Import</para></listitem>
 999   </itemizedlist></listitem>
1000 </varlistentry>
1001 <varlistentry>
1002   <term><classname>Vala.CreationMethod</classname></term>
1003   <listitem>
1004     <para><emphasis>Same as <classname>Vala.Method</classname> - this class
1005     inherits Method</emphasis></para>
1006   </listitem>
1007 </varlistentry>
1008 <varlistentry>
1009   <term><classname>Vala.FormalParameter</classname></term>
1010   <listitem><itemizedlist>
1011     <listitem><para>CCode</para></listitem>
1012   </itemizedlist></listitem>
1013 </varlistentry>
1014 <varlistentry>
1015   <term><classname>Vala.Property</classname></term>
1016   <listitem><itemizedlist>
1017     <listitem><para>Notify</para></listitem>
1018     <listitem><para>NoAccessorMethod</para></listitem>
1019     <listitem>
1020       <para>Description</para>
1021       <itemizedlist>
1022         <listitem><para>nick</para></listitem>
1023         <listitem><para>blurb</para></listitem>
1024       </itemizedlist>
1025     </listitem>
1026   </itemizedlist></listitem>
1027 </varlistentry>
1028 <varlistentry>
1029   <term><classname>Vala.Delegate</classname></term>
1030   <listitem><itemizedlist>
1031     <listitem><para>CCode</para></listitem>
1032     <listitem><para>NoArrayLength</para></listitem>
1033   </itemizedlist></listitem>
1034 </varlistentry>
1035 <varlistentry>
1036   <term><classname>Vala.Constant</classname></term>
1037   <listitem><itemizedlist>
1038     <listitem><para>CCode</para></listitem>
1039   </itemizedlist></listitem>
1040 </varlistentry>
1041 <varlistentry>
1042   <term><classname>Vala.Field</classname></term>
1043   <listitem><itemizedlist>
1044     <listitem><para>CCode</para></listitem>
1045     <listitem><para>NoArrayLength</para></listitem>
1046   </itemizedlist></listitem>
1047 </varlistentry>
1048 <varlistentry>
1049   <term><classname>Vala.Signal</classname></term>
1050   <listitem><itemizedlist>
1051     <listitem><para>HasEmitter</para></listitem>
1052   </itemizedlist></listitem>
1053 </varlistentry>
1054 </variablelist>
1055
1056 </sect2>
1057
1058 <sect2><title>Symbol Resolution</title>
1059
1060 <para>
1061   <classname>Vala.SymbolResolver</classname> is a
1062   <classname>CodeVisitor</classname> that exchanges
1063   <classname>Vala.UnresolvedType</classname>s in the parse tree with
1064   <classname>Vala.DataType</classname>s and links
1065   <classname>Vala.NamespaceReference</classname>s with the correct
1066   namespace symbol. Additionally, it checks base types for classes so
1067   that classes don't inherit from multiple classes or themselves, and
1068   likewise it checks that interfaces don't need to implement
1069   themselves.
1070 </para>
1071
1072 <sect3><title>Data Types</title>
1073
1074 <para>
1075   Every expression has a static type. This is computed by the semantic
1076   analyser. <classname>Vala.DataType</classname> is called a "type
1077   reference" because it contains a reference to a
1078   <classname>Vala.Typesymbol</classname> (a class, interface, etc) as
1079   well as information about the expression's type e.g. if it can be
1080   null, if it's an out parameter.
1081 </para>
1082
1083 <para>Fixme: expand this section</para>
1084 </sect3>
1085
1086 <sect3><title>Symbols</title>
1087
1088 <para>
1089   A <classname>Vala.Symbol</classname> is a specialization of
1090   <classname>Vala.CodeNode</classname>. All symbols except for the
1091   root symbol are contained within another's scope. Types have scope
1092   and variables have scope. For types and variables, scope determines
1093   their accessibility, subject to access modifiers. For variables,
1094   scope also determines their lifetime. As the code tree is traversed,
1095   <classname>SymbolResolver</classname> keeps track of the current
1096   scope. For example, when a class is visited,
1097   <varname>current_scope</varname> is set to that class's scope.
1098 </para>
1099
1100 <para>
1101   When the parser parses a type, e.g. in the statement
1102   <code>Gtk.Window main_window;</code>, the type
1103   <classname>Gtk.Window</classname> is initially a
1104   <classname>Vala.UnresolvedType</classname>. In
1105   <function>visit_data_type()</function>, the
1106   <classname>UnresolvedType</classname> code node asks its parent to
1107   replace it with a new <classname>Vala.DataType</classname> created
1108   with <function>resolve_type()</function>.
1109 </para>
1110
1111 <para>
1112   <classname>UnresolvedType</classname>s have
1113   <classname>UnresolvedSymbol</classname>s. <function>resolve_type()</function>
1114   uses <function>resolve_symbol()</function> to find the
1115   <classname>Typesymbol</classname> referred to, and then wraps it in
1116   a new <classname>DataType</classname> object.
1117 </para>
1118
1119 <para>
1120  <function>resolve_symbol</function> is a recursive method which looks
1121  up an unresolved symbol's name in the current scope and returns the
1122  corresponding <classname>Typesymbol</classname>. The base case is
1123  when the <classname>UnresolvedSymbol</classname> has no qualifiers,
1124  e.g. <classname>Window</classname>. The recursive case is when the
1125  symbol looks like <classname>Gtk.Window</classname> or
1126  <varname>Gtk.Orientation.HORIZONTAL</varname>. In <function>Vala.Parser.parse_symbol_name()</function>, the symbol is built inside-out, so <code>Gtk.Orientation.HORIZONTAL</code> is parsed as
1127
1128 <programlisting>
1129 UnresolvedSymbol
1130     (UnresolvedSymbol
1131         (UnresolvedSymbol(null, "Gtk"),
1132          "Orientation"),
1133      "HORIZONTAL")
1134 </programlisting>
1135
1136 This is inside-out because <code>Orientation</code> is the parent
1137 scope of <code>HORIZONTAL</code>, but <code>Orientation</code> is the
1138 child node of <code>HORIZONTAL</code>.
1139 </para>
1140
1141 <para>
1142   In the base case, the symbol's name is looked up in
1143   <varname>current_scope</varname>. If the symbol is not found
1144   there, then the scope of all imported namespaces is searched. If
1145   more than one imported namespace contains the symbol, an "ambiguous
1146   reference" error will be reported.
1147 </para>
1148
1149 <para>
1150   In the recursive case, <function>resolve_symbol()</function> is
1151   called on the child node to give a parent scope, in which the symbol
1152   is looked up.
1153 </para>
1154
1155 <para>
1156   One last function of <classname>SymbolResolver</classname> is in
1157   <function>visit_variable_declarator()</function> - to mark a
1158   variable type reference as "nullable" if the variable's type is a
1159   class, interface, array or error (reference type). This is used
1160   later by <classname>Vala.NullChecker</classname>.
1161 </para>
1162
1163 </sect3>
1164
1165 </sect2>
1166
1167 <sect2><title>Semantic Analyzer</title>
1168
1169 <para></para>
1170 </sect2>
1171
1172 <sect2 id="ch-codegen"><title>C Code Generation</title>
1173
1174 <para></para>
1175 </sect2>
1176
1177 <sect2><title>C Code Compilation and Linking</title>
1178
1179 <para></para>
1180 </sect2>
1181 </sect1>
1182
1183 <sect1 id="ch-vapi"><title>Vala Bindings - VAPI</title>
1184
1185 <para>
1186   The bindings are located in the vapi directories.
1187 </para>
1188
1189 <sect2><title><code>CCode</code> Attribute Reference</title>
1190
1191 <para>
1192   <code>CCode</code> attributes influence the C code which is
1193   generated by Vala. They have the form
1194
1195   <programlisting>
1196     [CCode (argument0 = value0, argument1 = value1, ...)]
1197   </programlisting>
1198 </para>
1199
1200 <para>
1201   Usually these attributes are not required because Vala chooses
1202   normal values. However, they exist for the cases when Vala's chosen
1203   values don't fit the API.
1204 </para>
1205
1206 <warning>
1207   <para>
1208     I'm not sure how much of this will apply once we have GObject
1209     introspection.
1210   </para>
1211 </warning>
1212
1213   <table><title>CCode Attributes</title>
1214   <tgroup cols='4'>
1215     <colspec colname='name'/>
1216     <colspec colname='applies'/>
1217     <colspec colname='type'/>
1218     <colspec colname='ex'/>
1219     <spanspec spanname="desc" namest="name" nameend="ex"/>
1220     <thead>
1221       <row>
1222         <entry>Name</entry>
1223         <entry>Applies to</entry>
1224         <entry>Type</entry>
1225         <entry>Example</entry>
1226       </row>
1227       <row>
1228         <entry spanname="desc">Description</entry>
1229       </row>
1230     </thead>
1231     <tbody>
1232       <row>
1233         <entry>array_length_pos</entry>
1234         <entry>constructor, delegate, method, parameter</entry>
1235         <entry>string</entry>
1236         <entry></entry>
1237       </row>
1238       <row>
1239         <entry spanname="desc">
1240           array_length_pos
1241         </entry>
1242       </row>
1243       <row>
1244         <entry>cheader_filename</entry>
1245         <entry>class, constant, constructor, delegate, enum, field, interface, method, namespace, struct</entry>
1246         <entry>string - comma-separated list of headers</entry>
1247         <entry>"glib.h"</entry>
1248       </row>
1249       <row>
1250         <entry spanname="desc">
1251           The header file(s) which should be <code>#include</code>d in
1252           the emitted C code, so that this symbol is usable. If more
1253           than one header file is needed, separate them by commas.
1254         </entry>
1255       </row>
1256       <row>
1257         <entry>cname</entry>
1258         <entry>class, constant, constructor, delegate, enum, field, method, struct</entry>
1259         <entry>string</entry>
1260         <entry>"gboolean"</entry>
1261       </row>
1262       <row>
1263         <entry spanname="desc">
1264           The name that this symbol will take when translated into C
1265           code. If this attribute is not specified, the symbol will
1266           get a name with the normal vala translation rules.
1267         </entry>
1268       </row>
1269       <row>
1270         <entry>const_cname</entry>
1271         <entry>class, struct</entry>
1272         <entry>string</entry>
1273         <entry></entry>
1274       </row>
1275       <row>
1276         <entry spanname="desc">
1277           const_cname
1278         </entry>
1279       </row>
1280       <row>
1281         <entry>copy_function </entry>
1282         <entry>class</entry>
1283         <entry>string</entry>
1284         <entry></entry>
1285       </row>
1286       <row>
1287         <entry spanname="desc">
1288           copy_function
1289         </entry>
1290       </row>
1291       <row>
1292         <entry>cprefix</entry>
1293         <entry>class, enum, namespace, struct</entry>
1294         <entry>string</entry>
1295         <entry></entry>
1296       </row>
1297       <row>
1298         <entry spanname="desc">
1299           cprefix
1300         </entry>
1301       </row>
1302       <row>
1303         <entry>default_value</entry>
1304         <entry>struct</entry>
1305         <entry>string - C value expression</entry>
1306         <entry>"FALSE"</entry>
1307       </row>
1308       <row>
1309         <entry spanname="desc">
1310           A C expression representing this type's default value. This
1311           is needed because ...
1312         </entry>
1313       </row>
1314       <row>
1315         <entry>delegate_target_pos</entry>
1316         <entry>constructor, delegate, method, parameter</entry>
1317         <entry>string</entry>
1318         <entry></entry>
1319       </row>
1320       <row>
1321         <entry spanname="desc">
1322           delegate_target_pos
1323         </entry>
1324       </row>
1325       <row>
1326         <entry>free_function</entry>
1327         <entry>class</entry>
1328         <entry>string</entry>
1329         <entry></entry>
1330       </row>
1331       <row>
1332         <entry spanname="desc">
1333           free_function
1334         </entry>
1335       </row>
1336       <row>
1337         <entry>get_value_function</entry>
1338         <entry>class, struct</entry>
1339         <entry>string - function name</entry>
1340         <entry>"g_value_get_boolean"</entry>
1341       </row>
1342       <row>
1343         <entry spanname="desc">
1344           <programlisting>
1345   <emphasis>type_cname</emphasis>get_value_function (const GValue *value);
1346           </programlisting>
1347
1348           A function which will return an object when passed a
1349           GValue. This is used ...
1350         </entry>
1351       </row>
1352       <row>
1353         <entry>has_type_id</entry>
1354         <entry>class, enum</entry>
1355         <entry>string</entry>
1356         <entry></entry>
1357       </row>
1358       <row>
1359         <entry spanname="desc">
1360           has_type_id
1361         </entry>
1362       </row>
1363       <row>
1364         <entry>instance_pos</entry>
1365         <entry>constructor, delegate, method</entry>
1366         <entry>string</entry>
1367         <entry></entry>
1368       </row>
1369       <row>
1370         <entry spanname="desc">
1371           instance_pos
1372         </entry>
1373       </row>
1374       <row>
1375         <entry>lower_case_cprefix</entry>
1376         <entry>class, enum, interface, namespace</entry>
1377         <entry>string</entry>
1378         <entry></entry>
1379       </row>
1380       <row>
1381         <entry spanname="desc">
1382           lower_case_cprefix
1383         </entry>
1384       </row>
1385       <row>
1386         <entry>marshaller_type_name</entry>
1387         <entry>class, struct</entry>
1388         <entry>string</entry>
1389         <entry>"BOOLEAN"</entry>
1390       </row>
1391       <row>
1392         <entry spanname="desc">
1393           Don't know yet.
1394         </entry>
1395       </row>
1396       <row>
1397         <entry>ref_function</entry>
1398         <entry>class</entry>
1399         <entry>string</entry>
1400         <entry></entry>
1401       </row>
1402       <row>
1403         <entry spanname="desc">
1404           ref_function
1405         </entry>
1406       </row>
1407       <row>
1408         <entry>sentinel</entry>
1409         <entry>constructor, method</entry>
1410         <entry>string</entry>
1411         <entry></entry>
1412       </row>
1413       <row>
1414         <entry spanname="desc">
1415           sentinel
1416         </entry>
1417       </row>
1418       <row>
1419         <entry>set_value_function</entry>
1420         <entry>class, struct</entry>
1421         <entry>string - function name</entry>
1422         <entry>"g_value_set_boolean"</entry>
1423       </row>
1424       <row>
1425         <entry spanname="desc">
1426           <programlisting>
1427   void set_value_function (GValue *value, <emphasis>type_cname</emphasis> v);
1428           </programlisting>
1429
1430           A function that will set a GValue with an object of this
1431           type. This is used ...
1432         </entry>
1433       </row>
1434       <row>
1435         <entry>skip</entry>
1436         <entry>parameter</entry>
1437         <entry>string</entry>
1438         <entry></entry>
1439       </row>
1440       <row>
1441         <entry spanname="desc">
1442           skip
1443         </entry>
1444       </row>
1445       <row>
1446         <entry>type_cname</entry>
1447         <entry>interface</entry>
1448         <entry>string</entry>
1449         <entry></entry>
1450       </row>
1451       <row>
1452         <entry spanname="desc">
1453           type_cname
1454         </entry>
1455       </row>
1456       <row>
1457         <entry>type_id</entry>
1458         <entry>class, enum, struct</entry>
1459         <entry>string - </entry>
1460         <entry>"G_TYPE_BOOLEAN"</entry>
1461       </row>
1462       <row>
1463         <entry spanname="desc">
1464           The GObject type system type that this object is registered
1465           with. If <code>type_id</code> is not specified, Vala uses a
1466           type ID based on the type's name.
1467         </entry>
1468       </row>
1469       <row>
1470         <entry>unref_function</entry>
1471         <entry>class</entry>
1472         <entry>string</entry>
1473         <entry></entry>
1474       </row>
1475       <row>
1476         <entry spanname="desc">
1477           unref_function
1478         </entry>
1479       </row>
1480       <row>
1481         <entry>vfunc_name</entry>
1482         <entry>constructor, method</entry>
1483         <entry>string</entry>
1484         <entry></entry>
1485       </row>
1486       <row>
1487         <entry spanname="desc">
1488           vfunc_name
1489         </entry>
1490       </row>
1491     </tbody>
1492   </tgroup>
1493   </table>
1494 </sect2>
1495
1496 </sect1>
1497
1498 <sect1 id="ch-libgee"><title>libgee Internal</title>
1499
1500 <para>
1501    What is the difference between external and internal libgee?
1502 </para>
1503 </sect1>
1504
1505 <sect1><title>Other Tools</title>
1506
1507 <sect2 id="ch-vapigen"><title>vapigen</title>
1508 <para></para>
1509 </sect2>
1510
1511 <sect2 id="ch-gen-project"><title>gen-project</title>
1512 <para></para>
1513 </sect2>
1514
1515 <sect2 id="ch-gen-introspect"><title>vala-gen-introspect</title>
1516 <para></para>
1517 </sect2>
1518 </sect1>
1519
1520 <sect1 id="ch-testing"><title>Testing</title>
1521
1522 <para>
1523   A goal for Vala 1.0 is to have every tests for every documented
1524   feature of the language.
1525 </para>
1526 </sect1>
1527
1528 <sect1 id="ch-docs"><title>Documentation</title>
1529
1530 <para>
1531   XML sources for the Vala Reference are in the
1532   <filename>doc/vala</filename> directory. You can rebuild the docs by
1533   cd'ing into <filename>doc/vala</filename> and typing
1534   <userinput>make</userinput>. Currently the conversion to HTML is
1535   done using xsltproc and a simple stylesheet.
1536 </para>
1537
1538 <para>
1539   Docbook XML sources for the Hackers' Guide are in
1540   <filename>doc/hackers</filename>. HTML documentation is built by
1541   default. This document can be rebuilt by running
1542   <userinput>make</userinput> in <filename>doc/hackers</filename>.
1543 </para>
1544
1545 <para>
1546    Generated binding documentation - fixme.
1547 </para>
1548
1549 <para>
1550    libvala documentation - fixme.
1551 </para>
1552
1553 <para>
1554    <ulink
1555    url="http://live.gnome.org/Vala">http://live.gnome.org/Vala</ulink>
1556    - The Wiki is open to anyone who would like to make a quality
1557    contribution.
1558 </para>
1559 </sect1>
1560
1561 <sect1><title>Build System</title>
1562
1563 <para>
1564    Vala is built using the standard GNU Autotools. The built
1565    executables are actually stored in <filename>.libs</filename>
1566    directories and wrapped by scripts. Therefore to debug, follow
1567    these instructions fixme.
1568 </para>
1569
1570 <para>
1571   <command>./configure</command> uses the
1572   <varname>AC_PATH_PROG</varname> macro to choose the
1573   <command>valac</command> which is on your path, or one specified in
1574   the <varname>VALAC</varname> environment variable. Therefore, to
1575   build Vala with your own <command>valac</command>, type this, for
1576   example:
1577
1578   <screen>
1579     VALAC=$HOME/dev/vala-0.20/compiler/valac ./configure --prefix=$HOME/prefix
1580   </screen>
1581 </para>
1582
1583 <sect2><title>Out-of-tree build</title>
1584
1585 <para>
1586   An out-of-tree build does not properly work yet. Out-of-tree
1587   builds have the advantage that your source tree is not cluttered
1588   with built files. Suppose you have vala checked out in
1589   <filename>~/dev/valatrunk</filename>.
1590 </para>
1591
1592 <screen>
1593     rodney@solaria:~/dev % svn co http://svn.gnome.org/svn/vala/trunk valatrunk
1594     rodney@solaria:~/dev % ls valatrunk
1595 fixme           fixme          fixme                  fixme
1596 aclocal.m4      config.log     gobject-introspection  README
1597 AUTHORS         config.status  INSTALL                stamp-h1
1598 autogen.sh      config.sub     install-sh             tests
1599 autom4te.cache  configure      libtool                vala
1600 ccode           configure.ac   ltmain.sh              vala-1.0.pc
1601 ChangeLog       COPYING        MAINTAINERS            vala-1.0.pc.in
1602 compile         depcomp        Makefile               vapi
1603 compiler        doc            Makefile.am            vapigen
1604 config.guess    gee            Makefile.in            ylwrap
1605 config.h        gen-project    missing
1606 config.h.in     gobject        NEWS
1607 fixme           fixme          fixme                  fixme
1608     rodney@solaria:~/dev % mkdir buildvala
1609     rodney@solaria:~/dev % cd buildvala
1610     rodney@solaria:~/dev/buildvala % ../valatrunk/autogen.sh --prefix=$HOME/dev/prefix
1611     rodney@solaria:~/dev/buildvala % make
1612 </screen>
1613
1614 <para>
1615     All <filename>Makefile</filename>s, etc, generated by configure
1616     will be put in the <filename>buildvala</filename> directory and
1617     you can run make directly from there.
1618 </para>
1619 </sect2>
1620 </sect1>
1621
1622 <sect1><title>Directory Index</title>
1623
1624 <informaltable frame='none'>
1625 <tgroup cols='2'>
1626 <tbody>
1627 <row><entry><filename>gen-project</filename></entry>
1628 <entry><xref linkend="ch-gen-project"/></entry></row>
1629 <row><entry><filename>gen-project/licenses</filename></entry>
1630 <entry><xref linkend="ch-gen-project"/></entry></row>
1631 <row><entry><filename>vapi</filename></entry>
1632 <entry><xref linkend="ch-vapi"/></entry></row>
1633 <row><entry><filename>vapi/packages</filename></entry>
1634 <entry><xref linkend="ch-vapi"/></entry></row>
1635 <row><entry><filename>gee</filename></entry>
1636 <entry><xref linkend="ch-libgee"/></entry></row>
1637 <row><entry><filename>gobject</filename></entry>
1638 <entry><xref linkend="ch-codegen"/></entry></row>
1639 <row><entry><filename>doc</filename></entry>
1640 <entry><xref linkend="ch-docs"/></entry></row>
1641 <row><entry><filename>doc/hackers</filename></entry>
1642 <entry><xref linkend="ch-docs"/></entry></row>
1643 <row><entry><filename>doc/vala</filename></entry>
1644 <entry><xref linkend="ch-docs"/></entry></row>
1645 <row><entry><filename>vapigen</filename></entry>
1646 <entry><xref linkend="ch-vapigen"/></entry></row>
1647 <row><entry><filename>vapigen/vala-gen-introspect</filename></entry>
1648 <entry><xref linkend="ch-gen-introspect"/></entry></row>
1649 <row><entry><filename>compiler</filename></entry>
1650 <entry><xref linkend="ch-valac"/></entry></row>
1651 <row><entry><filename>vala</filename></entry>
1652 <entry><xref linkend="ch-valac"/></entry></row>
1653 <row><entry><filename>gobject-introspection</filename></entry>
1654 <entry><xref linkend=""/></entry></row>
1655 <row><entry><filename>ccode</filename></entry>
1656 <entry><xref linkend="ch-codegen"/></entry></row>
1657 <row><entry><filename>tests</filename></entry>
1658 <entry><xref linkend="ch-testing"/></entry></row>
1659 </tbody>
1660 </tgroup>
1661 </informaltable>
1662
1663 </sect1>
1664
1665 <sect1><title>Index</title>
1666 <para>
1667    Should automatically generate this from Docbook.
1668 </para>
1669 </sect1>
1670
1671 <sect1><title>GNU Free Documentation License</title>
1672
1673 <para>
1674   etc.
1675 </para>
1676 </sect1>
1677
1678 <!--
1679 * Junk
1680
1681 ** CCodeNodes
1682
1683 public class Vala.CCodeTypeDefinition : CCodeNode
1684 public class Vala.CCodeMacroReplacement : CCodeNode
1685 public class Vala.CCodeStruct : CCodeNode
1686 public class Vala.CCodeFragment : CCodeNode
1687 public class Vala.CCodeFormalParameter : CCodeNode
1688 public class Vala.CCodeFunction : CCodeNode
1689 public class Vala.CCodeNewline : CCodeNode
1690 public class Vala.CCodeEnumValue : CCodeNode
1691 public abstract class Vala.CCodeDeclarator : CCodeNode
1692 public class Vala.CCodeComment : CCodeNode
1693 public abstract class Vala.CCodeExpression : CCodeNode
1694 public class Vala.CCodeLineDirective : CCodeNode
1695 public abstract class Vala.CCodeStatement : CCodeNode
1696 public class Vala.CCodeEnum : CCodeNode
1697 public class Vala.CCodeIncludeDirective : CCodeNode
1698 -->
1699 </article>