https://wiki.dlang.org/api.php?action=feedcontributions&user=Jondegenhardt&feedformat=atomD Wiki - User contributions [en]2024-03-29T14:26:37ZUser contributionsMediaWiki 1.31.2https://wiki.dlang.org/?title=Jon_Degenhardt&diff=9666Jon Degenhardt2019-09-20T17:55:05Z<p>Jondegenhardt: </p>
<hr />
<div>== D Related Work ==<br />
* [https://dlang.org/blog/2017/05/24/faster-command-line-tools-in-d/ Faster Command Line Tools in D] (Blog post)<br />
* [https://github.com/eBay/tsv-utils eBay's TSV Utilities]<br />
{{Person<br />
|github=jondegenhardt<br />
}}</div>Jondegenhardthttps://wiki.dlang.org/?title=Jon_Degenhardt&diff=9665Jon Degenhardt2019-09-20T17:41:29Z<p>Jondegenhardt: Created page with "{{Person |github=jondegenhardt }}"</p>
<hr />
<div>{{Person<br />
|github=jondegenhardt<br />
}}</div>Jondegenhardthttps://wiki.dlang.org/?title=GSOC_2019_Ideas&diff=9428GSOC 2019 Ideas2018-12-04T06:06:40Z<p>Jondegenhardt: Have the eBay link point to eBay/tsv-utils rather than the AdRoll blog post</p>
<hr />
<div>This is the D Language Foundation's Google Summer of Code 2019 page.<br />
<br />
If you are interested in working on a D project as part of GSoC 2019, as either a student or mentor, please contact Michael Parker at aldacron@gmail.com. Include "GSoC 2019" in the email subject line.<br />
<br />
<br />
== Timeline ==<br />
The timeline for GSoC 2019 [https://developers.google.com/open-source/gsoc/timeline can be found here].<br />
<br />
== Ideas ==<br />
<br />
The D ecosystem is always in need of improvement through the revision of existing projects and the creation of new ones. The core projects like the([http://dlang.org/phobos/index.html standard library]) and the compilers ([[Compilers]]) are always in need of attention. Other important areas include GUI support, integration with other languages, improving and enhancing the tooling, IDE and editor support, and more.<br />
<br />
Please add your project ideas to the list below, being as descriptive as you can in the summaries. Students interested in participating can use the ideas listed here as jumping off points, so the more information you provide, the easier it will be for them to get started. If your idea is particularly complex or nuanced, consider leaving contact information so that interested parties may follow up.<br />
<br />
Some [https://wiki.dlang.org/GSOC_2018_Ideas ideas from the GSoC 2018] and [https://wiki.dlang.org/SAOC_2018_ideas the Symmetry Autumn of Code] pages remain unimplemented. Feel free to include here any of those you care about.<br />
<br />
=== Graphics library for resource constrained embedded systems ===<br />
----<br />
<br />
Create a 2D rasterizer, rich drawing primitives, and 2D graphics library suitable for resource constrained embedded systems (e.g. ARM Cortex-M) to be used in industrial controls, home appliances, medical devices, consumer electronics, and IoT just to name a few. The end goal would be something similar to [https://www.segger.com/products/user-interface/emwin Segger's emWin]. The library would be used to drive LDCs similar to https://www.adafruit.com/product/3396<br />
Requirements:<br />
<br />
* Hardware agnostic; should simply render to a frame buffer<br />
* No dependencies (No Phobos, no C standard library, and no official D runtime).<br />
* Consider using -betterC, but a custom minimal D runtime is also a viable option<br />
<br />
Related work:<br />
<br />
* https://github.com/TurkeyMan/color<br />
* https://bitbucket.org/timosi/minlibd<br />
* https://github.com/JinShil/stm32f42_discovery_demo<br />
<br />
Proposed Project Mentors: TBA<br />
<br />
=== Tabular data container (data frames) ===<br />
----<br />
<br />
Pandas, R and Julia have made [https://github.com/mobileink/data.frame/wiki/What-is-a-Data-Frame%3F data frames] very popular.<br />
As D is getting more interest from data scientist (e.g. [https://github.com/eBay/tsv-utils eBay] or [http://tech.adroll.com/blog/data/2014/11/17/d-is-for-data-science.html AdRoll]) it would be very beneficial to use one language for the entire data analysis pipeline - especially considering that D (in contrast to popular languages like Python, R or Julia) - is compiled to native machine code and gets optimized by the sophisticated LLVM backend.<br />
<br />
Minimum requirements:<br />
<br />
* conversion to and from CSV<br />
* multi-indexing<br />
* column binary operations, e.g. `column1 * column2`<br />
* group-by on an arbitrary number of columns<br />
* column/group aggregations<br />
<br />
Proposed Project Mentor: TBA<br />
<br />
=== C++ interops ===<br />
----<br />
<br />
There are many experiments in transparently interfacing D with C++, notably:<br />
<br />
* [https://github.com/atilaneves/dpp dpp] by Atila Neves, that parses and translates headers on the fly<br />
* [https://wiki.dlang.org/Calypso Calypso] by Elie Morisse that bridges the two languages at the AST level.<br />
<br />
There is also a lot of work in gringing STL types to the DRuntime (see https://github.com/dlang/druntime/pull/2310).<br />
<br />
D would greatly benefit by seamlessly integrating the C++ ecosystem. There are many ways to accomplish this goal and it should be discussed with the community.<br />
Andrei already commented on the importance of a tool like Calypso in this thread:<br />
https://forum.dlang.org/post/m9s4cd$2s1v$1@digitalmars.com<br />
<br />
<br />
Proposed Project Mentor: TBA<br />
<br />
[[Category:GSOC]]</div>Jondegenhardthttps://wiki.dlang.org/?title=Building_LDC_from_source&diff=9267Building LDC from source2018-07-23T22:10:15Z<p>Jondegenhardt: /* Useful CMake variables */</p>
<hr />
<div>This page shows you how to build and install [[LDC]] on most Posix-like systems such as linux, macOS, BSD, or Android. For building LDC on Windows, please see [[Building and hacking LDC on Windows using MSVC|its dedicated page]].<br />
<br />
== Advice ==<br />
It is hard for us to keep these wiki pages up-to-date. If you run into trouble, have a look at the build scripts for our [http://wiki.dlang.org/LDC_contributor%27s_guide#Continuous_Integration Continuous Integration] platforms: the files <tt>.circleci/config.yml</tt> (Ubuntu Linux and macOS) and <tt>appveyor.yml</tt> (Windows) are always up-to-date with the latest build setup.<br />
<br />
== Prerequisites ==<br />
<br />
* Git (for fetching the source code, if not using a tarball)<br />
* a C++ toolchain (GCC, Clang, …)<br />
* a D compiler (currently LDC and DMD are supported)<br />
** If you don't have a D compiler installed: LDC 0.17 is the last version that does not need a D compiler to be built. Thus for bootstrapping, you can first build 0.17, and then use that to build newer compiler versions. Our testing infrastructure explicitly tests that new LDC versions can be built with 0.17. The git branch is called <tt>ltsmaster</tt> or [https://github.com/ldc-developers/ldc/releases you can get the source for the latest 0.17 release].<br />
* CMake 2.8+<br />
* Make or Ninja<br />
* LLVM 3.7+<br />
* For 0.17 ltsmaster, you need libconfig++ and its header files<br />
** Get the <tt>libconfig-devel</tt> or <tt>libconfig-dev</tt> package for some Linux distributions. On OSX, <tt>sudo port install libconfig-hr</tt>); on Android with the Termux app, <tt>apt install libconfig-dev</tt><br />
* libcurl-dev for building the Phobos standard library and tests (various versions available, e.g. libcurl4-gnutls-dev on Ubuntu)<br />
* libedit-dev<br />
* zlib-dev (e.g. zlib1g-dev on Ubuntu)<br />
<br />
=== LLVM ===<br />
<br />
Many Linux distributions already provide recent binary LLVM packages, sometimes in the form of user-curated package repositories (PPA, …). If a recent LLVM package is available, you might prefer to use it, as LLVM is a rather big project to build. Only the Android target requires building [https://github.com/ldc-developers/llvm our lightly tweaked version of LLVM], which is what we'll use here.<br />
<br />
==== Building LLVM manually ====<br />
<br />
We try to keep LDC up-to-date with LLVM trunk, but the latest official release is recommended for the least amount of trouble (with LLVM trunk, you will have to recompile LLVM often). Download [https://github.com/ldc-developers/llvm/releases/tag/ldc-v5.0.1/ our lightly tweaked version of the last official release, 5.0.1], extract the archive, configure it, and build:<br />
<br />
<syntaxhighlight lang=bash><br />
curl -L -O https://github.com/ldc-developers/llvm/releases/download/ldc-v5.0.1/llvm-5.0.1.src.tar.xz<br />
tar xf llvm-5.0.1.src.tar.xz<br />
cd llvm-5.0.1.src/<br />
mkdir build && cd build/<br />
<br />
cmake -GNinja .. -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;AArch64;ARM;PowerPC;NVPTX" -DLLVM_BUILD_TOOLS=OFF -DLLVM_BUILD_UTILS=OFF # remove -GNinja to use Make instead<br />
ninja all llvm-config<br />
<br />
cd ../../<br />
</syntaxhighlight><br />
<br />
If you are planning to work on LDC itself, you might want to install a debug build of LLVM instead by using <tt>-DCMAKE_BUILD_TYPE=Debug</tt>. Warning: This leads to a ''heavy'' slowdown!<br />
<br />
If you are building natively in Termux for Android, you'll want to add <tt>-DLLVM_DEFAULT_TARGET_TRIPLE=armv7-none-linux-android</tt>, because CMake cannot detect the Android platform yet.<br />
<br />
== LDC ==<br />
<br />
Now that you're ready to build and install LDC from source, clone the [https://github.com/ldc-developers/ldc LDC GitHub repository] or get [https://github.com/ldc-developers/ldc/releases one of our official source releases]:<br />
<pre>$ git clone --recursive https://github.com/ldc-developers/ldc.git</pre><br />
<br />
If you're behind a company firewall and cloning of the submodules fails, first configure git to use a different protocol, ex https:<br />
<pre>$ git config --global url."https://github".insteadOf git://github</pre><br />
<br />
If you already have the git repo, don’t forget to make sure your submodules are up to date by running <tt>git submodule update --init</tt>.<br />
<br />
Run the following commands to configure and build ldc and its runtime libraries (see the list of useful CMake switches below):<br />
<br />
<syntaxhighlight lang=bash><br />
cd ldc<br />
<br />
# Make a working directory for the build (name/path arbitrary).<br />
mkdir build && cd build<br />
<br />
# If host D compiler is not on path, explicitly specify dmd/ldmd2<br />
# (not required for ltsmaster/0.17.x).<br />
export DMD=/path/to/your/dmd2/bin/dmd<br />
<br />
# Run CMake, giving path to top-level source directory. (Remove<br />
# -G Ninja to use default generator, i.e. make.)<br />
cmake -G Ninja -DLLVM_CONFIG=../../llvm-5.0.1.src/build/bin/llvm-config ..<br />
<br />
# Build and install LDC. Use -j<n> to limit parallelism if running out of memory.<br />
ninja<br />
sudo ninja install<br />
</syntaxhighlight><br />
The last step is optional; instead of installing it to the system, you can also choose to run LDC from the <tt>bin/</tt> directory in your CMake working tree. If you're using an LLVM already installed in your system instead of the tweaked version we just compiled, you don't need to specify <tt>-DLLVM_CONFIG=..</tt>, because our CMake config should pick it up automatically. If you want to target Android and are building ldc 1.4 or later, add <tt>-DLDC_TARGET_PRESET=Android-arm</tt> to the CMake config.<br />
<br />
If cross-compiling the runtime libraries, you'll need to specify the C cross-compiler before running CMake<br />
<br />
<pre>$ export CC=/home/david/android-ndk-r16b/toolchains/llvm/prebuilt/linux-x86_64/bin/clang</pre><br />
<br />
and pass any C, D, or linker flags you need to CMake:<br />
<br />
<pre>-DRT_CFLAGS="-target armv7-none-linux-gnueabihf -Os" -DD_FLAGS="-w;-mtriple=armv7-none-linux-gnueabihf" -DLD_FLAGS="-target armv7-none-linux-gnueabihf -fpie -pie"</pre><br />
<br />
=== Useful CMake variables ===<br />
<br />
* '''LIB_SUFFIX''': Some Linux distributions, such as Fedora, expect 64 bit libraries in <tt>/usr/lib64</tt> instead of <tt>/usr/lib</tt>. In this case, the installation directory can be adjusted using <tt>-DLIB_SUFFIX=64</tt>.<br />
* '''CMAKE_INSTALL_PREFIX''': The installation prefix, <tt>/usr/local</tt> by default (e.g. <tt>-DCMAKE_INSTALL_PREFIX=/opt/ldc</tt>).<br />
* '''INCLUDE_INSTALL_DIR''': The location the D modules for druntime and Phobos are installed to.<br />
* '''RUNTIME_DIR''', '''PHOBOS2_DIR''': By default, druntime and Phobos are expected in <tt>runtime/</tt> as git submodules. Should circumstances require it, these paths can be changed by setting the variables accordingly.<br />
* '''LLVM_ROOT_DIR''' and '''LLVM_CONFIG''': Allows you to specify the LLVM instance to use. LLVM_CONFIG specifies the path and name of the <tt>llvm-config</tt> binary to use. By default, it is assumed to be <tt>${LLVM_ROOT_DIR}/bin/llvm-config</tt>, otherwise it is searched for on default system paths. EDIT: https://github.com/ldc-developers/ldc/issues/1928#issuecomment-268421779 suggests we should just use `ccmake -DLLVM_ROOT_DIR=$homebrew_D/ ..` on ubuntu 14.04 even if /usr/bin/llvm-config-3.8 is available<br />
* '''LIBCONFIG_LIBRARY''' and '''LIBCONFIG_INCLUDE_DIR''': Only for 0.17 ltsmaster, these variables can be used to specify the location of the libconfig++ library files and the path to the corresponding header files. NOTE: on error Could NOT find LibConfig (missing: LIBCONFIG_INCLUDE_DIR LIBCONFIG_LIBRARY) and using brew, use for eg: CMAKE_PREFIX_PATH=`brew --prefix` cmake .. [see https://github.com/ldc-developers/ldc/issues/952] or use `sudo apt-get install libconfig++`<br />
* '''D_COMPILER''': path to prebuilt D compiler, needed for anything newer than 0.17 ltsmaster<br />
* '''BUILD_LTO_LIBS''': Set this to <tt>'ON'</tt> to build phobos and druntime with LTO. Available on MacOS and Linux starting with LDC 1.9.0. Include <tt>D_FLAGS='-w;-flto=thin'</tt> to enable ThinLTO (so pass <tt>-DBUILD_LTO_LIBS=ON -DD_FLAGS='-w;-flto=thin'</tt> to cmake). In LDC 1.12.0 ThinLTO will be included automatically, so the <tt>D_FLAGS</tt> variable won't be necessary. LDC 1.12.0 will also support Win64 ([https://github.com/ldc-developers/ldc/pull/2774 PR 2774]).<br />
<br />
NOTE: see https://github.com/Linuxbrew/homebrew-core/blob/master/Formula/ldc.rb for brew's install<br />
<br />
== Tips ==<br />
<br />
The Makefiles generated by CMake respect the <tt>DESTDIR</tt> variable for the <tt>install</tt> target. It is prepended to all the file installation targets. This can be useful for building packages:<br />
<br />
<tt>$ make install DESTDIR=&lt;your root directory&gt;</tt><br />
<br />
[[Category:LDC]]</div>Jondegenhardthttps://wiki.dlang.org/?title=Building_LDC_from_source&diff=9266Building LDC from source2018-07-23T22:06:26Z<p>Jondegenhardt: /* Useful CMake variables */</p>
<hr />
<div>This page shows you how to build and install [[LDC]] on most Posix-like systems such as linux, macOS, BSD, or Android. For building LDC on Windows, please see [[Building and hacking LDC on Windows using MSVC|its dedicated page]].<br />
<br />
== Advice ==<br />
It is hard for us to keep these wiki pages up-to-date. If you run into trouble, have a look at the build scripts for our [http://wiki.dlang.org/LDC_contributor%27s_guide#Continuous_Integration Continuous Integration] platforms: the files <tt>.circleci/config.yml</tt> (Ubuntu Linux and macOS) and <tt>appveyor.yml</tt> (Windows) are always up-to-date with the latest build setup.<br />
<br />
== Prerequisites ==<br />
<br />
* Git (for fetching the source code, if not using a tarball)<br />
* a C++ toolchain (GCC, Clang, …)<br />
* a D compiler (currently LDC and DMD are supported)<br />
** If you don't have a D compiler installed: LDC 0.17 is the last version that does not need a D compiler to be built. Thus for bootstrapping, you can first build 0.17, and then use that to build newer compiler versions. Our testing infrastructure explicitly tests that new LDC versions can be built with 0.17. The git branch is called <tt>ltsmaster</tt> or [https://github.com/ldc-developers/ldc/releases you can get the source for the latest 0.17 release].<br />
* CMake 2.8+<br />
* Make or Ninja<br />
* LLVM 3.7+<br />
* For 0.17 ltsmaster, you need libconfig++ and its header files<br />
** Get the <tt>libconfig-devel</tt> or <tt>libconfig-dev</tt> package for some Linux distributions. On OSX, <tt>sudo port install libconfig-hr</tt>); on Android with the Termux app, <tt>apt install libconfig-dev</tt><br />
* libcurl-dev for building the Phobos standard library and tests (various versions available, e.g. libcurl4-gnutls-dev on Ubuntu)<br />
* libedit-dev<br />
* zlib-dev (e.g. zlib1g-dev on Ubuntu)<br />
<br />
=== LLVM ===<br />
<br />
Many Linux distributions already provide recent binary LLVM packages, sometimes in the form of user-curated package repositories (PPA, …). If a recent LLVM package is available, you might prefer to use it, as LLVM is a rather big project to build. Only the Android target requires building [https://github.com/ldc-developers/llvm our lightly tweaked version of LLVM], which is what we'll use here.<br />
<br />
==== Building LLVM manually ====<br />
<br />
We try to keep LDC up-to-date with LLVM trunk, but the latest official release is recommended for the least amount of trouble (with LLVM trunk, you will have to recompile LLVM often). Download [https://github.com/ldc-developers/llvm/releases/tag/ldc-v5.0.1/ our lightly tweaked version of the last official release, 5.0.1], extract the archive, configure it, and build:<br />
<br />
<syntaxhighlight lang=bash><br />
curl -L -O https://github.com/ldc-developers/llvm/releases/download/ldc-v5.0.1/llvm-5.0.1.src.tar.xz<br />
tar xf llvm-5.0.1.src.tar.xz<br />
cd llvm-5.0.1.src/<br />
mkdir build && cd build/<br />
<br />
cmake -GNinja .. -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;AArch64;ARM;PowerPC;NVPTX" -DLLVM_BUILD_TOOLS=OFF -DLLVM_BUILD_UTILS=OFF # remove -GNinja to use Make instead<br />
ninja all llvm-config<br />
<br />
cd ../../<br />
</syntaxhighlight><br />
<br />
If you are planning to work on LDC itself, you might want to install a debug build of LLVM instead by using <tt>-DCMAKE_BUILD_TYPE=Debug</tt>. Warning: This leads to a ''heavy'' slowdown!<br />
<br />
If you are building natively in Termux for Android, you'll want to add <tt>-DLLVM_DEFAULT_TARGET_TRIPLE=armv7-none-linux-android</tt>, because CMake cannot detect the Android platform yet.<br />
<br />
== LDC ==<br />
<br />
Now that you're ready to build and install LDC from source, clone the [https://github.com/ldc-developers/ldc LDC GitHub repository] or get [https://github.com/ldc-developers/ldc/releases one of our official source releases]:<br />
<pre>$ git clone --recursive https://github.com/ldc-developers/ldc.git</pre><br />
<br />
If you're behind a company firewall and cloning of the submodules fails, first configure git to use a different protocol, ex https:<br />
<pre>$ git config --global url."https://github".insteadOf git://github</pre><br />
<br />
If you already have the git repo, don’t forget to make sure your submodules are up to date by running <tt>git submodule update --init</tt>.<br />
<br />
Run the following commands to configure and build ldc and its runtime libraries (see the list of useful CMake switches below):<br />
<br />
<syntaxhighlight lang=bash><br />
cd ldc<br />
<br />
# Make a working directory for the build (name/path arbitrary).<br />
mkdir build && cd build<br />
<br />
# If host D compiler is not on path, explicitly specify dmd/ldmd2<br />
# (not required for ltsmaster/0.17.x).<br />
export DMD=/path/to/your/dmd2/bin/dmd<br />
<br />
# Run CMake, giving path to top-level source directory. (Remove<br />
# -G Ninja to use default generator, i.e. make.)<br />
cmake -G Ninja -DLLVM_CONFIG=../../llvm-5.0.1.src/build/bin/llvm-config ..<br />
<br />
# Build and install LDC. Use -j<n> to limit parallelism if running out of memory.<br />
ninja<br />
sudo ninja install<br />
</syntaxhighlight><br />
The last step is optional; instead of installing it to the system, you can also choose to run LDC from the <tt>bin/</tt> directory in your CMake working tree. If you're using an LLVM already installed in your system instead of the tweaked version we just compiled, you don't need to specify <tt>-DLLVM_CONFIG=..</tt>, because our CMake config should pick it up automatically. If you want to target Android and are building ldc 1.4 or later, add <tt>-DLDC_TARGET_PRESET=Android-arm</tt> to the CMake config.<br />
<br />
If cross-compiling the runtime libraries, you'll need to specify the C cross-compiler before running CMake<br />
<br />
<pre>$ export CC=/home/david/android-ndk-r16b/toolchains/llvm/prebuilt/linux-x86_64/bin/clang</pre><br />
<br />
and pass any C, D, or linker flags you need to CMake:<br />
<br />
<pre>-DRT_CFLAGS="-target armv7-none-linux-gnueabihf -Os" -DD_FLAGS="-w;-mtriple=armv7-none-linux-gnueabihf" -DLD_FLAGS="-target armv7-none-linux-gnueabihf -fpie -pie"</pre><br />
<br />
=== Useful CMake variables ===<br />
<br />
* '''LIB_SUFFIX''': Some Linux distributions, such as Fedora, expect 64 bit libraries in <tt>/usr/lib64</tt> instead of <tt>/usr/lib</tt>. In this case, the installation directory can be adjusted using <tt>-DLIB_SUFFIX=64</tt>.<br />
* '''CMAKE_INSTALL_PREFIX''': The installation prefix, <tt>/usr/local</tt> by default (e.g. <tt>-DCMAKE_INSTALL_PREFIX=/opt/ldc</tt>).<br />
* '''INCLUDE_INSTALL_DIR''': The location the D modules for druntime and Phobos are installed to.<br />
* '''RUNTIME_DIR''', '''PHOBOS2_DIR''': By default, druntime and Phobos are expected in <tt>runtime/</tt> as git submodules. Should circumstances require it, these paths can be changed by setting the variables accordingly.<br />
* '''LLVM_ROOT_DIR''' and '''LLVM_CONFIG''': Allows you to specify the LLVM instance to use. LLVM_CONFIG specifies the path and name of the <tt>llvm-config</tt> binary to use. By default, it is assumed to be <tt>${LLVM_ROOT_DIR}/bin/llvm-config</tt>, otherwise it is searched for on default system paths. EDIT: https://github.com/ldc-developers/ldc/issues/1928#issuecomment-268421779 suggests we should just use `ccmake -DLLVM_ROOT_DIR=$homebrew_D/ ..` on ubuntu 14.04 even if /usr/bin/llvm-config-3.8 is available<br />
* '''LIBCONFIG_LIBRARY''' and '''LIBCONFIG_INCLUDE_DIR''': Only for 0.17 ltsmaster, these variables can be used to specify the location of the libconfig++ library files and the path to the corresponding header files. NOTE: on error Could NOT find LibConfig (missing: LIBCONFIG_INCLUDE_DIR LIBCONFIG_LIBRARY) and using brew, use for eg: CMAKE_PREFIX_PATH=`brew --prefix` cmake .. [see https://github.com/ldc-developers/ldc/issues/952] or use `sudo apt-get install libconfig++`<br />
* '''D_COMPILER''': path to prebuilt D compiler, needed for anything newer than 0.17 ltsmaster<br />
* '''BUILD_LTO_LIBS''': Set this to <tt>'ON'</tt> to build phobos and druntime with LTO. Available on MacOS and Linux starting with LDC 1.9.0. Include <tt>D_FLAGS='-w;-flto=thin'</tt> to enable ThinLTO (so pass <tt>-DBUILD_LTO_LIBS=ON -DD_FLAGS='-w;-flto=thin'</tt> to cmake). In LDC 1.12.0 ThinLTO will be included automatically, so the <tt>D_FLAGS</tt> variable won't be necessary. LDC 1.12.0 will also support Win64 ([PR 2774](https://github.com/ldc-developers/ldc/pull/2774)).<br />
<br />
NOTE: see https://github.com/Linuxbrew/homebrew-core/blob/master/Formula/ldc.rb for brew's install<br />
<br />
== Tips ==<br />
<br />
The Makefiles generated by CMake respect the <tt>DESTDIR</tt> variable for the <tt>install</tt> target. It is prepended to all the file installation targets. This can be useful for building packages:<br />
<br />
<tt>$ make install DESTDIR=&lt;your root directory&gt;</tt><br />
<br />
[[Category:LDC]]</div>Jondegenhardthttps://wiki.dlang.org/?title=Building_LDC_from_source&diff=9265Building LDC from source2018-07-23T22:04:48Z<p>Jondegenhardt: /* Useful CMake variables */</p>
<hr />
<div>This page shows you how to build and install [[LDC]] on most Posix-like systems such as linux, macOS, BSD, or Android. For building LDC on Windows, please see [[Building and hacking LDC on Windows using MSVC|its dedicated page]].<br />
<br />
== Advice ==<br />
It is hard for us to keep these wiki pages up-to-date. If you run into trouble, have a look at the build scripts for our [http://wiki.dlang.org/LDC_contributor%27s_guide#Continuous_Integration Continuous Integration] platforms: the files <tt>.circleci/config.yml</tt> (Ubuntu Linux and macOS) and <tt>appveyor.yml</tt> (Windows) are always up-to-date with the latest build setup.<br />
<br />
== Prerequisites ==<br />
<br />
* Git (for fetching the source code, if not using a tarball)<br />
* a C++ toolchain (GCC, Clang, …)<br />
* a D compiler (currently LDC and DMD are supported)<br />
** If you don't have a D compiler installed: LDC 0.17 is the last version that does not need a D compiler to be built. Thus for bootstrapping, you can first build 0.17, and then use that to build newer compiler versions. Our testing infrastructure explicitly tests that new LDC versions can be built with 0.17. The git branch is called <tt>ltsmaster</tt> or [https://github.com/ldc-developers/ldc/releases you can get the source for the latest 0.17 release].<br />
* CMake 2.8+<br />
* Make or Ninja<br />
* LLVM 3.7+<br />
* For 0.17 ltsmaster, you need libconfig++ and its header files<br />
** Get the <tt>libconfig-devel</tt> or <tt>libconfig-dev</tt> package for some Linux distributions. On OSX, <tt>sudo port install libconfig-hr</tt>); on Android with the Termux app, <tt>apt install libconfig-dev</tt><br />
* libcurl-dev for building the Phobos standard library and tests (various versions available, e.g. libcurl4-gnutls-dev on Ubuntu)<br />
* libedit-dev<br />
* zlib-dev (e.g. zlib1g-dev on Ubuntu)<br />
<br />
=== LLVM ===<br />
<br />
Many Linux distributions already provide recent binary LLVM packages, sometimes in the form of user-curated package repositories (PPA, …). If a recent LLVM package is available, you might prefer to use it, as LLVM is a rather big project to build. Only the Android target requires building [https://github.com/ldc-developers/llvm our lightly tweaked version of LLVM], which is what we'll use here.<br />
<br />
==== Building LLVM manually ====<br />
<br />
We try to keep LDC up-to-date with LLVM trunk, but the latest official release is recommended for the least amount of trouble (with LLVM trunk, you will have to recompile LLVM often). Download [https://github.com/ldc-developers/llvm/releases/tag/ldc-v5.0.1/ our lightly tweaked version of the last official release, 5.0.1], extract the archive, configure it, and build:<br />
<br />
<syntaxhighlight lang=bash><br />
curl -L -O https://github.com/ldc-developers/llvm/releases/download/ldc-v5.0.1/llvm-5.0.1.src.tar.xz<br />
tar xf llvm-5.0.1.src.tar.xz<br />
cd llvm-5.0.1.src/<br />
mkdir build && cd build/<br />
<br />
cmake -GNinja .. -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;AArch64;ARM;PowerPC;NVPTX" -DLLVM_BUILD_TOOLS=OFF -DLLVM_BUILD_UTILS=OFF # remove -GNinja to use Make instead<br />
ninja all llvm-config<br />
<br />
cd ../../<br />
</syntaxhighlight><br />
<br />
If you are planning to work on LDC itself, you might want to install a debug build of LLVM instead by using <tt>-DCMAKE_BUILD_TYPE=Debug</tt>. Warning: This leads to a ''heavy'' slowdown!<br />
<br />
If you are building natively in Termux for Android, you'll want to add <tt>-DLLVM_DEFAULT_TARGET_TRIPLE=armv7-none-linux-android</tt>, because CMake cannot detect the Android platform yet.<br />
<br />
== LDC ==<br />
<br />
Now that you're ready to build and install LDC from source, clone the [https://github.com/ldc-developers/ldc LDC GitHub repository] or get [https://github.com/ldc-developers/ldc/releases one of our official source releases]:<br />
<pre>$ git clone --recursive https://github.com/ldc-developers/ldc.git</pre><br />
<br />
If you're behind a company firewall and cloning of the submodules fails, first configure git to use a different protocol, ex https:<br />
<pre>$ git config --global url."https://github".insteadOf git://github</pre><br />
<br />
If you already have the git repo, don’t forget to make sure your submodules are up to date by running <tt>git submodule update --init</tt>.<br />
<br />
Run the following commands to configure and build ldc and its runtime libraries (see the list of useful CMake switches below):<br />
<br />
<syntaxhighlight lang=bash><br />
cd ldc<br />
<br />
# Make a working directory for the build (name/path arbitrary).<br />
mkdir build && cd build<br />
<br />
# If host D compiler is not on path, explicitly specify dmd/ldmd2<br />
# (not required for ltsmaster/0.17.x).<br />
export DMD=/path/to/your/dmd2/bin/dmd<br />
<br />
# Run CMake, giving path to top-level source directory. (Remove<br />
# -G Ninja to use default generator, i.e. make.)<br />
cmake -G Ninja -DLLVM_CONFIG=../../llvm-5.0.1.src/build/bin/llvm-config ..<br />
<br />
# Build and install LDC. Use -j<n> to limit parallelism if running out of memory.<br />
ninja<br />
sudo ninja install<br />
</syntaxhighlight><br />
The last step is optional; instead of installing it to the system, you can also choose to run LDC from the <tt>bin/</tt> directory in your CMake working tree. If you're using an LLVM already installed in your system instead of the tweaked version we just compiled, you don't need to specify <tt>-DLLVM_CONFIG=..</tt>, because our CMake config should pick it up automatically. If you want to target Android and are building ldc 1.4 or later, add <tt>-DLDC_TARGET_PRESET=Android-arm</tt> to the CMake config.<br />
<br />
If cross-compiling the runtime libraries, you'll need to specify the C cross-compiler before running CMake<br />
<br />
<pre>$ export CC=/home/david/android-ndk-r16b/toolchains/llvm/prebuilt/linux-x86_64/bin/clang</pre><br />
<br />
and pass any C, D, or linker flags you need to CMake:<br />
<br />
<pre>-DRT_CFLAGS="-target armv7-none-linux-gnueabihf -Os" -DD_FLAGS="-w;-mtriple=armv7-none-linux-gnueabihf" -DLD_FLAGS="-target armv7-none-linux-gnueabihf -fpie -pie"</pre><br />
<br />
=== Useful CMake variables ===<br />
<br />
* '''LIB_SUFFIX''': Some Linux distributions, such as Fedora, expect 64 bit libraries in <tt>/usr/lib64</tt> instead of <tt>/usr/lib</tt>. In this case, the installation directory can be adjusted using <tt>-DLIB_SUFFIX=64</tt>.<br />
* '''CMAKE_INSTALL_PREFIX''': The installation prefix, <tt>/usr/local</tt> by default (e.g. <tt>-DCMAKE_INSTALL_PREFIX=/opt/ldc</tt>).<br />
* '''INCLUDE_INSTALL_DIR''': The location the D modules for druntime and Phobos are installed to.<br />
* '''RUNTIME_DIR''', '''PHOBOS2_DIR''': By default, druntime and Phobos are expected in <tt>runtime/</tt> as git submodules. Should circumstances require it, these paths can be changed by setting the variables accordingly.<br />
* '''LLVM_ROOT_DIR''' and '''LLVM_CONFIG''': Allows you to specify the LLVM instance to use. LLVM_CONFIG specifies the path and name of the <tt>llvm-config</tt> binary to use. By default, it is assumed to be <tt>${LLVM_ROOT_DIR}/bin/llvm-config</tt>, otherwise it is searched for on default system paths. EDIT: https://github.com/ldc-developers/ldc/issues/1928#issuecomment-268421779 suggests we should just use `ccmake -DLLVM_ROOT_DIR=$homebrew_D/ ..` on ubuntu 14.04 even if /usr/bin/llvm-config-3.8 is available<br />
* '''LIBCONFIG_LIBRARY''' and '''LIBCONFIG_INCLUDE_DIR''': Only for 0.17 ltsmaster, these variables can be used to specify the location of the libconfig++ library files and the path to the corresponding header files. NOTE: on error Could NOT find LibConfig (missing: LIBCONFIG_INCLUDE_DIR LIBCONFIG_LIBRARY) and using brew, use for eg: CMAKE_PREFIX_PATH=`brew --prefix` cmake .. [see https://github.com/ldc-developers/ldc/issues/952] or use `sudo apt-get install libconfig++`<br />
* '''D_COMPILER''': path to prebuilt D compiler, needed for anything newer than 0.17 ltsmaster<br />
* '''BUILD_LTO_LIBS''': Use this to build phobos and druntime with LTO. Available on MacOS and Linux starting with LDC 1.9.0. Include <tt>D_FLAGS='-w;-flto=thin'</tt> to enable ThinLTO (so pass <tt>-DBUILD_LTO_LIBS=ON -DD_FLAGS='-w;-flto=thin'</tt> to cmake). In LDC 1.12.0 ThinLTO will be included automatically, so the <tt>D_FLAGS</tt> variable won't be necessary. LDC 1.12.0 will also support Win64 ([PR 2774](https://github.com/ldc-developers/ldc/pull/2774)).<br />
<br />
NOTE: see https://github.com/Linuxbrew/homebrew-core/blob/master/Formula/ldc.rb for brew's install<br />
<br />
== Tips ==<br />
<br />
The Makefiles generated by CMake respect the <tt>DESTDIR</tt> variable for the <tt>install</tt> target. It is prepended to all the file installation targets. This can be useful for building packages:<br />
<br />
<tt>$ make install DESTDIR=&lt;your root directory&gt;</tt><br />
<br />
[[Category:LDC]]</div>Jondegenhardthttps://wiki.dlang.org/?title=Building_LDC_from_source&diff=9264Building LDC from source2018-07-23T22:03:00Z<p>Jondegenhardt: /* Useful CMake variables */</p>
<hr />
<div>This page shows you how to build and install [[LDC]] on most Posix-like systems such as linux, macOS, BSD, or Android. For building LDC on Windows, please see [[Building and hacking LDC on Windows using MSVC|its dedicated page]].<br />
<br />
== Advice ==<br />
It is hard for us to keep these wiki pages up-to-date. If you run into trouble, have a look at the build scripts for our [http://wiki.dlang.org/LDC_contributor%27s_guide#Continuous_Integration Continuous Integration] platforms: the files <tt>.circleci/config.yml</tt> (Ubuntu Linux and macOS) and <tt>appveyor.yml</tt> (Windows) are always up-to-date with the latest build setup.<br />
<br />
== Prerequisites ==<br />
<br />
* Git (for fetching the source code, if not using a tarball)<br />
* a C++ toolchain (GCC, Clang, …)<br />
* a D compiler (currently LDC and DMD are supported)<br />
** If you don't have a D compiler installed: LDC 0.17 is the last version that does not need a D compiler to be built. Thus for bootstrapping, you can first build 0.17, and then use that to build newer compiler versions. Our testing infrastructure explicitly tests that new LDC versions can be built with 0.17. The git branch is called <tt>ltsmaster</tt> or [https://github.com/ldc-developers/ldc/releases you can get the source for the latest 0.17 release].<br />
* CMake 2.8+<br />
* Make or Ninja<br />
* LLVM 3.7+<br />
* For 0.17 ltsmaster, you need libconfig++ and its header files<br />
** Get the <tt>libconfig-devel</tt> or <tt>libconfig-dev</tt> package for some Linux distributions. On OSX, <tt>sudo port install libconfig-hr</tt>); on Android with the Termux app, <tt>apt install libconfig-dev</tt><br />
* libcurl-dev for building the Phobos standard library and tests (various versions available, e.g. libcurl4-gnutls-dev on Ubuntu)<br />
* libedit-dev<br />
* zlib-dev (e.g. zlib1g-dev on Ubuntu)<br />
<br />
=== LLVM ===<br />
<br />
Many Linux distributions already provide recent binary LLVM packages, sometimes in the form of user-curated package repositories (PPA, …). If a recent LLVM package is available, you might prefer to use it, as LLVM is a rather big project to build. Only the Android target requires building [https://github.com/ldc-developers/llvm our lightly tweaked version of LLVM], which is what we'll use here.<br />
<br />
==== Building LLVM manually ====<br />
<br />
We try to keep LDC up-to-date with LLVM trunk, but the latest official release is recommended for the least amount of trouble (with LLVM trunk, you will have to recompile LLVM often). Download [https://github.com/ldc-developers/llvm/releases/tag/ldc-v5.0.1/ our lightly tweaked version of the last official release, 5.0.1], extract the archive, configure it, and build:<br />
<br />
<syntaxhighlight lang=bash><br />
curl -L -O https://github.com/ldc-developers/llvm/releases/download/ldc-v5.0.1/llvm-5.0.1.src.tar.xz<br />
tar xf llvm-5.0.1.src.tar.xz<br />
cd llvm-5.0.1.src/<br />
mkdir build && cd build/<br />
<br />
cmake -GNinja .. -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;AArch64;ARM;PowerPC;NVPTX" -DLLVM_BUILD_TOOLS=OFF -DLLVM_BUILD_UTILS=OFF # remove -GNinja to use Make instead<br />
ninja all llvm-config<br />
<br />
cd ../../<br />
</syntaxhighlight><br />
<br />
If you are planning to work on LDC itself, you might want to install a debug build of LLVM instead by using <tt>-DCMAKE_BUILD_TYPE=Debug</tt>. Warning: This leads to a ''heavy'' slowdown!<br />
<br />
If you are building natively in Termux for Android, you'll want to add <tt>-DLLVM_DEFAULT_TARGET_TRIPLE=armv7-none-linux-android</tt>, because CMake cannot detect the Android platform yet.<br />
<br />
== LDC ==<br />
<br />
Now that you're ready to build and install LDC from source, clone the [https://github.com/ldc-developers/ldc LDC GitHub repository] or get [https://github.com/ldc-developers/ldc/releases one of our official source releases]:<br />
<pre>$ git clone --recursive https://github.com/ldc-developers/ldc.git</pre><br />
<br />
If you're behind a company firewall and cloning of the submodules fails, first configure git to use a different protocol, ex https:<br />
<pre>$ git config --global url."https://github".insteadOf git://github</pre><br />
<br />
If you already have the git repo, don’t forget to make sure your submodules are up to date by running <tt>git submodule update --init</tt>.<br />
<br />
Run the following commands to configure and build ldc and its runtime libraries (see the list of useful CMake switches below):<br />
<br />
<syntaxhighlight lang=bash><br />
cd ldc<br />
<br />
# Make a working directory for the build (name/path arbitrary).<br />
mkdir build && cd build<br />
<br />
# If host D compiler is not on path, explicitly specify dmd/ldmd2<br />
# (not required for ltsmaster/0.17.x).<br />
export DMD=/path/to/your/dmd2/bin/dmd<br />
<br />
# Run CMake, giving path to top-level source directory. (Remove<br />
# -G Ninja to use default generator, i.e. make.)<br />
cmake -G Ninja -DLLVM_CONFIG=../../llvm-5.0.1.src/build/bin/llvm-config ..<br />
<br />
# Build and install LDC. Use -j<n> to limit parallelism if running out of memory.<br />
ninja<br />
sudo ninja install<br />
</syntaxhighlight><br />
The last step is optional; instead of installing it to the system, you can also choose to run LDC from the <tt>bin/</tt> directory in your CMake working tree. If you're using an LLVM already installed in your system instead of the tweaked version we just compiled, you don't need to specify <tt>-DLLVM_CONFIG=..</tt>, because our CMake config should pick it up automatically. If you want to target Android and are building ldc 1.4 or later, add <tt>-DLDC_TARGET_PRESET=Android-arm</tt> to the CMake config.<br />
<br />
If cross-compiling the runtime libraries, you'll need to specify the C cross-compiler before running CMake<br />
<br />
<pre>$ export CC=/home/david/android-ndk-r16b/toolchains/llvm/prebuilt/linux-x86_64/bin/clang</pre><br />
<br />
and pass any C, D, or linker flags you need to CMake:<br />
<br />
<pre>-DRT_CFLAGS="-target armv7-none-linux-gnueabihf -Os" -DD_FLAGS="-w;-mtriple=armv7-none-linux-gnueabihf" -DLD_FLAGS="-target armv7-none-linux-gnueabihf -fpie -pie"</pre><br />
<br />
=== Useful CMake variables ===<br />
<br />
* '''LIB_SUFFIX''': Some Linux distributions, such as Fedora, expect 64 bit libraries in <tt>/usr/lib64</tt> instead of <tt>/usr/lib</tt>. In this case, the installation directory can be adjusted using <tt>-DLIB_SUFFIX=64</tt>.<br />
* '''CMAKE_INSTALL_PREFIX''': The installation prefix, <tt>/usr/local</tt> by default (e.g. <tt>-DCMAKE_INSTALL_PREFIX=/opt/ldc</tt>).<br />
* '''INCLUDE_INSTALL_DIR''': The location the D modules for druntime and Phobos are installed to.<br />
* '''RUNTIME_DIR''', '''PHOBOS2_DIR''': By default, druntime and Phobos are expected in <tt>runtime/</tt> as git submodules. Should circumstances require it, these paths can be changed by setting the variables accordingly.<br />
* '''LLVM_ROOT_DIR''' and '''LLVM_CONFIG''': Allows you to specify the LLVM instance to use. LLVM_CONFIG specifies the path and name of the <tt>llvm-config</tt> binary to use. By default, it is assumed to be <tt>${LLVM_ROOT_DIR}/bin/llvm-config</tt>, otherwise it is searched for on default system paths. EDIT: https://github.com/ldc-developers/ldc/issues/1928#issuecomment-268421779 suggests we should just use `ccmake -DLLVM_ROOT_DIR=$homebrew_D/ ..` on ubuntu 14.04 even if /usr/bin/llvm-config-3.8 is available<br />
* '''LIBCONFIG_LIBRARY''' and '''LIBCONFIG_INCLUDE_DIR''': Only for 0.17 ltsmaster, these variables can be used to specify the location of the libconfig++ library files and the path to the corresponding header files. NOTE: on error Could NOT find LibConfig (missing: LIBCONFIG_INCLUDE_DIR LIBCONFIG_LIBRARY) and using brew, use for eg: CMAKE_PREFIX_PATH=`brew --prefix` cmake .. [see https://github.com/ldc-developers/ldc/issues/952] or use `sudo apt-get install libconfig++`<br />
* '''D_COMPILER''': path to prebuilt D compiler, needed for anything newer than 0.17 ltsmaster<br />
* '''BUILD_LTO_LIBS''': Use this to build phobos and druntime with LTO. Available on MacOS and Linux starting with LDC 1.9.0. Include <tt>D_FLAGS='-w;-flto=thin'</tt> to enable ThinLTO (so pass <tt>-DBUILD_LTO_LIBS=ON -DD_FLAGS='-w;-flto=thin'</tt> to cmake. In LDC 1.12.0 ThinLTO will be included automatically, so the <tt>D_FLAGS</tt> variable won't be necessary. LDC 1.12.0 will also support this for Win64 ([PR 2774](https://github.com/ldc-developers/ldc/pull/2774)).<br />
<br />
NOTE: see https://github.com/Linuxbrew/homebrew-core/blob/master/Formula/ldc.rb for brew's install<br />
<br />
== Tips ==<br />
<br />
The Makefiles generated by CMake respect the <tt>DESTDIR</tt> variable for the <tt>install</tt> target. It is prepended to all the file installation targets. This can be useful for building packages:<br />
<br />
<tt>$ make install DESTDIR=&lt;your root directory&gt;</tt><br />
<br />
[[Category:LDC]]</div>Jondegenhardthttps://wiki.dlang.org/?title=Starting_as_a_Contributor&diff=8640Starting as a Contributor2017-10-01T18:39:33Z<p>Jondegenhardt: /* Existing tools */</p>
<hr />
<div>This page describes how to build D, put together a correct patch, and contribute it as a GitHub pull request.<br />
<br />
==Existing tools==<br />
<br />
There exist tools which can do some of the below steps automatically:<br />
<br />
* [https://github.com/dlang/tools/blob/master/setup.sh tools/setup.sh] is a simple script that either installs a new or updates an existing D development tree. Just download the script and run.<br />
* [https://github.com/CyberShadow/Digger Digger] - can download and build D from any point in its recent history.<br />
* [https://github.com/jacob-carlborg/dvm DVM] - can build and locally install D from source code.<br />
<br />
== Building from source ==<br />
<br />
The build information is split into Posix and Windows pages. Be sure to follow the according guide and continue to this page once your setup is working.<br />
<br />
* [[Building_under_Posix | Building under Posix (Linux, macOS, FreeBSD, ...)]]<br />
* [[Building_under_Windows | Building under Windows]]<br />
<br />
== Unittest <tt>phobos</tt> ==<br />
<br />
=== Full build ===<br />
<br />
If you want to work on phobos itself, you need to run unittests&mdash;either for the full library, a package, or a module. To unittest the entire library:<br />
<br />
<syntaxhighlight lang=bash><br />
make -j16 -f posix.mak unittest<br />
</syntaxhighlight><br />
<br />
Adjust the parameter passed to <tt>-j</tt> depending on your machine (beefier machines support larger parameters). This command unittests <tt>phobos</tt> in both debug and release mode. To only test one of them, add <tt>BUILD=debug</tt> or <tt>BUILD=release</tt> to the command line, for example:<br />
<br />
<syntaxhighlight lang=bash><br />
make -j16 -f posix.mak BUILD=debug unittest<br />
</syntaxhighlight><br />
<br />
Specifying <tt>BUILD</tt> makes unittesting faster so it is recommended in iterative development. Just make sure both debug and release builds are tested before e.g. submitting a pull request.<br />
<br />
=== Test a single package ===<br />
<br />
While changing one specific package or module, it's useful to be able to only unittest that particular entity. The following two commands only unittest (in debug mode) the <tt>std.algorithm</tt> package:<br />
<br />
<syntaxhighlight lang=bash><br />
make -j16 -f posix.mak BUILD=debug std/algorithm.test<br />
</syntaxhighlight><br />
<br />
Several modules, packages, or mix thereof may be specified for testing in the same command line. For example, this command also tests (and also in debug mode) the <tt>std.algorithm</tt> package and the <tt>std.conv</tt> module, with better parallelism:<br />
<br />
<syntaxhighlight lang=bash><br />
make -j16 -f posix.mak BUILD=debug std/algorithm.test std/conv.test<br />
</syntaxhighlight><br />
<br />
=== Test a single package without Phobos ===<br />
<br />
You can test a module directly with <tt>rdmd</tt>:<br />
<br />
<syntaxhighlight lang=bash><br />
rdmddev -unittest -main std/algorithm/sorting.d<br />
</syntaxhighlight><br />
<br />
However, be aware that this method doesn't recompile Phobos and thus only checks the executed file. Thus you should only use this for fast builds on small changes.<br />
Moreover, for this method you will need to define the <tt>rdmddev</tt> <tt>alias</tt> or alternatively use [https://dlang.org/download.html <tt>dmd-nightly</tt>].<br />
<br />
<syntaxhighlight lang=bash><br />
alias rdmdev='rdmd --compiler=$HOME/dlang/dmd/generated/linux/release/64/dmd -conf= -L--export-dynamic -I~/dlang/druntime/import -I~/dlang/phobos ~/dlang/phobos/generated/linux/release/64/libphobos2.a'<br />
</syntaxhighlight><br />
<br />
=== Run CI checks ===<br />
<br />
The auto-tester will fail your PR if your changes contain trailing whitespace or incorrect line endings. You can run this test locally with the command:<br />
<br />
<syntaxhighlight lang=bash><br />
make -j16 -f posix.mak checkwhitespace<br />
</syntaxhighlight><br />
<br />
CircleCi will also run various checks for the [http://dlang.org/dstyle.html DStyle] and ensures that every example is runnable on <tt>dlang.org</tt>.<br />
You can run this test locally with:<br />
<br />
<syntaxhighlight lang=bash><br />
make -f posix.mak style<br />
</syntaxhighlight><br />
<br />
==Running Independent Programs==<br />
<br />
The rig created so far allows making changes and testing dmd, druntime, and phobos by using their respective makefiles.<br />
<br />
However, running independent programs (such as by using <tt>~/dlang/dmd/generated/linux/release/64/dmd ~/mytest</tt>) will not know where to pick up the libraries from, even though the compiler path is correctly specified. As a consequence such programs will not compile, or (worse) will pick up libraries of a preexisting dmd installation on the target system and will fail in mysterious ways.<br />
<br />
The remedy is to specify include and library paths properly. To build <tt>mytest.d</tt> using <tt>~/dlang/dmd</tt>, <tt>~/dlang/druntime</tt>, and <tt>~/dlang/phobos</tt>, use this command line:<br />
<br />
<syntaxhighlight lang=bash><br />
~/dlang/dmd/generated/linux/release/64/dmd -I~/dlang/druntime/import -I~/dlang/phobos -L-L$HOME/dlang/phobos/generated/linux/release/64 mytest.d<br />
</syntaxhighlight><br />
<br />
On a different OS, you will need to replace the OS name. For example for <tt>macOS</tt>:<br />
<br />
<syntaxhighlight lang=bash><br />
~/dlang/dmd/generated/osx/release/64/dmd -I~/dlang/druntime/import -I~/dlang/phobos -L-L$HOME/dlang/phobos/generated/osx/release/64 mytest.d<br />
</syntaxhighlight><br />
<br />
<br />
The two <tt>-I</tt> uses bring the import files for druntime and phobos into visibility. The <tt>-L</tt> directive forwards the rest of the argument to the linker, i.e. the linker will get <tt>$HOME/dlang/phobos/generated/*/release/64/</tt> with <tt>$HOME</tt> expanded properly. Sadly we cannot use the tilde (<tt>~</tt>) for <tt>-L</tt> because it won't get expanded properly. (If you need a 32-bit build, replace <tt>/64</tt> with <tt>/32</tt> and of course use the <tt>-m32</tt> flag for the compiler.)<br />
<br />
Of course if you need to use this line often, you may want to put it into a batch file or a <tt>dmd.conf</tt> file (see more info about <tt>dmd.conf</tt> on [https://dlang.org/dmd-linux.html Linux], [https://dlang.org/dmd-windows.html Windows], [https://dlang.org/dmd-osx.html OSX], and [https://dlang.org/dmd-freebsd.html FreeBSD]).<br />
<br />
== Fetch and build <tt>dlang.org</tt> ==<br />
<br />
=== Fetch <tt>dlang.org</tt> ===<br />
<br />
This step is optional. Changes to <tt>phobos</tt> documentation require that the site (which includes automatically generated <tt>phobos</tt> documentation) builds successfully. Alternatively to building the documentation locally, you can use the documentation autotester service, which will build documentation, generate a diff of the results, and add a link to your GitHub pull request.<br />
<br />
The following will clone the <tt>dlang.org</tt> repository:<br />
<br />
<syntaxhighlight lang=bash><br />
cd ~/dlang<br />
git clone https://github.com/dlang/dlang.org<br />
cd dlang.org<br />
</syntaxhighlight><br />
<br />
Furthermore, all of <tt>dmd</tt>, <tt>druntime</tt>, <tt>phobos</tt>, <tt>tools</tt> are needed for the site to build. <br />
The instructions below will build the site to <tt>~/dlang/dlang.org/web</tt>.<br />
<br />
<br />
=== Build new Phobos documentation ===<br />
<br />
If you are just interested in previewing your change to Phobos documentation, the <tt>html</tt> and <tt>phobos-prerelease</tt> will save time:<br />
<br />
<syntaxhighlight lang=bash><br />
make -f posix.mak html phobos-prerelease<br />
</syntaxhighlight><br />
<br />
Of course, parallelizing with <tt>-j</tt> improves speed as well.<br />
<br />
To informally test it, open the appropriate HTML documents in that directory. Note that the currently released phobos would be in <tt>~/dlang/dlang.org/web/phobos</tt>, whereas the current (fresh) build of phobos's documentation will reside in <tt>~/dlang/dlang.org/web/phobos-prerelease</tt>.<br />
So, for example, if you change the embedded documentation in <tt>~/dlang/phobos/std/conv.d</tt>, the changes are visible in <tt>~/dlang/dlang.org/web/phobos-prerelease/std_conv.html</tt>. (The build process replaces the slashes in submodules with underscores.)<br />
<br />
=== Avoiding network traffic ===<br />
<br />
Note that one of the first lines output during the <tt>make</tt> run looks like this:<br />
<br />
<tt>LATEST={{Latest DMD Version Raw}} <-- place in the command line to skip network traffic.</tt><br />
<br />
That's advice worth heeding because fetching <tt>LATEST</tt> automatically involves network traffic, which adds time to the build. So for future builds use this:<br />
<br />
make -f posix.mak LATEST={{Latest DMD Version Raw}} html phobos-prerelease<br />
<br />
=== Full build ===<br />
<br />
Note that the full build all of the documentation in all forms, including Kindle builds and various other things that may require installing additional tools, and may download/build old versions of DMD. This may take some time and can be run with:<br />
<br />
make -f posix.mak<br />
<br />
Or if you want to avoid network traffic:<br />
<br />
make -f posix.mak LATEST={{Latest DMD Version Raw}}<br />
<br />
== Ancillary stuff ==<br />
<br />
==== <tt>[https://github.com/dlang/dconf.org dconf.org]</tt>, <tt>[https://github.com/dlang/dub dub]</tt>, <tt>[https://github.com/dlang/dub-registry dub-registry]</tt>, <tt>[https://github.com/dlang/installer installer]</tt>, <tt>[https://github.com/dlang/tools tools]</tt>, and <tt>[https://github.com/dlang/visuald visuald]</tt> ====<br />
<br />
These ancillary repositories are of somewhat specific interest. Their installation mimics that of the repositories described above. If you get to the point where you need to work on one of these, chances are you're already versed in what needs doing. If not, [http://forum.dlang.org/group/digitalmars.D ask away].<br />
<br />
==Additional Tools==<br />
<br />
If you cloned {{code|dlang/tools.git}}, you also have a {{code|tools}} folder where small helping programs live. There is no need to build them, you can just compile them using DMD:<br />
<br />
<syntaxhighlight lang=dos><br />
dmd rdmd.d;<br />
dmd ddemangle.d;<br />
dmd dtab;<br />
dmd tolf;<br />
</syntaxhighlight><br />
<br />
{{code|rdmd}} builds your D modules automatically, from the one containing {{code|main}}. It'll deduce dependencies and compile/link them for you.<br />
{{code|ddemangle}} will demangle its input, replacing all mangled D symbols with their unmangled form.<br />
{{code|dtab}} transforms tabs into spaces in source code.<br />
{{code|tolf}} replaces line endings with LF.<br />
<br />
Using {{code|dtab}} and {{code|tolf}} is a good idea if you want to contribute to the dlang repos.<br />
<br />
== Typical Contributor Workflow ==<br />
<br />
There are many ways to use <tt>git</tt> and GitHub to contribute. Here's a typical one.<br />
<br />
First, fork the github repository or repositories you'd like to contribute to (<tt>dmd</tt>, <tt>druntime</tt>, <tt>phobos</tt> etc) by navigating to their respective pages on <tt>github.com</tt> and clicking "Fork". Then, set up your local git repository to reflect that. For example, consider you want to contribute to <tt>phobos</tt> and have forked it. Then run these commands:<br />
<br />
<syntaxhighlight lang=bash><br />
cd ~/code/phobos<br />
git remote add myfork https://github.com/username/phobos.git<br />
git remote update<br />
</syntaxhighlight><br />
<br />
(Replace <tt>username</tt> with your actual github user name.) This adds the "myfork" repository and makes sure everything is synchronized between your local copy and the remote repositories. Then, it's best to work in branches as shown below:<br />
<br />
<syntaxhighlight lang=bash><br />
git checkout -b awesome-new-feature<br />
# ... get some good work done here ...<br />
git commit -am "Awesome new feature ..."<br />
git push -f myfork<br />
</syntaxhighlight><br />
<br />
With this, your work is in your github fork of the <tt>phobos</tt> (or whichever) repository. After that, visit your fork on <tt>github.com</tt>, which looks like <tt>https://github.com/username/phobos/tree/awesome-new-feature</tt>.<br />
<br />
== Create a pull request ==<br />
<br />
Once you have tested all your changes and pushed them to your fork on GitHub, you are ready to submit a pull request.<br />
<br />
* Navigate to your fork of the project on GitHub.<br />
* '''Important''': Select the branch that you made your changes in, say issue_1234.<br />
* Click on the "Pull Request" button.<br />
<br />
This will submit your changes for review by the D maintainers. If your changes are approved, they will be merged into the master branch. Otherwise, if the maintainers have some comments or feedback, you can refine your changes by editing and testing in your local workspace, and pushing the new changes to the same git branch. The new changes will be automatically included in your pull request.<br />
<br />
Choose a title for your pull request that clearly states what it does. When fixing a bug, the usual thing to do is to use the summary from the bugzilla report. Eg a title like "Fix 3797" or "Issue 3797" contains much less information than "Fix Issue 3797 - Regression(2.038): Implicit conversion between incompatible function pointers" and requires a lot more effort for the reviewers to determine if it is something they are interested in.<br />
<br />
Pull request descriptions should contain a hyperlink to the [[Bugzilla]] issue that is being fixed. This is usually added at the end of the description.<br />
<br />
If the pull request is for a bug fix, the commit message should have the format "fix issue 1234". This enables the dlang-bot to automatically pick up the issue from [[Bugzilla]] and post it as a comment on the PR. If the PR is already open, then a git rebase is necessary followed by a force push. During the rebase, the commit message should be renamed to match the one specified.<br />
<br />
After the pull request is created, add the 'pull' keyword to the corresponding Bugzilla issue and a link to the pull request posted in a comment.<br />
<br />
=== Characteristics of a Good Pull Request ===<br />
<br />
* Addresses one topic only.<br />
* Refactorings should not be mixed in with bug fixes or enhancements.<br />
* Refactorings should be marked as such in the subject, and must not contain any behavior changes.<br />
* Larger refactorings need to broken up into smaller PRs.<br />
<br />
The problems with large PRs are:<br />
<br />
* They are hard to review.<br />
* github is very slow at serving pages with large diffs on them.<br />
* If the PR introduces a regression, a large diff is much harder to debug than a small one.<br />
* They imply an all or nothing view of it, when it actually may have good parts and bad parts.<br />
<br />
=== Autotester ===<br />
<br />
Pull requests are automatically picked up by the [[Git Commit Tester|autotester]], which compiles the code in the pull request and runs it through the dmd, druntime, and phobos unittests on all supported platforms. Generally, pull requests must pass all tests before they will be merged. The status of the tests can be monitored through the pull request page.<br />
<br />
Every user must be manually approved before the autotester will start testing their pull requests. Users can be approved by anyone with commit access.<br />
<br />
=== Rebasing ===<br />
<br />
Sometimes, if a particular change you are working on is taking a long time, or if you encounter a problem that is fixed by a new commit upstream, you may need to sync your local branch with master in order to keep the code up-to-date. In this case, it is recommended that you use git rebase to apply your changes ''on top of'' the latest git master, so that when you submit a pull request, the change history will be easier for the reviewers to follow. Using git merge is ''not'' recommended, as it may produce a lot of merge commits that may not be relevant to your changes.<br />
<br />
For example, you may be working on your changes:<br />
<br />
<syntaxhighlight lang=bash><br />
cd /usr/src/d/phobos<br />
git checkout mybranch<br />
vim std/algorithm.d # apply lots of cool changes here<br />
</syntaxhighlight><br />
<br />
First, before you resync with master, make sure all your changes are checked in (or stashed):<br />
<br />
<syntaxhighlight lang=bash><br />
git commit -a<br />
</syntaxhighlight><br />
<br />
If you forked from the official D programming language repositories you may need to add an upstream remote to pull in the latest official changes. If this is the case you can add an upstream remote like this:<br />
<br />
<syntaxhighlight lang=bash><br />
git remote add upstream git@github.com:dlang/phobos<br />
</syntaxhighlight><br />
<br />
This adds another remote to your repository called upstream and only needs to be done once. Once the upstream remote is added, you can update your repository's master branch by running the following:<br />
<br />
<syntaxhighlight lang=bash><br />
git checkout master<br />
git pull --ff-only upstream master<br />
</syntaxhighlight><br />
<br />
The --ff-only option is to ensure that your master branch is identical to the official D sources' master branch, since otherwise you will end up with a very messy history that will be hard to clean up (and the reviewers will probably reject your pull request due to having unrelated merge commits).<br />
<br />
Now go back to your branch and rebase it:<br />
<br />
<syntaxhighlight lang=bash><br />
git checkout mybranch<br />
git rebase master<br />
</syntaxhighlight><br />
<br />
Now your sources should be up-to-date. Recompile and test everything to make sure it all works.<br />
<br />
Note that after rebasing, you will need to force an update to your fork on GitHub with the -f flag, otherwise it will fail because the histories don't match anymore:<br />
<br />
<syntaxhighlight lang=bash><br />
git push -f origin mybranch<br />
</syntaxhighlight><br />
<br />
You may wish to read up on [http://git-scm.com/book/en/Git-Branching-Rebasing how git rebase works] if you're not familiar with the concept.<br />
<br />
If, during the 'git rebase' command, you encounter conflicts, you may want to learn [http://stackoverflow.com/questions/8780257/git-rebase-a-branch-onto-master-failed-how-to-resolve how to resolve a conflict during git rebase].<br />
<br />
=== Squashing ===<br />
<br />
After receiving feedback on your PR, it's common for it to have lots of commits that don't add much by being separate. For example, consider the following git history on a PR:<br />
<br />
commit [ffffff] Added new function: foobar<br />
commit [aaaaaa] Spelling error fix in foobar docs<br />
commit [cccccc] Clarified Docs for foobar<br />
<br />
Nothing is gained from having these as three separate commits as they are all focused on one feature. Instead, they should be one commit so the history looks like this<br />
<br />
commit [333333] Added new function: foobar<br />
<br />
while still retaining all of your changes. In order to perform this, please consult this [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits guide]<br />
<br />
You can also directly append to your last commit and force an update of your PR:<br />
<br />
<syntaxhighlight lang=bash><br />
git commit --amend<br />
git push -f<br />
</syntaxhighlight><br />
<br />
=== Stable Branch ===<br />
<br />
If you are working on a fix for a regression, chances are it should go into the next point release, and not the next major version (e.g. 2.067.1 instead of 2.068). In this case, you should check out the stable branch of each subproject BEFORE you create your topic branch:<br />
<br />
<syntaxhighlight lang=bash><br />
cd dmd<br />
git checkout stable<br />
cd ../druntime<br />
git checkout stable<br />
cd ../phobos<br />
git checkout stable<br />
</syntaxhighlight><br />
<br />
Then follow the instructions for [[#Make your changes in a branch|making a branch]].<br />
<br />
If you forget to do this, or didn't realize it, It's not possible to simply re-target your branch for pulling into the stable branch. GitHub will let you do this, but your branch will include many of the changes from the unstable branch!<br />
<br />
In order to fix such a problem, you can [[#Rebasing|rebase]] your changes from master on top of the stable branch. First you need to pull in the stable branch from your fork on github:<br />
<br />
<syntaxhighlight lang=bash><br />
git checkout stable<br />
</syntaxhighlight><br />
<br />
Then, you go back to your branch, and replay the changes from master using rebase:<br />
<br />
<syntaxhighlight lang=bash><br />
git checkout mybranch<br />
git fetch upstream<br />
git rebase --onto upstream/stable upstream/master mybranch<br />
</syntaxhighlight><br />
<br />
You may have to follow the instructions in the [[#Rebasing|Rebasing section]] on adding the upstream branch, substituting stable for master, if you need to update to the latest stable changes.<br />
<br />
This sometimes may not work, as the changes between the stable and master are too drastic. In this case, you may have to re create your changes after a clean checkout of the stable branch.<br />
<br />
When creating a pull request, you need to tell github to target the stable branch instead of master on the upstream repository. This is done via a drop-down at the top of the page, make sure to do this before submitting your pull request as this cannot be changed after the PR is created (you will have to close the PR and create a new one).<br />
<br />
If you notice in your PR a whole slew of changes that seem to have nothing to do with your changes, it's likely because you forgot one of these steps.<br />
<br />
=== Reviews ===<br />
<br />
Any pull requests that make language changes must be approved by Walter and Andrei. This includes druntime changes that implement the specification.<br />
<br />
Any pull requests that make significant changes to code should be reviewed by more than one person. This means that at least two people need to approve the pull request before it is merged. One person must be a person with commit rights, but the other need not be, as long as that person is trusted within the developer community.<br />
<br />
Pull requests that are trivial (typos, obvious minor bug fixes, etc.) may be pulled without a second review.<br />
<br />
Please note that any updates pushed to the candidate branch do not automatically notify a subscribed person. If you update your branch to correct an issue, please also put in a comment indicating it.<br />
<br />
== Contributing FAQ ==<br />
<br />
=== A file that I made a change on was modified by a different merged PR, and now my PR can't be merged, now what? ===<br />
<br />
What you need to do is rebase your git branch on the master branch. What this does is rewrite the history of your git branch to make it seem like it was merged off of the head of master rather than the older commit where you actually branched. This will include the new commits in your PR so your PR no longer conflicts. See [https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request this tutorial] for more details.<br />
<br />
=== I would to help, but I don't know how. What is the best way? ===<br />
<br />
Anyone is welcome to contribute as D is very much a volunteer effort!<br />
The best place to look for ideas to contribute is the [[Get involved|get involved]] guide.<br />
Please also don't hesitate to point out (or even fix) any stumbling blocks you may encounter when starting out.<br />
<br />
=== CodeCov shows a red cross ===<br />
<br />
On every build the generated coverage files are sent to CodeCov for further processing.<br />
You can see the non-covered lines by clicking on the link or for further convenience in the future by installing the [https://github.com/codecov/browser-extension CodeCov browser extension].<br />
<br />
=== CircleCi shows a red cross ===<br />
<br />
On CircleCi static code analysis is run. For example it lints the Phobos codebase after [https://dlang.org/dstyle.html the DStyle].<br />
Moreover, checks are run to ensure that every example on dlang.org is runnable. On Posix, you can run this locally by executing the <tt>style</tt> target:<br />
<br />
<syntaxhighlight lang=bash><br />
make -f posix.mak style<br />
</syntaxhighlight><br />
<br />
=== The auto-tester shows a red cross ===<br />
<br />
The [https://auto-tester.puremagic.com auto-tester] tests every PR on all supported platforms (Windows, Linux, macOS, and Linux) for 32 and 64-bit builds.<br />
Please click on the link of your PR to find out more about the error.<br />
<br />
=== The Project Tester shows a red cross ===<br />
<br />
The Project Tester tests every PR on all supported platforms (Windows, Linux, macOS, and Linux) for 32 and 64-bit builds.<br />
Please click on the link of your PR to find out more about the error.<br />
<br />
=== How can I link a PR with Bugzilla? ===<br />
<br />
The integration is handled by the [Dlang-Bot https://github.com/dlang-bots/dlang-bot].<br />
If you mention a bugzilla issue in you git commit message, your will get linked to the Bugzilla issue.<br />
For more information, please visit the [https://github.com/dlang-bots/dlang-bot Dlang-Bot's documentation].<br />
<br />
== See Also ==<br />
<br />
* [[Contributing_to_Phobos| Contributing to Phobos]]<br />
* [[Contributing_to_dlang.org| Contributing to dlang.org]]<br />
* [[Guidelines for maintainers]]<br />
* [[Get involved]]<br />
<br />
[[Category: Contribution Guidelines]]</div>Jondegenhardt