Cross Compilation Guide for New Users

[Dan]

Hi Dlang forums.

I ran into some problems when trying to cross compile. Hope this 
clarifies the set-up for anyone with the same problems.

Additionally, perhaps these more explicit instructions / pitfalls 
could be put into the official [wiki page about cross 
compiling](https://wiki.dlang.org/Cross-compiling_with_LDC). As a 
new user, this would have helped greatly.


# Guide

## Step 1: Obtain an LDC distribution compiled for the target
Prebuilt LDC binaries are found on the [LDC GitHub repo's 
releases page](https://github.com/ldc-developers/ldc/releases/)

For a 64-bit windows target, download 
`ldc2-<version>-windows-x64.7z`. (note that you may need to click 
"see all releases", as some may be hidden by default).

Extract this archive.

Find the "lib" folder in the archive, then rename and move it to 
a system-wide location. The wiki page recommends 
`%%ldcbinarypath%%/../lib-win64`, which on my system is 
equivalent to `/usr/lib-win64`



## Step 2: Tweak the LDC Configuration file

As per [Cross Compiling with 
LDC](https://wiki.dlang.org/Cross-compiling_with_LDC), add your 
target "triple" name to the `ldc2.conf` file, putting the path to 
your target's "lib file" (the one that we extracted and moved in 
step 1) inside `lib-dirs = [ ... ]`.

 From my personal testing, lib-dirs allows absolute and relative 
paths.

### Pitfall 1: Using the "wrong" LDC configuration file

Before tweaking the system-wide configuration in 
`/etc/ldc2.conf`, I wanted to test one out in the current working 
directory of my project, which according to [Using 
LDC](https://wiki.dlang.org/Using_LDC), is one of valid places 
that LDC will find a configuration file. I incorrectly assumed, 
however, that ldc2 will read both the local and system-wide 
config files.

So, I copied the the "Win64" configuration snippet from [Cross 
Compiling with 
LDC](https://wiki.dlang.org/Cross-compiling_with_LDC) into a 
local `ldc2.conf` (into my project's root), and ran `ldc2 
-mtriple=x86_64-windows-msvc source/app.d`, but received an error


```
Error: `object` not found. object.d may be incorrectly installed 
or corrupt.
        ldc2 might not be correctly installed.
        Please check your ldc2.conf configuration file.
        Installation instructions can be found at 
http://wiki.dlang.org/LDC.
```

This happens because unlike our local configuration file, the 
system wide one (at `/etc/ldc2.conf`) contains a line that tells 
ldc2 where to find necessary files.

```
default:
{
     // ...
     post-switches = [
         "-I/usr/include/dlang/ldc",
     ];
     // ...
}
```

#### Solution 1: Use the system-wide ldc2.conf only

Copy your configuration to the system-wide `/etc/ldc2.conf`, then 
**delete the `ldc2.conf` inside the poject directory**

#### Solution 2: Add post-switches to the local config

Add the following lines to your local `ldc2.conf`, under 
`switches`. replace `-I/usr/include/dlang/ldc` with a different 
ldc includes path if necessary.

```
     post-switches = [
         "-I/usr/include/dlang/ldc",
     ];
```


### Pitfall 2: Incorrect "lib-dirs" option

If you left your `lib-dirs` path as 
`"%%ldcbinarypath%%/../lib-aarch64"`, it may be incorrect.

This value must reflect the location of the "lib" folder that we 
extracted and moved in step 1.



## Step 3: Verify cross compilation is working

Compile a Dlang file for your target using ldc2. In my case, the 
command was `ldc2 -mtriple=x86_64-windows-msvc source/app.d`

If everything is set up correctly, congratulations! We now know 
how to cross compile with Dlang.