Readme overhaul

[Roboron]

The information in the current readme is outdated (the fluisynth library still missing, the new CMake build system too), so I worked on updating it, basing it upon my work done in the wiki page over the last year

=> https://simutrans-germany.com/wiki/wiki/en_CompilingSimutrans

In the process I thought that it could be desirable to add some basic information about Simutrans for people that just discovered the project or was simply looking for a download. So I added this and information about contributing.

At last I also made it a markdown file so we it benefit from the GitHub preview system. There's not much formatting though, so it can be reverted to a fully plaintext file easily if you don't like the idea. I've created an empty repository to show it live and also for sharing because the forum won't let attach it.

=> https://github.com/Roboron3042/simreadme

What do you think?

[KneeOn]

I like it, and I have no issues with a formatted document coming from Windows. I know Linux users might not agree.

[prissi]

Thank you. It is indeed what one expects of a Readme on github.

But we do not really have simutrans on github since access is really only via the SVN and having extended on the simutrans organization automatically forbids having standard there (unless the fork on the aburch is deleted or the simutrans repo is imported fresh from the svn (which is another option).

So the readme must also work for the distribution with the zip file, and that is oviously better as a text file. Can we have both?

On the content: pkgconf is not a library and usually come with the system (on Linux). And as mentioned there are two scripts to set up a simutrans compiling environment on windows for Msys2 (setup-mingw.sh) and MSVC (install-building-libs-XXX.bat) which prepare the environment without worry. This will help the 80%+ windows user a lot, so maybe it should mentioned first?

In principle the setup-mingw.sh script could be easily extended to other package managers (especially since you listed the libary names on various systems) and could prepare a compile envrionment for almost any unix-like system.

The Makefile will stay for a long time, since Android needs it and the build process for Android is complicated (to put it mildly). For building make works fine and need so much shorter section to explain, so why does it come second?

For cmake I recommend "make -j 4" instead "cmake --build . --target install" (The first uses parallel build, which is way faster.) And why target install? Every build will download all the translations and fail if NSIS is not set up (which is not straight forward with MSYS, at least on the two systems I tested.) I strongly recommend to debugs Simutrans with an existing installation. (NB: cmake makes it very hard to see for instance the linker command line. So debugging linker failures is hard with cmake compared to the Makefile we have.)

For MSVC visual compiling/debugging I strongly recommend the simutrans.sln file, where one can test SDL2 and GDI without searching hidden information or editing config files manually. Cmake in MSVC is more a proof of concept. For instance, the only way to add debug arguments is editing json files, and half of that file is reset even after one call. Also one has to click where one usually never need to click ...

Since Simutrans 123, the pakset installer is needed to start Simutrans.

Maybe you wanted to say: "For a full distribution for windows (using sh distribute.sh or cmake build .. --target isntall), NSIS installer is also included." or somethign liek that? Simutrans will happily starts without and can be compiled and debuged without. Two of my four machines have no NSIS installation. Also NSIS is useless to compile for Linux, BSD, or Mac (or Amiga, Haiku, Android, ... )
Furthermore, I think CMake should not fail to build without NSIS as default, since integrating NSIS to MSYS2 is not straight forward.

[Roboron]

Thank you for the feedback, prissi, I've incorporated all of your suggestions and clarifications https://github.com/Roboron3042/simreadme/commit/dd75b2c9919ec705ad20195e2e07e8897bbcb477

having extended on the simutrans organization automatically forbids having standard there

I believe the current fork of simutrans-extended in the simutrans organization has already served its purpose, so we can ask for clearance.

Can we have both?

If you like the current version, I will work on the plaintext version next. EDIT: Actually, I did it already https://github.com/Roboron3042/simreadme/blob/main/readme.txt

In principle the setup-mingw.sh script could be easily extended to other package managers

Good idea, but that's not the objective of this. Also, the setup-mingw.sh script may be better inside the repository than in some forum thread.

For cmake I recommend "make -j 4"

cmake also has this flag. The make instructions didn't mention it either, so I added it to both

On the content: pkgconf is not a library and usually come with the system (on Linux)

"Usually" is the key word here. Me at least, I had to install it when I first compiled simutrans with Freetype support. So better leave it. I have changed "libraries" references to "dependencies" though, to keep the text "technically correct"

And why target install? Every build will download all the translations and fail if NSIS is not set up

I think you misunderstood how the target install works. Such target is only executed after the build is completed, so the build with not fail because of it. Regardless, I've moved the references to distribution out of the "compiling" section to a new "distribution" section, so the target install is not mentioned in the build process anymore, nor is the NSIS install ^.^

Maybe you wanted to say: "For a full distribution for windows (using sh distribute.sh or cmake build .. --target isntall), NSIS installer is also included." or somethign liek that?

Ouch. What a fail. I am ashamed.

[Mariculous]

I believe the current fork of simutrans-extended in the simutrans organization has already served its purpose, so we can ask for clearance.

I could move it back to my own github account

[prissi]

Sorry, I am sometimes a little rude. Blame me being German ... I think the current readme cover most issues with compiling. And I see one can have a txt and md and only the md is show: Very good, so we can have the normal readme .txtin the zip/

Just one thing: I fear the readme has become too long so nobody might actually read it fully. One way out could be linking to a long documentations and rather keep it short like this:

-------------------
You need "pckconfig" or "vcpkg" (for Microsoft visual C++). and "libpng2 libbzip2 zlib" High recommended are "libSDL2 libzstd libfreetype". Optional are miniupnpc (for easy server setup) and libfluidsynth (needed for midi support for Linux and Mac).

You can use the helper script instal... and setup-... to install the libaries needed. (I will out them into the SVN)

After installing the development versions of those libaries you can build simutrans using
1) CMake
mkdir out
cd out
cmake -G "Insert the correct Makefiles GEnerater" ..
cmake build . -j 4
2) make
automake (I think I should include the .cofigure file in the svn, so no automake)
./cofigure
make
3) Microsoft Visual C++
Open the simutrans.sln, select the target (default is GDI) and build.

--------------------------
The comments about release/debug (and especially stable, did overlook this for years ... ) builds are not really needed there, since no you but you and me releases stable versions. That short people may be more likely to read it, adn the long part is better a wiki page, which one can update should new libaries be needed.

[Andarix]

It should also be possible to include a redme.html or compile.html.

Browsers exist on every graphical system. The formatting and links should also be more user-friendly.

[prissi]

Converting the readme.ml into hmtl would jsut invole saving the github page as html and remove the surrounding clutter. Should be easy. ANd indeed, html may be a good alternative.

[Roboron]

Sorry, I am sometimes a little rude. Blame me being German ...

Don't worry; I do.

Just one thing: I fear the readme has become too long so nobody might actually read it fully. One way out could be linking to a long documentations and rather keep it short

Okay, the readme.txt I shortened it by a lot, only practically leaving high-level links to the wiki in most cases, and shortened a lot the getting the dependencies section.

On both readme.txt and readme.md I removed the distribution step and shortened the build section and the getting the dependencies section as you suggested. Only on the readme.md I left the first table.

Converting the .md to html could be done using pandoc, I think.

[prissi]

I will give you commit rights to the svn, check you inbox.

[Roboron]

Added in r10369.

Wow, I can say that now!

[Yona-TYT]

Wow, I can say that now!

Congratulations hehehe.