View source for GDC Development

= Developer Documentation =

At the moment, documentation for GDC, especially the internals, is sparse.
The DMD frontend and the GCC internals aren't very well documented either.
This page will hopefully help provide insight on GDC's internals.

----

== GDC Internals ==

GDC is essentially divided into 3 parts.

* The DMD Frontend
* GCC's Internals
* GDC's glue code

=== The DMD frontend ===

* The dmd and dmd2 subfolders contain D1 and D2 frontend source code respectively.
* On Wiki4D, there is the start of a  [//prowiki.org/wiki4d/wiki.cgi?DMDSourceGuide DMD Source Guide] to look at for now.
* In DMD, mars.c holds the main function for compiler. In GDC, this is surrounded #ifndef IN_GCC, meaning that if we are using GCC, don't compile that part in. The main for GDC function can be found gcc/main.c. It calls the toplev_main() function in gcc/toplev.c, which uses a generic main function for GCC front ends that don't implement their own.

=== GCC's Internals ===

* http://gcc.gnu.org/wiki/GettingStarted

=== GDC's glue code ===

* This is the bridge between the DMD frontend and GCC
* Read the [[http://prowiki.org/wiki4d/wiki.cgi?DMDSourceGuide | DMD Source Guide]], especially section Intermediate representation as a start.
* Also look at the [[GDCHacking | GDC Hacking]] entry for information about GDC's glue code.

==== Files ====

* d-codegen[.cc/.h]:
** Implements IRState.

* d-glue.cc:
** Implements all the methods described there in the DMD source guide, including all Statement::toIR and Expression::toElem methods thus, replacing dmd's toelem.c, e2ir.c, s2ir.c, etc.

* d-irstate[.cc/.h]:
** Simliar to irstate[.c/.h] in DMD's source, but not quite. In DMD, irstate[.c/.h] are only for the struct IRState, and do not inherit from any other structs. In GDC, d-irstate[.cc/.h] implements "IRBase", which inherits from Object. In d-codegen[.cc/.h], IRState is then implemented.

----

== Updating GDC ==

=== Merging a new DMD/Phobos version ===

When a new DMD version is out, we will try to get GDC up to date as soon as possible. The instructions are as follows: (From David Friedman)

<pre>
1. Extract the new dmd-xxx.zip package.

2. Diff the compiler source from the previously merged dmd version (not 
gdc's d/dmd or d/dmd2 directory).  You may have to fix line endings in 
the new dmd source to get a clean diff.

3. Depending on the nature of the changes, it may be possible to simply 
apply the changes to the gdc version as a patch.  Otherwise, make 
changes manually. 

Because some of the changes I made a pretty drastic, it will probably be 
easier to applies these incremental changes to gdc rather than try to 
re-apply my changes to the original dmd code.

4. Get the new compiler working and run regression tests.

5. Do steps 2 and 3 for Phobos.  It helps to work on the compiler and 
Phobos separately. Sometimes compiler changes will require the new 
runtime library to work correctly, however.

Also, I don't merge too many versions at a time.  For example, I would 
probably do  2.015, 2.016+2.017, and then 2.018.  The array operations 
in 2.018 should well tested before moving on.

I don't really have any other documentation.  I do have some scripts to 
help with the diffing process.

David
</pre>

If you are using D2, you will also need to repeat the process for Druntime.

You can find all the DMD, Phobos, and Druntime versions in the [[http://ftp.digitalmars.com/|Digitalmars FTP]].

To create a more readable diff you can use this command:
<syntaxhighlight lang="bash">
diff -Naruw dmdX dmdX+1 > dmdX-to-dmdX+1.patch
</syntaxhighlight>

Where **X** is a dmd version.

To apply the generated patch in the most automatic way run patch as follows in the corresponding DMD or Phobos dir:
<syntaxhighlight lang="bash">
patch -p4 -l -F 3 --verbose < dmdX-to-dmdX+1.patch
</syntaxhighlight> 

It will patch all the files it can, and will place all the statement that can't be merged in **file.rej** where file is a filename.

=== Merging a new GCC version ===

New GCC versions come out on occasion as well, but can require a bit more work to set up than a new DMD version. Usually, you only need to make patches for a 4.x version, and not for every 4.x.x version. Here are the instructions given from David Friedman:

<pre>
The first thing to do is modify d/setup-gcc.sh to allow building with 
the new version.

Next, you should try to apply the set of patches in d/patches/ for the 
previous version.  For the top-level-xxx patch, just manually apply the 
changes to Makefile.def and configure.ac.  You will need to get the 
autogen package to rebuild Makefile.in.  Rebuilding the top-level 
'configure' script with autoconf may be tricky, so you just apply the 
one-line change directly to 'configure'.

You probably will need to create a d-bi-attrs-4x.h.  This is select 
portion of gcc/c-common.c modified to for D.  (Conditionally) included 
it in d-builtins.c.

Most of the work is then getting GDC to work correctly.  Any changes you 
make that are version specific should probably involve the use of the 
D_GCC_VER macro.  Search for "D_GCC_VER" to get a feel for what you will 
need to do.

Once you gotten everything working and are done making changes to the 
GCC sources, you need to create a set of patches for the new version.  
The for FSF GCC, there are two patches: One is the top-level, 
'patch-toplev-<version>'.  The other is for thee gcc/ directory 
'patch-gcc-<version>'.
</pre>

You can find GCC versions in the [//ftp.gnu.org/gnu/gcc GNU FTP].

----

== Repository Guidelines ==

These are the repository guidelines that a committer should follow while committing to the GDC repository.

The '''default''' branch must never be broken but should contain a working version of the compiler. If you want to develop a new feature or do a merging with a newer GCC or DMD or Phobos, it's strongly encuraged that you create your own branch. If you don't know about mercurial branches, [[this small tutorial will fill all the knowledge requirements to create a new branch|http://hgbook.red-bean.com/read/managing-releases-and-branchy-development.html]]. 

It's better if you give to your branch a short name representing the topic of that branch. You can commit in anytime to that branch and broke it, people interested in the same feature will work in the same branch. When a feature is fully developed and stable, where stable means that it compiles, it can be merged to the '''default''' branch. After the merging, before the default branch is committed to the central repository, you have to build and test that the '''default''' branch compiles too.

After that you can delete your branch from the repository.

----

== External Links ==

For what may not have been explained here well enough, here are some other links that have some useful information:

[//prowiki.org/wiki4d/wiki.cgi?GdcHacking GDC Hacking]

[//prowiki.org/wiki4d/wiki.cgi?DMDSourceGuide DMD Source Guide]

[//gcc.gnu.org/wiki GCC Wiki]

[//blog.lxgcc.net/?page_id=116 GCC front-end guide]