instructions don't list required tooling

[Pomax]

Trying to run make generates the following error:

C:\Users\Pomax\Git\Font-Validator> make
mkdir -p bin
for target in Compat OTFontFile Compat.2nd ValCommon GMath Glyph OTFontFileVal;
do \
            make bin/${target}.dll ; \
        done
make[1]: Entering directory '/cygdrive/c/users/mike/documents/Git projects/collaborations/Font-Validator'
( cd Compat     && \
        mcs -debug- -optimize+ -target:library  -lib:../bin/ -r:SharpFont -r:System.Windows.Forms -out:../bin/Compat.dll *.cs )
/bin/sh: line 1: mcs: command not found

Can the readme be extended with the set of tools that are used during the make run, so that people can check whether they have all the prerequisites in place? Some googling reveals that mcs is the Mono c# compiler, something which I'm sure lots of people won't be familiar with =)

[HinTak]

The readme says mono is required!

[HinTak]

Hmm, I suppose the first line of the build section can be longer - "adapted for building with the mono c# compiler mcs instead of Microsoft 's csc. ". I forgot something that was taken for granted from the beginning - the aim was to take the existing code base and try to make it work on non-windows. MS's original plan was simply to release a partial source to enable a python rewrite to happen.

I got in the middle that discussion and said, there is mono, and it is quicker/better than a whole-sale rewrite... Thus the partial source became mine to make whole...

[Pomax]

Yeah, just https://github.com/Microsoft/Font-Validator/blob/master/README.txt#L23 is not really enough =)

A "Requirements" section for builds that rely on external tools, with links to the tools needed, is usually the best way to make sure people understand what they need to have in place before they type make. It can be a short section, but it makes quite a big difference.

[HinTak]

Running on non-windows requires the mono runtime; on windows, it is just dotnet runtime which has been shipping as standard on windows for years (used to be optional additional download around windows 98/2000?).

Xamarin only distinguishes the runtime vs +compiler/SDK for Mac OS X. On Linux and windows, if you download/install "mono", you get both the runtime and the compiler. (the concept is entirely parallel that in Java - .dll/.exe in the dotnet universe is platform-independent but requires a runtime, which windows ships by default nowadays).

You need both the mono mcs C# compiler and GNU make as a bare minimum to start changing the code and building it. There are specific parts, which requires monodevelop (the GUI based mono development environment; quite large and many additional dependencies and quite difficult to install from source - I tried to get the latest, and filed many bugs at redhat's bugzilla on missing stuff, etc), Microsoft Help Workshop, and genuine Windows .NET SDK tools to build - when mono's corresponding tools are inadequate. I haven't documented much of these, except for a small paragraph in the Makefile, and README-extra.txt (the filed bug listings therein!), and perhaps some part of Font-dev.pdf .

I wanted to keep the README brief - if I put too much stuff in it, I suspect people would just not read the whole thing if it is too long. But I'd think about editing the above and put it up as a FAQ or something.

[HinTak]

When I took this on, building on windows was not a priority - the source (which did not build) was meant to be released as a reference for a python rewrite to happen.

In any case, Microsoft removed the visual studio related files before giving it to me (this is mentioned on the first page of FontVal-dev.pdf). However, if you are on windows, you should look into re-adding visual studio related things back. This specifically means a *.csproj file. The microsoft C# compiler is in many ways "nicer" than the mono C# compiler.

[Pomax]

Remember that on github, no one may have prior experience: I'm a JS dev, not a C# dev, so I have no idea what I need to build this. I have visual studio express installed because some node modules need it to install, but that's my only experience with "windows-only" tooling (I'm on windows 7 pro x64, but as I tend to work on JS code, almost nothing I work with requires special compiles)

I looked at the "build" section of the readme since that's where I'd expect the build instructions to be, didn't see any "you need ... installed before this can compile" notices, and then tried running "make". That then got the error that "mcs" was not a known command, breaking the build, so that's a thing the readme can prevent for other people, even windows users that aren't necessarily windows developers.

[HinTak]

There is always the issue of how much hand-holding one provides, until it get swarmed in noise.

The bulk of Font Validator is in C#, so some degree of familiarity with the typical C# development is assumed. The "orthodox" C# development is MS visual studio/ Microsoft C# compiler, hence that's assumed, and so there is one sentence at the build section saying this is not built with the orthodox system. It is meant to be sufficient to people who are familiar with the orthodox system.

FWIW, microsoft removed all support files for building under the orthodox MS visual studio/ C# compiler system, so I never saw anything in that direction, and I never tried in that direction. You are welcomed to re-add that.

in the orthodox system, one would not include URLs in the README for where to download Microsoft visual studio express (for people who do not want to pay for the licensed full version) or where to buy a version of MS visual studio either. That said, if you want to submit a patch for the README, you are free to do so, and up to the microsoft folks to include the change.

[Pomax]

My point was that this repo makes getting the latest version of the Font Validator a super simple process, for anyone. Anyone can build it now, as long as you at least tell them what they need to run that build process, and that explanation is only a few extra lines in the readme: that should really not be a big deal. The level of hand-holding involved will pretty much be the same as any other popular github-hosted project: your audience is no longer just "developers" once you host on github, it's "everyone" =)

You'll find a lot of great projects on github have links in the readme.md for required tooling, so links to mono and visual studio express aren't really out of place: they're appreciated by people who run across this project. It lets them know that even though the code's been written by highly skilled people, you don't need to be a developer just to compile this project. Anyeone can just check that they have what is needed to build it, and then type one command, and done: they can use the application. That's fantastica for people who aren't developers: I know opentype, I know nothing about C#, I just wanted to compile the Font Validator to test my fonts with a more modern version that is currently available from Microsoft.

I'll file that PR, this was a little more "why should we make things easier?" as opposed to "a small improvement that make things much better? let's do it!" than was necessary =)

[HinTak]

It is good to clarify what info should be provided.

I am a bit too familiar with it to see problems from the point of view of somebody starting now. Could wait for one or two newcomer's input then update it in one go.

[HinTak]

I updated the top-level README because building with MS Visual Studio has been mostly re-added. Have a look and see what you think:

https://github.com/HinTak/Font-Validator/commit/392101a2b5375c15ffff58aa4e6d3ac4ff6a7de2

Note that the Compat module (the module I wrote for replacing everything that Microsoft did not open) does not build with MS VC# yet. It should be straight-forward, it isn't done yet mainly because I don't use MS VC# regularly enough, nor windows itself for that matter :). Tips to go about that is here: https://github.com/HinTak/Font-Validator/issues/8#issuecomment-186716648

[Pomax]

I'll give it a look over, but would it make sense to rename README.txt to README.md, since it's using md formatting and is far more informative than the README.md that's currently used?

[HinTak]

On my fork, README.txt was renamed to README.md 3 months ago, 2 days after it went public...

[Pomax]

ah, was looking at the wrong repo.