KhronosGroup / KhronosGroup/Vulkan-Tutorial

Improvements to the development enviroment section

Open
#500 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
418
Forks
126
Avg merge
11d 6h
Merged PRs (30d)
31

Description

## Summary

Currently, after compiling the project is not clear how to check if your enviroment is valid.
The binaries will launch a black screen, so beginners might believe they have a wrong enviroment.

## Proposed changes

### Add a section on running examples

I would recommend adding a final section explaining that most binaries will produce a black screen, along with a table containing some tutorial binaries, the name, expected image, and folder to run them.

It is also not clear that binaries have to be run from their `build\\Debug` folder, so we should explain that.

### Add a quick start section

I am not sure about this. I wonder whether we should add a small `Quick start` section with just the basic steps. This should make it easier for people to just build and test the repository:

> 1. Install [vcpkg](https://github.com/microsoft/vcpkg)
> 2. Run the installation script for your plaform.
> * **Linux:** `scripts/install_dependencies_windows.bat`
> * **Windows:** `scripts/install_dependencies_windows.bat`
> * Read `Common considerationss` for more details
> 3. Create a CMake project for your favorite IDE
> * From attachments: `cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path\to\vcpkg]\scripts\buildsystems\vcpkg.cmake`
> * Read `Setting up a CMake project`
> 4. You should be able to open, compile and run the project on your favorite IDE
> 5. Alternatively:
> - Compile with `cmake --build .\build`
> - This will generate binaries for each the step in the tutorial.
> - Go to the expected directory `cd attachments\build\28_model_loading\Debug`
> - Run: `.\28_model_loading.exe`
> - You should view something similar to [this](images/drawing_model.png)

Having an image like this at the beginning also indicates what you will learn to do by following the tutorial. I think we also add and to `00_introduction.adoc`.

### Rename the section

Not sure if `Development_enviroment` is the best name. I think we should include `build` in the name.
Some people might just want to test if they can use Vulkan in their machine, before they start to follow the tutorial.
I think this section will be more easy to find as `Build_and_development_enviroment`

Contributor guide

Open the contributing guide

Research direction

Locate the Development_enviroment section and 00_introduction.adoc, then inspect the existing setup instructions, scripts, and attachments examples. Document how to build and run an example from its build//Debug folder, explain expected output such as the black screen, and add the agreed quick-start or section rename. Verify the commands and example path against the repository.

Written by the indexing model from the issue text.

Assessment

Tech stack
cmake, cpp
Domain
build-system, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.