Improvements to the development enviroment section

Open
#500 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

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

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.

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\<filename>\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
  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

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

Dominant language
C++
Stars
424
Forks
127
Avg merge
2d 21h
Merged PRs (30d)
5

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from KhronosGroup/Vulkan-Tutorial

All issues in KhronosGroup/Vulkan-Tutorial

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.