Vision document for H1 2018

[SealabJaster]

On Sunday, 11 March 2018 at 17:15:28 UTC, Seb wrote:
> What could be done from your perspective to make the setup 
> easier?

(This is from the perspective of a novice programmer, who hasn't 
really interacted with open source projects much)

When I first tried to compile dmd+druntime+phobos quite a while 
ago, I found the information on the wiki about building on 
windows[1] pretty unhelpful (in fact I never managed get all 3 to 
compile properly), though that seems to have gotten a lot better 
now (especially that it tells you how to structure your 
directories, which from what I remember you just had to piece 
together and guess from what the wiki commands were doing 
originally). Luckily the two contributions I made back then 
didn't require me to actually have any of that working...

As a spoiled Windows user, I like convenience, and I like things 
being easy to do. For me, trying to simply build everything was a 
frustrating task that took up a few days of time (reminder, this 
*was* quite a bit ago before the Windows part of the wiki was 
updated, and I was/still am pretty new to working on projects 
that aren't my own).

One of the more frustrating yet annoyingly simple issues I was 
having was that the version of Make in my PATH (GNU Make at a 
guess) wasn't able to use win32.mak, which led to me getting 
confused and frustrated for a day or two before I figured 
out(can't remember how exactly) that I had to use Digital Mars' 
make... I don't think there's any clear text on the wiki that 
says "For Windows, you *need* to use Digital Mars' make to use 
win32.mak".

After I changed to using Digital Mars' Make, I ran into another 
annoying but very simple issue. The wiki says to use "make 
-fwin32.mak release", ok fine:
```
PS D:\Coding\D\Tools\dlang\dmd2\src\dmd\src> make -fwin32.mak 
release
Error: can't read makefile 'win32'
```

Turns out all I had to do was put a space between '-f' and 
'win32.mak'. Thankfully I only wasted about 30mins at most 
figuring that out. Didn't make it any less frustrating though.

Around the time I was adding std.traits.isCopyable to Phobos, I 
thought to myself "Maybe I can at least get the testing stuff to 
work!"... So I go to the wiki and see something along the lines 
of "make -fposix.mak std/traits.test" and thought that win32.mak 
would have the same functionality - however it doesn't, and only 
has a target to unittest the entirety of Phobos, giving me the 
impression Windows seems to just be a footnote compared to Posix 
platforms. ('make -f win32.mak dscanner' is another example). For 
isCopyable, it was easier for me to just develop it in it's own 
file, move it into std.traits, and hope the auto-tester could 
build it.

I think I did manage to get "make -f win32.mak unittest" (for 
phobos) to work at one point, but a test that included sockets 
failed (I think it was a test between paired sockets, and one of 
them timed out). This of course made it feel pointless to use, 
since it'd just always fail.

One last example of a very tiny issue, is that for DMD, the 
makefiles you use to build it are in, for example 
'dmd2/src/dmd/src/win32.mak', instead of 'dmd2/src/dmd/win32.mak' 
making it a bit inconsistent with 
druntime('dmd2/src/druntime/win32.mak') and 
phobos('dmd2/src/phobos/win32.mak').

There were certainly a bunch more tiny issues and bumps I had 
when trying to build things my first time around that I can't 
remember, whether it be due to my own incompetency or due to 
issues with the wiki/win32.mak, and after the two changes I made 
to Phobos I just had no will to continue, and gave up for a while.

I genuinely feel it'd have been easier for me to just load up 
Ubuntu on a VM and go from there, instead of developing on 
Windows.

One thing I'd would have liked, as a Windows/lazy user, and as a 
beginner, is a single file/tool that would've helped me setup and 
build everything (like that setup.sh you linked, except it's a 
Bash script...)

And in a perfect world, we wouldn't need 3 different makefiles 
(win32.mak, win64.mak, and posix.mak), but instead there'd either 
be a single makefile, or some other tool is used to provide a 
cross-platform way to access the current features of posix.mak. I 
understand that this isn't an easy issue to solve though, hence 
the "in a perfect world" (you could also say, in a perfect world, 
everyone develops on a Posix platform! ;)).

Then I recently gathered up the will to want to contribute again, 
and decided to make a Powershell script that does exactly that 
for me which actually turned out to work pretty well, I can build 
all 3 projects without too much hassle, and without having to 
remember all those annoying pitfalls e.g. "-f win32.mak instead 
of -fwin32.mak", something I would've liked to have in the first 
place. Or so I thought.

I wanted to try and add some colouring[2] to dmd's error messages 
(sounds easy enough right?), so I have a quick look and see all I 
need to do is add some backticks around certain parts of the 
error message[3, as an example]. So I add my backticks into one 
error I can easily trigger, build it using my powershell script, 
and then all I see is that an exception (I think it was actually 
a RangeError) was thrown, and the stack trace was just a bunch of 
addresses without any text. (I don't have that build of dmd.exe 
anymore, and most of dmd has been colourised by now, so I can't 
get an accurate copy-paste of what happened or try to reproduce 
it.)

I decided "that's not supposed to happen", and tried to colourise 
a few other error messages... but I got the exact same result. I 
try to take an already coloursised error message, copy and paste 
it to another file, and try again to no avail.

At that point I decided that it's probably yet another issue with 
my build environment that I'll have to try an work out, but if I 
can't even get something 'trivial' such as colouring in messages 
working without frustration, then I can't be bothered to put in 
any more effort with trying to do anything else (I'd rather not 
be stuck only being able to do documentation changes), since, at 
least in my experience, I'm probably just too inexperienced, and 
I just keep hitting road blocks and endless frustrations.

I have a lot of free time, and I have a lot of love for this 
language, but when I struggle to get _anything_ to work (and also 
struggle to find something I'm actually capable of trying to do, 
I find Bugzilla a bit hard to use) then it makes me demotivated. 
Maybe I'm missing something, maybe I'm just an idiot, maybe the 
wiki is incorrect, etc. There's clearly _something_ wrong with 
what I'm doing, but I can't bring myself to try and figure out 
what anymore (I say that, but I know full well I'll shortly want 
to try again, and again, and again, until I can finally help out 
with dlang ;( ). I'd like to note that the process of submitting 
the PRs didn't make me run into any issue (though, the changes 
were really simple, so I doubt there was much room for something 
to stop them)

This post may not be all that helpful, but I feel the need to 
voice the frustrations with my experience. Sorry for the 
pointless/off-topic rant.

[1] https://wiki.dlang.org/Building_under_Windows
[2] https://github.com/dlang/dmd/projects/2
[3] https://github.com/dlang/dmd/pull/7781/files