Difference between revisions of "LDC contributor's guide"

From D Wiki
Jump to: navigation, search
(APIs and idioms)
Line 21: Line 21:
  
 
=== APIs and idioms ===
 
=== APIs and idioms ===
* Avoid making changes to the front end sources (''dmd'' and ''dmd2'') as much as reasonably possible. If modifications are necessary, be sure to enclose the deviations from the upstream source <tt>#if IN_LLVM</tt> blocks, and keep the original source code around for easier comparison. This makes it much easier to resolve any merge conflicts when folding in new frontend releases.
+
* Avoid making changes to the front end sources (''dmd'' and ''dmd2'') as much as reasonably possible. If modifications are necessary, be sure to enclose the deviations from the upstream source <tt>#if IN_LLVM</tt> blocks, and keep the original source code around for easier comparison. Add a comment referring to the relevant issue on our tracker, or the upstream DMD commit in case of a straight backport. This makes it much easier to resolve any merge conflicts when folding in new frontend releases.
 
* Use [http://llvm.org/docs/doxygen/html/ErrorHandling_8h.html#ace243f5c25697a1107cce46626b3dc94 ''llvm_unreachable("message")''] instead of ''assert(0 && "message")'' (from ''llvm/Support/ErrorHandling.h''). Not only might it lead to slightly better codegen, it also prevents »variable might be used uninitialized« and similar compiler warnings.
 
* Use [http://llvm.org/docs/doxygen/html/ErrorHandling_8h.html#ace243f5c25697a1107cce46626b3dc94 ''llvm_unreachable("message")''] instead of ''assert(0 && "message")'' (from ''llvm/Support/ErrorHandling.h''). Not only might it lead to slightly better codegen, it also prevents »variable might be used uninitialized« and similar compiler warnings.
  

Revision as of 18:49, 26 April 2015

This page is a work-in-progress collection of tips for LDC contributors and development guidelines.

Continuous Integration

The LDC project uses two different CI systems: Travis CI, which is Ubuntu x86 only but also tests pull requests, and ci.lycus.org, which has three different x86_64 Linux slaves.

Any efforts to get regular builds running on Windows and OS X would be very much appreciated.

To run the test suite locally, use ctest (e.g. ctest -j3 --output-on-failure) in the CMake root directory. To work on a specific test case, you might want to look into the -R and --verbose options to ctest.

Style guidelines

Generally, use your good taste and try to use a style similar to the surrounding code. Many parts of the LLVM Coding Standards are directly applicable to LDC as well.

Formatting, etc.

  • Hard rules: 4 spaces for indentation, LF newlines.
  • Use include guards consistently, in the format LDC_<dir>_<filename>, e.g. LDC_GEN_DVALUE_H.
  • Includes are placed at the top of the file, sorted lexicographically and grouped in the following order:
    1. Main include corresponding to the .cpp file, if any.
    2. DMD and other LDC includes.
    3. LLVM/libconfig includes.
    4. System includes.

APIs and idioms

  • Avoid making changes to the front end sources (dmd and dmd2) as much as reasonably possible. If modifications are necessary, be sure to enclose the deviations from the upstream source #if IN_LLVM blocks, and keep the original source code around for easier comparison. Add a comment referring to the relevant issue on our tracker, or the upstream DMD commit in case of a straight backport. This makes it much easier to resolve any merge conflicts when folding in new frontend releases.
  • Use llvm_unreachable("message") instead of assert(0 && "message") (from llvm/Support/ErrorHandling.h). Not only might it lead to slightly better codegen, it also prevents »variable might be used uninitialized« and similar compiler warnings.

Merging a new DMD release

Eventually, we will want to write up a checklist of what to consider when merging a new frontend release. Right now, just a few points to consider:

  • Check if there were any new command line options added to DMD. if so, also handle them in LDMD.

Updating the dmd-testsuite repository

The dmd-testsuite repository is derived from the upstream DMD repository by the update-dmd-testsuite.sh script in the ldc-scripts repository. Just run it without arguments, and it should update the repository with the latest commits/tags (given that you have Git installed and an SSH key configured for github.com). The changes should apply to the remote repository in a fast-forward fashion, never force a push.

After this is done, when merging a new DMD frontend release, just merge the v2.<xyz> tag into the ldc branch, manually resolving any merge conflicts as necessary (most changes should definitely be upstreamed).

Releasing a new version of LDC

There is a separate page describing the LDC release process: How to release LDC.