mirror of
https://git.eden-emu.dev/eden-emu/eden
synced 2026-05-07 06:39:06 +00:00
[docs] Clean up debug and development docs + fix mdlint (#3936)
Signed-off-by: crueter <crueter@eden-emu.dev> Reviewed-on: https://git.eden-emu.dev/eden-emu/eden/pulls/3936 Reviewed-by: Lizzie <lizzie@eden-emu.dev> Reviewed-by: MaranBr <maranbr@eden-emu.dev>
This commit is contained in:
crueter
parent
86eae5cc41
commit
65beea7c73
|
|
@ -9,6 +9,7 @@ When reporting issues or finding bugs, we often need backtraces, debug logs, or
|
|||
If your bug is related to a graphical issue--e.g. mismatched colors, vertex explosions, flickering, etc.--then you are required to include graphical debugging logs in your issue reports.
|
||||
|
||||
Graphics Debugging is found in General -> Debug on desktop, and Advanced Settings -> Debug on Android. Android users are all set; however, desktop users may need to install the Vulkan Validation Layers:
|
||||
|
||||
- Windows: Install the [Vulkan SDK](https://vulkan.lunarg.com/sdk/home)
|
||||
- Linux, BSD, etc: Install `vulkan-validation-layers`, `vulkan-layers`, or similar from your package manager. It should be located in e.g. `/usr/lib64/libVkLayer_khronos_validation.so`
|
||||
|
||||
|
|
@ -30,15 +31,16 @@ Ignoring SIGSEGV when debugging in host:
|
|||
### gdb
|
||||
|
||||
You must have GDB installed for aarch64 to debug the target. Install it through your package manager, e.g.:
|
||||
* On Arch:
|
||||
* `sudo pacman -Syu aarch64-linux-gnu-gdb`
|
||||
* On Gentoo:
|
||||
* `sudo emerge --ask crossdev`
|
||||
* `sudo crossdev -t aarch64-unknown-linux-gnu --ex-gdb`
|
||||
|
||||
Run `./build/bin/eden-cli -c <path to your config file (see logs where you run eden normally to see where it is)> -d -g <path to game>`
|
||||
Or `Enable GDB Stub` at General > Debug, then hook up an aarch64-gdb:
|
||||
* `target remote localhost:6543`
|
||||
- On Arch:
|
||||
- `sudo pacman -Syu aarch64-linux-gnu-gdb`
|
||||
- On Gentoo:
|
||||
- `sudo emerge --ask crossdev`
|
||||
- `sudo crossdev -t aarch64-unknown-linux-gnu --ex-gdb`
|
||||
|
||||
Run `./build/bin/eden-cli -c <path to your config file (see logs where you run eden normally to see where it is)> -d -g <path to game>`, or `Enable GDB Stub` at General > Debug, then hook up an aarch64-gdb:
|
||||
|
||||
- `target remote localhost:6543`
|
||||
|
||||
Type `c` (for continue) and then if it crashes just do a `bt` (backtrace) and `layout asm`
|
||||
|
||||
|
|
@ -69,26 +71,27 @@ For more information type `info gdb` and read [the man page](https://man7.org/li
|
|||
|
||||
## Simple checklist for debugging black screens using Renderdoc
|
||||
|
||||
Renderdoc is a free, cross platform, multi-graphics API debugger. It is an invaluable tool for diagnosing issues with graphics applications, and includes support for Vulkan. Get it [here](https://renderdoc.org).
|
||||
Renderdoc is a free, cross platform, multi-graphics API debugger. It is an invaluable tool for diagnosing issues with graphics applications, and includes support for Vulkan. Get it at [renderdoc.org](https://renderdoc.org).
|
||||
|
||||
Before using renderdoc to diagnose issues, it is always good to make sure there are no validation errors. Any errors means the behavior of the application is undefined. That said, renderdoc can help debug validation errors if you do have them.
|
||||
|
||||
When debugging a black screen, there are many ways the application could have setup Vulkan wrong.
|
||||
Here is a short checklist of items to look at to make sure are appropriate:
|
||||
* Draw call counts are correct (aka not zero, or if rendering many triangles, not 3)
|
||||
* Vertex buffers are bound
|
||||
* vertex attributes are correct - Make sure the size & offset of each attribute matches what should it should be
|
||||
* Any bound push constants and descriptors have the right data - including:
|
||||
* Matrices have correct values - double check the model, view, & projection matrices are uploaded correctly
|
||||
* Pipeline state is correct
|
||||
* viewport range is correct - x,y are 0,0; width & height are screen dimensions, minDepth is 0, maxDepth is 1, NDCDepthRange is 0,1
|
||||
* Fill mode matches expected - usually solid
|
||||
* Culling mode makes sense - commonly back or none
|
||||
* The winding direction is correct - typically CCW (counter clockwise)
|
||||
* Scissor region is correct - usually same as viewport's x,y,width, &height
|
||||
* Blend state is correct
|
||||
* Depth state is correct - typically enabled with Function set to Less than or Equal
|
||||
* Swapchain images are bound when rendering to the swapchain
|
||||
* Image being rendered to is the same as the one being presented when rendering to the swapchain
|
||||
|
||||
- Draw call counts are correct (aka not zero, or if rendering many triangles, not 3)
|
||||
- Vertex buffers are bound
|
||||
- vertex attributes are correct - Make sure the size & offset of each attribute matches what should it should be
|
||||
- Any bound push constants and descriptors have the right data - including:
|
||||
- Matrices have correct values - double check the model, view, & projection matrices are uploaded correctly
|
||||
- Pipeline state is correct
|
||||
- viewport range is correct - x,y are 0,0; width & height are screen dimensions, minDepth is 0, maxDepth is 1, NDCDepthRange is 0,1
|
||||
- Fill mode matches expected - usually solid
|
||||
- Culling mode makes sense - commonly back or none
|
||||
- The winding direction is correct - typically CCW (counter clockwise)
|
||||
- Scissor region is correct - usually same as viewport's x,y,width, &height
|
||||
- Blend state is correct
|
||||
- Depth state is correct - typically enabled with Function set to Less than or Equal
|
||||
- Swapchain images are bound when rendering to the swapchain
|
||||
- Image being rendered to is the same as the one being presented when rendering to the swapchain
|
||||
|
||||
Alternatively, a [RenderDoc Extension](https://github.com/baldurk/renderdoc-contrib/tree/main/baldurk/whereismydraw) ([Archive](https://web.archive.org/web/20250000000000*/https://github.com/baldurk/renderdoc-contrib/tree/main/baldurk/whereismydraw)) exists which automates doing a lot of these manual steps.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Development guidelines
|
||||
|
||||
## License Headers
|
||||
|
||||
All commits must have proper license header accreditation.
|
||||
|
||||
You can easily add all necessary license headers by running:
|
||||
|
||||
```sh
|
||||
git fetch origin master:master
|
||||
.ci/license-header.sh -u -c
|
||||
|
|
@ -11,6 +13,7 @@ git push
|
|||
```
|
||||
|
||||
Alternatively, you may omit `-c` and do an amend commit:
|
||||
|
||||
```sh
|
||||
git fetch origin master:master
|
||||
.ci/license-header.sh
|
||||
|
|
@ -22,8 +25,10 @@ If the work is licensed/vendored from other people or projects, you may omit the
|
|||
For more information on the license header script, run `.ci/license-header.sh -h`.
|
||||
|
||||
## Pull Requests
|
||||
|
||||
Pull requests are only to be merged by core developers when properly tested and discussions conclude on Discord or other communication channels. Labels are recommended but not required. However, all PRs MUST be namespaced and optionally typed:
|
||||
```
|
||||
|
||||
```txt
|
||||
[cmake] refactor: CPM over submodules
|
||||
[desktop] feat: implement firmware install from ZIP
|
||||
[hle] stub fw20 functions
|
||||
|
|
@ -34,7 +39,7 @@ Pull requests are only to be merged by core developers when properly tested and
|
|||
- The level of namespacing is generally left to the committer's choice.
|
||||
- However, we never recommend going more than two levels *except* in `hle`, in which case you may go as many as four levels depending on the specificity of your changes.
|
||||
- Ocassionally, up to two additional namespaces may be provided for more clarity.
|
||||
* Changes that affect the entire project (sans CMake changes) should be namespaced as `meta`.
|
||||
- Changes that affect the entire project (sans CMake changes) should be namespaced as `meta`.
|
||||
- Maintainers are permitted to change namespaces at will.
|
||||
- Commits within PRs are not required to be namespaced, but it is highly recommended.
|
||||
|
||||
|
|
@ -50,6 +55,7 @@ When adding new settings, use `tr("Setting:")` if the setting is meant to be a f
|
|||
- Try to not write "slow/fast" options unless it clearly degrades/increases performance for a given case, as most options may modify behaviour that result in different metrics accross different systems. If for example the option is an "accuracy" option, writing "High" is sufficient to imply "Slow". No need to write "High (Slow)".
|
||||
|
||||
Some examples:
|
||||
|
||||
- "[...] negatively affecting image quality", "[...] degrading image quality": Same wording but with less filler.
|
||||
- "[...] this may cause some glitches or crashes in some games", "[...] this may cause soft-crashes": Crashes implies there may be glitches (as crashes are technically a form of a fatal glitch). The entire sentence is structured as "may cause [...] on some games", which is redundant, because "may cause [...] in games" has the same semantic meaning ("may" is a chance that it will occur on "some" given set).
|
||||
- "FIFO Relaxed is similar to FIFO [...]", "FIFO Relaxed [...]": The name already implies similarity.
|
||||
|
|
@ -57,13 +63,16 @@ Some examples:
|
|||
- "[...] it can [...] in some cases", "[...] it can [...]": Implied probability.
|
||||
|
||||
Before adding a new setting, consider:
|
||||
|
||||
- Does the piece of code that the setting pertains to, make a significant difference if it's on/off?
|
||||
- Can it be auto-detected?
|
||||
|
||||
# IDE setup
|
||||
|
||||
## VSCode
|
||||
|
||||
Copy this to `.vscode/settings.json`, get CMake tools and it should be ready to build:
|
||||
|
||||
```json
|
||||
{
|
||||
"editor.tabSize": 4,
|
||||
|
|
@ -83,6 +92,7 @@ You may additionally need the `Qt Extension Pack` extension if building Qt.
|
|||
# Build speedup
|
||||
|
||||
If you have an HDD, use ramdisk (build in RAM), approximatedly you need 4GB for a full build with debug symbols:
|
||||
|
||||
```sh
|
||||
mkdir /tmp/ramdisk
|
||||
chmod 777 /tmp/ramdisk
|
||||
|
|
@ -96,128 +106,11 @@ umount /tmp/ramdisk
|
|||
# Assets and large files
|
||||
|
||||
A general rule of thumb, before uploading files:
|
||||
|
||||
- PNG files: Use [optipng](https://web.archive.org/web/20240325055059/https://optipng.sourceforge.net/).
|
||||
- SVG files: Use [svgo](https://github.com/svg/svgo).
|
||||
|
||||
May not be used but worth mentioning nonethless:
|
||||
|
||||
- OGG files: Use [OptiVorbis](https://github.com/OptiVorbis/OptiVorbis).
|
||||
- Video files: Use ffmpeg, preferably re-encode as AV1.
|
||||
|
||||
# Bisecting older commits
|
||||
|
||||
Since going into the past can be tricky (especially due to the dependencies from the project being lost thru time). This should "restore" the URLs for the respective submodules.
|
||||
|
||||
```sh
|
||||
#!/bin/sh -e
|
||||
cat > .gitmodules <<EOF
|
||||
[submodule "enet"]
|
||||
path = externals/enet
|
||||
url = https://github.com/lsalzman/enet.git
|
||||
[submodule "cubeb"]
|
||||
path = externals/cubeb
|
||||
url = https://github.com/mozilla/cubeb.git
|
||||
[submodule "dynarmic"]
|
||||
path = externals/dynarmic
|
||||
url = https://github.com/lioncash/dynarmic.git
|
||||
[submodule "libusb"]
|
||||
path = externals/libusb/libusb
|
||||
url = https://github.com/libusb/libusb.git
|
||||
[submodule "discord-rpc"]
|
||||
path = externals/discord-rpc
|
||||
url = https://github.com/yuzu-emu-mirror/discord-rpc.git
|
||||
[submodule "Vulkan-Headers"]
|
||||
path = externals/Vulkan-Headers
|
||||
url = https://github.com/KhronosGroup/Vulkan-Headers.git
|
||||
[submodule "sirit"]
|
||||
path = externals/sirit
|
||||
url = https://github.com/yuzu-emu-mirror/sirit.git
|
||||
[submodule "mbedtls"]
|
||||
path = externals/mbedtls
|
||||
url = https://github.com/yuzu-emu-mirror/mbedtls.git
|
||||
[submodule "xbyak"]
|
||||
path = externals/xbyak
|
||||
url = https://github.com/herumi/xbyak.git
|
||||
[submodule "opus"]
|
||||
path = externals/opus
|
||||
url = https://github.com/xiph/opus.git
|
||||
[submodule "SDL"]
|
||||
path = externals/SDL
|
||||
url = https://github.com/libsdl-org/SDL.git
|
||||
[submodule "cpp-httplib"]
|
||||
path = externals/cpp-httplib
|
||||
url = https://github.com/yhirose/cpp-httplib.git
|
||||
[submodule "ffmpeg"]
|
||||
path = externals/ffmpeg/ffmpeg
|
||||
url = https://github.com/FFmpeg/FFmpeg.git
|
||||
[submodule "vcpkg"]
|
||||
path = externals/vcpkg
|
||||
url = https://github.com/microsoft/vcpkg.git
|
||||
[submodule "cpp-jwt"]
|
||||
path = externals/cpp-jwt
|
||||
url = https://github.com/arun11299/cpp-jwt.git
|
||||
[submodule "libadrenotools"]
|
||||
path = externals/libadrenotools
|
||||
url = https://github.com/bylaws/libadrenotools.git
|
||||
[submodule "tzdb_to_nx"]
|
||||
path = externals/nx_tzdb/tzdb_to_nx
|
||||
url = https://github.com/lat9nq/tzdb_to_nx.git
|
||||
[submodule "VulkanMemoryAllocator"]
|
||||
path = externals/VulkanMemoryAllocator
|
||||
url = https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git
|
||||
[submodule "breakpad"]
|
||||
path = externals/breakpad
|
||||
url = https://github.com/yuzu-emu-mirror/breakpad.git
|
||||
[submodule "simpleini"]
|
||||
path = externals/simpleini
|
||||
url = https://github.com/brofield/simpleini.git
|
||||
[submodule "oaknut"]
|
||||
path = externals/oaknut
|
||||
url = https://github.com/merryhime/oaknut.git
|
||||
[submodule "Vulkan-Utility-Libraries"]
|
||||
path = externals/Vulkan-Utility-Libraries
|
||||
url = https://github.com/KhronosGroup/Vulkan-Utility-Libraries.git
|
||||
[submodule "oboe"]
|
||||
path = externals/oboe
|
||||
url = https://github.com/google/oboe.git
|
||||
[submodule "externals/boost-headers"]
|
||||
path = externals/boost-headers
|
||||
url = https://github.com/boostorg/headers.git
|
||||
EOF
|
||||
git submodule sync
|
||||
update_or_checkout () {
|
||||
if [ $0 = 'externals/sirit' ] \
|
||||
|| [ $0 = 'externals/dynarmic' ] \
|
||||
|| [ $0 = 'externals/breakpad' ] \
|
||||
|| [ $0 = 'externals/discord-rpc' ] \
|
||||
|| [ $0 = 'externals/mbedtls' ]; then
|
||||
[ -f $0/CMakeLists.txt ] || git submodule update --force --remote --init -- $0
|
||||
echo $0 ':remote' && git submodule update --remote $0
|
||||
exit
|
||||
elif [ $0 = 'externals/nx_tzdb/tzdb_to_nx' ]; then
|
||||
[ -f $0/CMakeLists.txt ] || git submodule update --force --remote --init -- $0
|
||||
echo $0 ':remote' && git submodule update --remote $0
|
||||
else
|
||||
echo $0 ':update' && git submodule update --init $0 && exit
|
||||
echo $0 ':remote' && git submodule update --remote $0 && exit
|
||||
echo $0 ':failure'
|
||||
fi
|
||||
}
|
||||
export -f update_or_checkout
|
||||
grep path .gitmodules | sed 's/.*= //' | xargs -n 1 -I {} bash -c 'update_or_checkout "$@"' {}
|
||||
# Fix for LLVM builds
|
||||
sed -i 's/src\/yuzu\/main.cpp/${CMAKE_SOURCE_DIR}\/src\/yuzu\/main.cpp/g' CMakeModules/FindLLVM.cmake
|
||||
# Only after cloning and everything - fixes issues with Zydis
|
||||
cat > externals/dynarmic/src/dynarmic/common/x64_disassemble.cpp <<EOF
|
||||
#include <cstddef>
|
||||
#include <vector>
|
||||
#include <string>
|
||||
namespace Dynarmic::Common {
|
||||
void DumpDisassembledX64(const void* ptr, size_t size) {}
|
||||
std::vector<std::string> DisassembleX64(const void* ptr, size_t size) { return {}; }
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
If having issues with older artifacts, then run `rm -r externals/dynarmic/build externals/dynarmic/externals externals/nx_tzdb/tzdb_to_nx/externals externals/sirit/externals`.
|
||||
|
||||
Configuring CMake with `-DSIRIT_USE_SYSTEM_SPIRV_HEADERS=1 -DCMAKE_CXX_FLAGS="-Wno-error" -DCMAKE_C_FLAGS="-Wno-error -Wno-array-parameter -Wno-stringop-overflow"` is also recommended.
|
||||
|
|
|
|||
Loading…
Reference in a new issue