|
| 1 | +## The GDC D Compiler |
| 2 | +[](https://buildkite.com/d-programming-gdc/gcc) |
| 3 | +[](https://cirrus-ci.com/github/D-Programming-GDC/gcc/ci/mainline) |
| 4 | +[](https://gcc.gnu.org/bugzilla/buglist.cgi?component=d&list_id=299901&product=gcc&resolution=---) |
| 5 | +[](https://github.com/D-Programming-GDC/gcc/blob/ci/mainline/COPYING) |
| 6 | + |
| 7 | +GDC is the GCC-based [D language][dlang] compiler, integrating the open source [DMDFE D][dmd] front end |
| 8 | +with [GCC][gcc] as the backend. The GNU D Compiler (GDC) project was originally started by David Friedman |
| 9 | +in 2004 until early 2007 when he disappeared from the D scene, and was no longer able to maintain GDC. |
| 10 | +Following a revival attempt in 2008, GDC is now under the lead of Iain Buclaw who has been steering the |
| 11 | +project since 2009 with the assistance of its contributors, without them the project would not have been |
| 12 | +nearly as successful as it has been. |
| 13 | + |
| 14 | +Documentation on GDC is available from [the wiki][wiki]. Any bugs or issues found with using GDC should |
| 15 | +be reported at [the GCC bugzilla site][bugs] with the bug component set to `d`. For help with GDC, the |
| 16 | +[D.gnu][maillist] mailing list is the place to go with questions or problems. There's also a GDC IRC |
| 17 | +channel at #d.gdc on FreeNode. Any questions which are related to the D language, but not directly to |
| 18 | +the GDC compiler, can be asked in the [D forums][dforum]. You can find more information about D, including |
| 19 | +example code, API documentation, tutorials and these forums at the [main D website][dlang]. |
| 20 | + |
| 21 | +### Building GDC |
| 22 | + |
| 23 | +Stable GDC releases for production usage should be obtained by downloading stable GCC sources |
| 24 | +from the [GCC downloads][gcc-download] site. |
| 25 | +For the latest experimental development version, simply download a [GCC snapshot][gcc-snapshot] or |
| 26 | +checkout the GCC Git repository. Most GDC development directly targets the GCC Git repository, |
| 27 | +so the latest GDC version is always available in the GCC Git. |
| 28 | +Do not use the `ci/mainline` branch in this repository, as it is rebased regularly and contains exclusively |
| 29 | +CI related changes. |
| 30 | + |
| 31 | +During certain development phases (e.g. when GCC is in a feature freeze) larger GDC changes may be staged |
| 32 | +to the `devel/gdc` branch. This branch is rebased irregularly, do not rely on the commit ids to be |
| 33 | +stable. |
| 34 | + |
| 35 | +If you need to clone this repo for some reason, you may want to do a shallow clone using the |
| 36 | +`--depth 1 --no-single-branch` git options, as this repository is large. To compile GDC, add `--enable-languages=d` to the GCC configure flags and [start building][gdc-build]. |
| 37 | + |
| 38 | +### Using GDC |
| 39 | + |
| 40 | +Usage information can be found at ... |
| 41 | + |
| 42 | +### Contributing to GDC |
| 43 | + |
| 44 | +Starting with GCC 9.0.0, GDC has been merged into upstream GCC and all GDC development now follows the usual |
| 45 | +GCC development process. Changes to GDC and related code can therefore be submitted |
| 46 | +to the [gcc-patches mailing list][patches-ml] for review. |
| 47 | + |
| 48 | +It is possible to directly post patches to the [mailing list][patches-ml] and not to use this repository at all. |
| 49 | +We however recommend using this repository to make use of the CI checks and the github review workflow. |
| 50 | + |
| 51 | +#### Submitting Changes |
| 52 | + |
| 53 | +To submit changes to GDC, simply fork this repository, create a new feature branch based on the `ci/mainline` branch, |
| 54 | +then open a pull request against the **mainline** branch. We recommend using full clones for development, allthough |
| 55 | +using shallow clones should also be possible. In code: |
| 56 | + |
| 57 | +```bash |
| 58 | +# Initial one time setup: |
| 59 | +# For repository on github, then clone your fork |
| 60 | +git clone git@github.com:[you]/gcc.git |
| 61 | +cd gcc |
| 62 | +# Add the gdc repository as a remote |
| 63 | +git remote add gdc git@github.com:D-Programming-GDC/gcc.git |
| 64 | + |
| 65 | +# Do this for every patch: |
| 66 | +# Fetch latest upstream changes |
| 67 | +git remote update |
| 68 | +# Base a new branch on gdc/mainline |
| 69 | +git checkout gdc/ci/mainline |
| 70 | +git checkout -b pr12345 |
| 71 | +# Make changes, commit |
| 72 | +git commit [...] |
| 73 | +git push origin pr12345:pr12345 |
| 74 | +# Open a pull request on github, target branch: mainline |
| 75 | +``` |
| 76 | +Opening a pull request will automatically trigger our CI and test your changes on various machines. |
| 77 | + |
| 78 | +#### Changelogs |
| 79 | +The GCC project requires keeping changes in the `Changelog` files. GCC ships a script which can generate |
| 80 | +Changelog templates for us if we feed it a diff: |
| 81 | +```bash |
| 82 | +git diff gdc/ci/mainline | ./contrib/mklog |
| 83 | +``` |
| 84 | +*Note:* The above command generates the diff between `gdc/ci/mainline` and your local branch. If `gdc/ci/mainline` was |
| 85 | +updated and you did a `git remote update`, `gdc/mainline` may have changes which are not yet in your branch. |
| 86 | +In that case, rebase onto `gdc/mainline` first. |
| 87 | + |
| 88 | +The command outputs something like this: |
| 89 | +``` |
| 90 | +ChangeLog: |
| 91 | +
|
| 92 | +2019-02-03 Johannes Pfau <johannespfau@example.com> |
| 93 | +
|
| 94 | + * test.d: New file. |
| 95 | +
|
| 96 | +gcc/d/ChangeLog: |
| 97 | +
|
| 98 | +2019-02-03 Johannes Pfau <johannespfau@example.com> |
| 99 | +
|
| 100 | + * dfile.txt: New file. |
| 101 | +
|
| 102 | +libphobos/ChangeLog: |
| 103 | +
|
| 104 | +2019-02-03 Johannes Pfau <johannespfau@example.com> |
| 105 | +
|
| 106 | + * phobosfile.txt: New file. |
| 107 | +
|
| 108 | +``` |
| 109 | + |
| 110 | +The `ChangeLog:`, `libphobos/ChangeLog:` part gives the file into which the following changes need to be added. |
| 111 | +Complete the changelog text and use the existing entries in the files for reference or see |
| 112 | +the [GCC][changelog-doc] and [GNU][changelog-doc2] documentation. Also make sure to adhere to the line length limit of 80 characters. Then make the changelog somehow available for review: |
| 113 | +Either commit the files, or preferable, just copy and paste the edited text output of `mklog` into your |
| 114 | +pull request description. |
| 115 | + |
| 116 | + |
| 117 | +### Getting Changes Into GCC Git |
| 118 | + |
| 119 | +After changes have been reviewed on github, they have to be pushed into the GCC Git. Pull requests will |
| 120 | +not get merged into this repository. The following steps can be handled by GDC maintainers, although it is |
| 121 | +possible to perform these by yourself as well. |
| 122 | + |
| 123 | +##### Sumbitting to the gcc-patches Mailing List |
| 124 | + |
| 125 | +Once the review and CI have passed on the github pull request page, the changes need to be submitted to the |
| 126 | +`gcc-patches` mailing list. This can easily be done using [git send-email][git-send-email]: |
| 127 | + |
| 128 | +1. You might want to squash the commits. Each commit will become one email/patch so it might make sense |
| 129 | + to combine commits here. |
| 130 | +2. The changelog should preferrably be pasted into the email text, so do not include |
| 131 | + commits modifying the changelog files. |
| 132 | +3. If you had to regenerate any autogenerated files (e.g. configure from configure.ac) |
| 133 | + you may keep these changes out of the patch for simplified review. The generated files |
| 134 | + should still be present in the changelog. |
| 135 | + |
| 136 | +You'll have to configure `git send-email` once after you checked out the repository: |
| 137 | +```bash |
| 138 | +git config sendemail.to gcc-patches@gcc.gnu.org |
| 139 | +``` |
| 140 | +If you never used `git send-email` before, you'll also have to setup the SMTP settings once. |
| 141 | +See [here][git-send-email] for details. |
| 142 | + |
| 143 | +Now to send the patches: |
| 144 | +```bash |
| 145 | +# Check which commits will be sent: |
| 146 | +git log gdc/ci/mainline.. |
| 147 | +# Check the complete diff which will be sent: |
| 148 | +git diff gdc/ci/mainline.. |
| 149 | +# Dry run to verify everything again |
| 150 | +git send-email gdc/ci/mainline --annotate --dry-run |
| 151 | +# Send the patches |
| 152 | +git send-email gdc/ci/mainline --annotate |
| 153 | +``` |
| 154 | + |
| 155 | +If you send multiple patches and want to write an introduction email, use the `--compose` argument for |
| 156 | +`git send-email`. You can also generate patch files like this: |
| 157 | +```bash |
| 158 | +git format-patch gdc/ci/mainline.. |
| 159 | +# Edit the *.patch files, add messages etc. |
| 160 | +# Now send the patches |
| 161 | +git send-email *.patch --dry-run |
| 162 | +git send-email *.patch |
| 163 | +``` |
| 164 | + |
| 165 | +##### Pushing Changes to Git |
| 166 | + |
| 167 | +This section is only relevant for GDC maintainers with GCC Git write access. There are certain rules when |
| 168 | +pushing to Git, usually you're only allowed to push **after** the patches have been reviewed on the mailing list. |
| 169 | +Refer to the [GCC documentation][gcc-git] for details. |
| 170 | + |
| 171 | +### Repository Information |
| 172 | + |
| 173 | +This repository is a fork of the [GCC git mirror][gcc-github]. |
| 174 | + |
| 175 | +#### Directory Structure |
| 176 | + |
| 177 | +All code branches contain the complete GCC tree. D sources are in `gcc/d` for the compiler |
| 178 | +and in `libphobos` for the runtime library. Changes to files in `gcc/d/dmd` or `libphobos` |
| 179 | +should be submitted to the [upstream dlang repositories][dlang-github] first if possible. |
| 180 | +Refer to [gcc/d/README.gcc][gcc-d-readme] for more details. |
| 181 | + |
| 182 | +#### Branches |
| 183 | + |
| 184 | +Branches in this repository are organized in the following way: |
| 185 | + |
| 186 | +* CI branches: The `ci/mainline` branch and release branches `ci/gcc-*` are based on the same |
| 187 | + branches in the upstream GCC git repository. The only changes compared to the upstream branches |
| 188 | + are CI-related setup commits. CI branches are updated automatically to be kept in sync with |
| 189 | + upstream and are rebased onto the upstream changes. These branches are effectively readonly: |
| 190 | + We never merge into the branches in this repository. The CI related changes make it possible |
| 191 | + to run CI based tests for any PR based on these branches, which is their sole purpose. |
| 192 | +* The `devel/gdc` branch: If GCC is in a late [development stage][gcc-stage] this branch can accumulate |
| 193 | + changes for the GCC release after the next one. It is essentially used to allow periodic merges from |
| 194 | + [upstream DMD][dlang-github] when GCC development is frozen. Changes in the GCC `mainline` branch |
| 195 | + are manually merged into this branch. When GCC enters stage 1 development again, this branch will be |
| 196 | + rebased and pushed to upstream `mainline`. After that, the branch in this repository will be **rebased** |
| 197 | + to mainline. |
| 198 | +* Backport branches: The `gcc-*-bp` branches contain D frontend and library feature updates for released GCC versions. |
| 199 | + Regression fixes should target the main `gcc-*-branch` branches instead, according to GCC rules. |
| 200 | + |
| 201 | + |
| 202 | + |
| 203 | +[home]: https://gdcproject.org |
| 204 | +[dlang]: https://dlang.org |
| 205 | +[gcc]: https://gcc.gnu.org |
| 206 | +[dforum]: https://forum.dlang.org |
| 207 | +[dmd]: https://github.com/dlang/dmd |
| 208 | +[wiki]: https://wiki.dlang.org/GDC |
| 209 | +[bugs]: https://gcc.gnu.org/bugzilla |
| 210 | +[maillist]: https://forum.dlang.org/group/D.gnu |
| 211 | +[email]: mailto:ibuclaw@gdcproject.org |
| 212 | +[gcc-devel]: https://gcc.gnu.org/git/?p=gcc.git;a=shortlog |
| 213 | +[patches-ml]: https://gcc.gnu.org/lists.html |
| 214 | +[gcc-github]: https://github.com/gcc-mirror/gcc |
| 215 | +[gcc-git]: https://gcc.gnu.org/gitwrite.html |
| 216 | +[gcc-stage]: https://www.gnu.org/software/gcc/develop.html |
| 217 | +[dlang-github]: https://github.com/dlang |
| 218 | +[gdc-build]: https://wiki.dlang.org/GDC/Installation/Generic |
| 219 | +[changelog-doc]: https://www.gnu.org/software/gcc/codingconventions.html#ChangeLogs |
| 220 | +[changelog-doc2]: https://www.gnu.org/prep/standards/standards.html#Change-Logs |
| 221 | +[git-send-email]: https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/ |
| 222 | +[gcc-download]: https://www.gnu.org/software/gcc/releases.html |
| 223 | +[gcc-d-readme]: https://github.com/D-Programming-GDC/gcc/blob/ci/mainline/gcc/d/README.gcc |
| 224 | +[gcc-snapshot]: https://www.gnu.org/software/gcc/snapshots.html |
0 commit comments