Add Compiler Guide (#33)

source/contributor-guide/compiler-guide.rst

@@ -0,0 +1,56 @@
+Compiler Guide
+==============
+
+The goal of this document is to provide a single point of information for developers interested in improving Vala.
+
+It is hoped that this document will encourage more Vala users to contribute to Vala by finding/fixing bugs, writing documentation, writing test-cases, and implementing new features.
+
+In the opinion of this document's author, a quality Vala 1.0 is an important part of the future of the GNOME Platform, because it will simplify the task of creating and maintaining excellent language-neutral libraries, which are necessary for the next generation of applications.
+
+The Vala code is fresh, and easy to read. The variable and class names are descriptive, and one often has a general feel of what the code is supposed to do, so the sparse comments are generally not a problem. However, because it is a compiler, Vala is inevitably long, and its call stack deep. This document should provide a high-level view of how Vala is put together.
+
+This document has been ported from docbook to this wiki in order to be team-maintained and more up-to-date with latest releases of the Vala compiler.
+
+
+License
+-------
+
+The complete text of the GNU Free Documentation License can be found here: `<http://www.gnu.org/licenses/fdl.html>`_.
+
+Acknowledgements
+----------------
+
+This document was originally created in 2008 and updated in 2010. Acknowledgements to the original authors:
+
+**Rodney Lorrimar**
+
+Document Author
+
+**Jürg Billeter**
+
+Vala Author
+
+**Raffaele Sandrini**
+
+Vala Author
+
+**Philip van Hoof**
+
+Contribution of the building Vala section.
+
+Edited by
+~~~~~~~~~
+
+Rodney Lorrimar <[email protected]>
+
+Luca Bruno <[email protected]>
+
+Chapters
+--------
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+   :numbered:
+
+   compiler-guide/*

source/contributor-guide/compiler-guide/01-00-project-information.rst

@@ -0,0 +1,20 @@
+Project Information
+===================
+
+Website, Mailing List, Bug Tracker, Matrix Room
+-----------------------------------------------
+
+* `<https://vala.dev>`_
+* GNOME GitLab issues - `<https://gitlab.gnome.org/GNOME/vala/issues>`_
+* `Vala Matrix Room <https://matrix.to/#/#vala:gnome.org>`_
+
+Project Maintainers
+-------------------
+The principal authors and project maintainers are Jürg Billeter and Raffaele Sandrini.
+
+License
+-------
+
+Vala compiler is licensed under LGPL 2.1, so that proprietary programs compiled with Vala can be distributed under different licenses and possibly without source code.
+
+

source/contributor-guide/compiler-guide/02-00-environment-setup.rst

@@ -0,0 +1,60 @@
+Environment Setup
+=================
+
+Compiling from the Source Repository
+------------------------------------
+
+The `Vala README.md <https://gitlab.gnome.org/GNOME/vala/blob/master/README.md>`_ file contains full and up to date instructions on how to download and compile Vala from the git repository.
+
+
+Setting up your editor
+--------------------------
+
+A :doc:`list of IDE(s) </tooling/ide-support>` with Vala support is available.
+
+Vala support is available also for `build tools and editors <Vala/Tools#Tool_Support>`_.
+
+Files
+-----
+
+Vala source files are named in the GTK+ style, i.e. all lowercase, with no separators between words, in the format namespaceclassname.vala. For example, the filename for Vala.FormalParameter is valaformalparameter.vala.
+
+For the Vala compiler and library there is only one namespace, and it is called "Vala". Don't put "using Vala;"; instead qualify the name of types you declare. For example "class Vala.FormalParameter : Symbol".
+
+Coding Style
+------------
+
+The coding style used in Vala itself seems to be a variation of the GTK+ coding style.
+
+* Tabs rather than spaces.
+* Tab width unspecified, but 4 works well.
+* Hanging braces.
+* Cuddled else.
+* Braces necessary for single-line blocks.
+* Variable and method identifiers in lowercase, words seperated by underscores.
+* Type identifiers in CamelCase.
+* Enum members and constants in ALL_CAPS, words seperated by underscores.
+* C-style `/* comments. */`
+* Hungarian notation not used.
+* Variables are often declared with implicit type (i.e. `var foo = new Foo ()`).
+* No line-length limit.
+* No function-length limit.
+* Space between method name and parameters' opening parenthesis.
+* Property `get`, `set`, `default` declaration all on one line, seperated by semicolons, if default implementations are used.
+* If properties have implementations, then `get {`, `set {` open new lines.
+* Attributes on their own line.
+* JavaDoc-style commenting on types, methods, variables.
+* Header at top of file contains:
+
+.. code-block:: vala
+
+   /* filename.vala
+    *
+    * Copyright (C) 20yy-20yy  Copyright Holder <email@address>
+    *
+    * License text.
+    *
+    * Author:
+    * 	Programmer Name <programmer@email>
+    */
+

source/contributor-guide/compiler-guide/03-00-the-vala-compiler.rst

@@ -0,0 +1,10 @@
+The Vala Compiler
+=================
+
+I suppose the best place to start is valac, the tool which Vala programmers know the best.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   03-00-the-vala-compiler/*

source/contributor-guide/compiler-guide/03-00-the-vala-compiler/03-01-vala-in-a-nutshell.rst

@@ -0,0 +1,57 @@
+Vala in a Nutshell
+==================
+
+The Vala compiler **valac** is a small shell around libvala which handles command-line arguments, locates the sources and libraries which are required, and drives the compilation procedure.
+
+**How valac is linked**
+
+.. image:: assets/valac-link.png
+   :alt: How valac is linked
+
+All the important work such as parsing, error checking/reporting, code generation, calling **gcc**, is done in libvala.
+
+The code for **valac** can be found in ``compiler/valacompiler.vala``.
+
+Command-line Options
+--------------------
+
+These are handled in the normal way by the Vala binding to *GLib.OptionContext*. Most of the instance variables in Vala.Compiler are referenced in the options array. It's not very interesting.
+
+The Compilation Procedure and Vala.CodeContext
+----------------------------------------------
+
+Vala.Compiler plugs together the classes of libvala in a big pipeline. This modular design makes Vala more maintainable and external tools can easily use this code.
+
+The valac Pipeline
+------------------
+
+1. Initialize CodeContext with command-line options.
+2. Add packages from command-line and others depending on the profile.
+3. Add sources, Vala, Genie, Gir, VAPI, and C from command-line.
+4. Parse everything.
+5. Resolve symbols.
+6. Run the Semantic Analyzer.
+7. Run the Flow Analyzer.
+8. Use the code generator to emit code.
+9. Write out VAPI and GIDL files, if a library is being compiled.
+10. Compile the generated C code.
+
+The individual steps will be explained later, but first ``Vala.CodeContext``, the data structure which holds everything together. It stores the compile options which were specified on the command line, and a list of source files to compile. There is only one ``CodeContext`` instantiated and its reference is passed around a lot, so effectively it's a global variable.
+
+Vala.CodeContext is the root of the code tree, because it contains the root Namespace, which holds references to all parsed code nodes. In addition to the code tree, the context contains a reference to a code generator object. This object walks the code tree and generates code.
+
+Vala.CodeContext contains an important method called ``accept``, which initiates a depth-first traversal of the code tree. This method, and the CodeVisitor pattern will be discussed later.
+
+**Data diagram**
+
+.. image:: assets/valac-data.png
+   :alt: Data diagram
+
+The Vala code tree is an abstract syntax tree (AST) built by parsing the Vala sources. For example, if you see a class called ``Vala.Destructor`` which inherits ``Vala.Symbol``, then it is a part of the AST. Data structures for the AST and the parser which builds it are in the ``vala`` directory.
+
+Vala also uses a tree to represent the C ``ccode`` that will be output. Data structures for the C code (CCode classes) tree are in the ``ccode`` directory.
+
+The machinery which transforms the Vala AST into a C code tree is in the ``codegen`` directory arranged in a modular visitor. The AST is traversed and a CCode tree is created.
+
+Vala is split upon these lines, most probably to break the system into conceptually-related, understandable chunks. However, with suitable modifications, the different modules could be replaced. Conceivably, Vala could produce non-GObject C code. More realistically, Vala could produce intermediate code as a `GCC frontend <http://gcc.gnu.org/frontends.html>`_.
+