Closed Gerold55 closed 5 years ago
Well was done to make sure that people can understand how to build it and add references to how to clone and to fork.
This is in my opinion, far from the greatest I've seen for build guides.
A more useful suggestion would be:
Building of this project is a simple endeavour, requiring only a few commands.
Initially, a clone of the repository will be required, however, if you plan on making edits first, make sure you fork the repo beforehand, and clone that.
An example command for cloning the repository is:
git clone https://github.com/GentenStudios/quartz-engine.git
Once cloned, enter the directory, by doing `cd quartz-engine``, and complete the following commands:
cmake -H. -BBuild
cmake --build Build
These commands will take a fair amount of time to complete, the first one configures the project and appropriate compilers, whereas the second command actually builds the project using those configurations. To run the executable, for MSVC/Windows users, go into Build/QuartzSandbox
and move QuartzSandbox.exe
out of Debug
and into this folder. You can then run it.
An alternative way of building is executing the initial cmake -H. -BBuild
command to generate Visual Studio Solution files, After doing so, go into the Build
folder, and open Quartz.sln
. Then find the build button and press it, or press F5. The initial run of the application may fail and there will be an error about a startup project. If so, locate the QuartzSandbox project in the sidebar, and right click, then select Set as Startup Project
, then press F5 or the Run button.
Voila! You've successfully built QuartzEngine and run the sandbox application, now feel free to start contributing in any way you can!
This is super wordy and can be improved, but it's still much better than what's been provided in the PR.
There are currently no markdown code markers in this, and like I said, this is still wordy and needs a lot of work, a simple copy paste from a badly written example isn't of any use to any newcomers.
I'm going to argue that this takes us in the wrong direction. A build guide should NOT teach the end user how to use the tools needed to build. If we need to explain in our build guide how to open a bash terminal then the end user has no business playing around in said bash terminal and a tutorial on how to use Git would be more appropriate before attempting this (not to mention if were on windows direct them to the Github GUI or a tool built into an IDE long before asking someone to open a bash terminal).
Our build guide should only provide information specific to our project, maybe the steps that need taken, but not how to use a computer or tools.
I think we could mix the 2 together so it's a little more understandable but also so that not the average noob can understand it. I hope that makes sense. I can reduce the step by step down a bit
You know what, I couldn't agree more with Austin, we should provide basic commands like the CMake ones, as a lot of even experienced people haven't used CMake, but in no way should we be having to show them how to clone or cd into directories, all we should tell them is the command for generating CMake files, and building the project via the required CMake command, as we have already.
In a nutshell, maybe slightly reword what we have if people have trouble with it in the future, but IMO, if they really are a n00b, they shouldn't be trying to jump straight in to a game engine, and could probably just join the discord and ask us how to do things, where any of us Devs are more than happy to guide them through the process.
@Gerold55 Just as a note this has been sitting for a bit.
Yes ik I'm trying to figure out how to make it sound right that everyone likes
I've also have had some life issues
The README should include its instructions concisely step-by-step without being too wordy; the README here is a good example https://github.com/Kitware/CMake/blob/master/README.rst
I just updated my comments above for the sake of making them more to the point.
For starters, the README from the CMake repository is a very good example.
@beeperdeeper089 @apachano The PR got updated. Can you guys reevaluate? I already gave some feedback to gerold on discord.
On line 29 you call visual studio "visual studios" The PR is also a bit "over worded" I think some more effective wording can be good. I didn't do an actual review as I do not know what improvements need to be made exactly.