Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: COMPILING.md does not describe how to make a non-debug build on non-Windows #8465

Closed
JGRennison opened this issue Dec 29, 2020 · 5 comments

Comments

@JGRennison
Copy link
Contributor

@JGRennison JGRennison commented Dec 29, 2020

Version of OpenTTD

Since CMake

Expected result

COMPILING.md should describe how to use CMake to produce a build which is suitable for normal users (i.e. not a slow debug build), on non-Windows platforms.
Ideally the commands closest to the top of the file should produce a playable build suitable for normal users.

Actual result

The suggested set of commands is:

mkdir build
cd build
cmake ..
make

which produces an unplayably slow binary.

There is no mention of CMAKE_BUILD_TYPE or equivalent mechanisms anywhere in the file (or on the wiki).
Normal users don't know anything about CMake and will not know that they should set this without prompting.

Steps to reproduce

N/A

@TrueBrain
Copy link
Member

@TrueBrain TrueBrain commented Jan 1, 2021

What is always a bit difficult for me with tickets like this: this describes a solution, but it gives me very little information about the problem itself.

The audience for COMPILING.md is not "normal" users, but developers. And developers that use a CMake project, should know how to target debug vs release (or really: learn CMake), but they are also very likely to need a Debug build, not a Release build. So I am more curious why a normal user is compiling from source at all?

I can think of various of reasons, but you made this ticket not without reason; so before I fill in all kinds of blanks, it might be better to just ask you: what triggered you to make this ticket? What is this group of normal users that compile and expect a non-debug build? (I have some ideas of my own, but I rather have you tell me your side first :) ).

If I understand a bit more what problem we are trying to solve here, there might be better solutions then to just extend COMPILING.md with some snippets how to create a release build. This is mostly as I am not sure that is really solving the problem. At least, the problem I see (by reading forums, Discord, and my own experience), would require a bit more generic solution then pointers in COMPILING.md :) But again .. I am trying to not get ahead of myself, and first let you draw me a picture :)

Tnx!

@JGRennison
Copy link
Contributor Author

@JGRennison JGRennison commented Jan 1, 2021

Having reference material on how to compile a project that makes no mention of how to make a normal build seems to me like a significant omission. I primarily created this issue because I read through the documentation and was surprised that I could not find this mentioned anywhere.

Personally, I find the idea of producing unoptimised debug builds by default to be very strange, but I am aware that that is how it is usually done in the CMake ecosystem.

For what its worth I all do all of my testing and debugging on builds with optimisations enabled and in my branch the default configuration enabled optimisations, so this does not affect me personally in that sense.

If the omission is intentional I've got no objection to the issue being closed.

@TrueBrain
Copy link
Member

@TrueBrain TrueBrain commented Jan 1, 2021

Ah :) Tnx for the clarification :D
I was hoping you had users having issue with Linux builds etc :P I would have loved to solve that issue :D Happy I asked :)

I looked around how other CMake projects do it, and exactly what you say: this is the default for CMake projects, and our default has always been to produce debug builds. Release builds have their own problem .. for my Ubuntu version for example it takes ~60 seconds to link the final binaries, which is not really useful when developing ;) I guess this is a matter of taste, more than anything else :)

I will ask what other devs think about this; personally I am fine by following what CMake defined; going against the stream also has its problems.

Tnx again for the clarification, much appreciated!

@TrueBrain
Copy link
Member

@TrueBrain TrueBrain commented Jan 2, 2021

I went for the middle-ground here: we now link to the CMake usage tutorial, which (if you CTRL+F) mentions how to make a Release. This is a bit the balance between being verbose about it and still showing how it should be done. Hopefully you agree that it is a nice in-between solution :)

@TrueBrain
Copy link
Member

@TrueBrain TrueBrain commented Apr 21, 2021

okay, few months later, I retract my original opinion. @JGRennison , you are right, it should be documented better. PR incoming :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
2 participants