[docs] reorg a bit, add AI policy, rewrite release policy (#3423)

mdlint, AI policy, and an actual release policy that doesn't suck.

Signed-off-by: crueter <crueter@eden-emu.dev>
Reviewed-on: https://git.eden-emu.dev/eden-emu/eden/pulls/3423
Reviewed-by: Lizzie <lizzie@eden-emu.dev>
Reviewed-by: DraVee <dravee@eden-emu.dev>
This commit is contained in:
crueter
2026-01-30 11:35:39 +01:00
parent 979ea5563b
commit a692986bd7
9 changed files with 157 additions and 180 deletions

View File

@@ -6,9 +6,11 @@
This is a full-fledged guide to build Eden on all supported platforms.
## Dependencies
First, you must [install some dependencies](Deps.md).
## Clone
Next, you will want to clone Eden via the terminal:
```sh
@@ -53,30 +55,35 @@ Hit "Configure Project", then wait for CMake to finish configuring (may take a w
> [!WARNING]
>For all systems:
>
>- *CMake* **MUST** be in your PATH (and also *ninja*, if you are using it as `<GENERATOR>`)
>- You *MUST* be in the cloned *Eden* directory
>
>On Windows:
>
> - It's recommended to install **[Ninja](https://ninja-build.org/)**
> - You must load **Visual C++ development environment**, this can be done by running our convenience script:
> - `tools/windows/load-msvc-env.ps1` (for PowerShell 5+)
> - `tools/windows/load-msvc-env.sh` (for MSYS2, Git Bash, etc)
Available `<GENERATOR>`:
- MSYS2: `MSYS Makefiles`
- MSVC: `Ninja` (preferred) or `Visual Studio 17 2022`
- macOS: `Ninja` (preferred) or `Xcode`
- Others: `Ninja` (preferred) or `UNIX Makefiles`
Available `<BUILD_TYPE>`:
- `Release` (default)
- `RelWithDebInfo` (debug symbols--compiled executable will be large)
- `Debug` (if you are using a debugger and annoyed with stuff getting optimized out)
Caveat for Debug Builds:
- If you're building with CCache, you will need to add the environment variable `CL` with the `/FS` flag ([Reference](https://learn.microsoft.com/pt-br/cpp/build/reference/fs-force-synchronous-pdb-writes?view=msvc-170))
Also see the [Options](Options.md) page for additional CMake options.
Also see the root CMakeLists.txt for more build options. Usually the default will provide the best experience, however.
```sh
cmake -S . -B build -G "<GENERATOR>" -DCMAKE_BUILD_TYPE=<BUILD_TYPE> -DYUZU_TESTS=OFF
@@ -95,7 +102,7 @@ cmake -S . -B build -G "<GENERATOR>" -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COM
<details>
<summary>Click to Open</summary>
* Clone the Repository:
- Clone the Repository:
<img src="https://user-images.githubusercontent.com/42481638/216899046-0d41d7d6-8e4d-4ed2-9587-b57088af5214.png" width="500">
<img src="https://user-images.githubusercontent.com/42481638/216899061-b2ea274a-e88c-40ae-bf0b-4450b46e9fea.png" width="500">
@@ -105,26 +112,26 @@ cmake -S . -B build -G "<GENERATOR>" -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COM
### Building & Setup
* Once Cloned, You will be taken to a prompt like the image below:
- Once Cloned, You will be taken to a prompt like the image below:
<img src="https://user-images.githubusercontent.com/42481638/216899092-3fe4cec6-a540-44e3-9e1e-3de9c2fffc2f.png" width="500">
* Set the settings to the image below:
* Change `Build type: Release`
* Change `Name: Release`
* Change `Toolchain Visual Studio`
* Change `Generator: Let CMake decide`
* Change `Build directory: build`
- Set the settings to the image below:
- Change `Build type: Release`
- Change `Name: Release`
- Change `Toolchain Visual Studio`
- Change `Generator: Let CMake decide`
- Change `Build directory: build`
<img src="https://user-images.githubusercontent.com/42481638/216899164-6cee8482-3d59-428f-b1bc-e6dc793c9b20.png" width="500">
* Click OK; now Clion will build a directory and index your code to allow for IntelliSense. Please be patient.
* Once this process has been completed (No loading bar bottom right), you can now build eden
* In the top right, click on the drop-down menu, select all configurations, then select eden
- Click OK; now Clion will build a directory and index your code to allow for IntelliSense. Please be patient.
- Once this process has been completed (No loading bar bottom right), you can now build eden
- In the top right, click on the drop-down menu, select all configurations, then select eden
<img src="https://user-images.githubusercontent.com/42481638/216899226-975048e9-bc6d-4ec1-bc2d-bd8a1e15ed04.png" height="500" >
* Now run by clicking the play button or pressing Shift+F10, and eden will auto-launch once built.
- Now run by clicking the play button or pressing Shift+F10, and eden will auto-launch once built.
<img src="https://user-images.githubusercontent.com/42481638/216899275-d514ec6a-e563-470e-81e2-3e04f0429b68.png" width="500">
</details>
@@ -132,6 +139,7 @@ cmake -S . -B build -G "<GENERATOR>" -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COM
## Troubleshooting
If your initial configure failed:
- *Carefully* re-read the [dependencies guide](Deps.md)
- Clear the CPM cache (`.cache/cpm`) and CMake cache (`<build directory>/CMakeCache.txt`)
- Evaluate the error and find any related settings
@@ -153,20 +161,16 @@ Simply hit Ctrl+B, or the "hammer" icon in the bottom left. To run, hit the "pla
If you are using the `UNIX Makefiles` or `Visual Studio 17 2022` as `<GENERATOR>`, you should also add `--parallel` for faster build times.
```
```sh
cmake --build build
```
Your compiled executable will be in:
- `build/bin/eden.exe` for Windows,
- `build/bin/eden.app/Contents/MacOS/eden` for macOS,
- and `build/bin/eden` for others.
## Scripts
Some platforms have convenience scripts provided for building.
- **[Linux](scripts/Linux.md)**
- **[Windows](scripts/Windows.md)**
macOS scripts will come soon.
Take a look at our [CI scripts](https://github.com/Eden-CI/Workflow). You can use `.ci/common/configure.sh` on any POSIX-compliant shell, but you are heavily encouraged to instead write your own based. It's not really that hard, provided you can read CMake.

View File

@@ -1,68 +0,0 @@
# CMake Options
To change these options, add `-DOPTION_NAME=NEWVALUE` to the command line.
- On Qt Creator, go to Project -> Current Configuration
Notes:
- Defaults are marked per-platform.
- "Non-UNIX" just means Windows/MSVC and Android (yes, macOS is UNIX
- Android generally doesn't need to change anything; if you do, go to `src/android/app/build.gradle.kts`
- To set a boolean variable to on, use `ON` for the value; to turn it off, use `OFF`
- If a variable is mentioned as being e.g. "ON" for a specific platform(s), that means it is defaulted to OFF on others
- TYPE is always boolean unless otherwise specified
- Format:
* `OPTION_NAME` (TYPE DEFAULT) DESCRIPTION
## Options
- `YUZU_USE_CPM` (ON for non-UNIX) Use CPM to fetch system dependencies (fmt, boost, etc) if needed. Externals will still be fetched. See the [CPM](CPM.md) and [Deps](Deps.md) docs for more info.
- `ENABLE_WEB_SERVICE` (ON) Enable multiplayer service
- `ENABLE_WIFI_SCAN` (OFF) Enable WiFi scanning (requires iw on Linux) - experimental
- `YUZU_USE_BUNDLED_FFMPEG` (ON for non-UNIX) Download (Windows, Android) or build (UNIX) bundled FFmpeg
- `ENABLE_CUBEB` (ON) Enables the cubeb audio backend
- `YUZU_TESTS` (ON) Compile tests - requires Catch2
- `YUZU_DOWNLOAD_ANDROID_VVL` (ON) Download validation layer binary for Android
- `YUZU_ENABLE_LTO` (OFF) Enable link-time optimization
* Not recommended on Windows
* UNIX may be better off appending `-flto=thin` to compiler args
- `YUZU_DOWNLOAD_TIME_ZONE_DATA` (ON) Always download time zone binaries
* Currently, build fails without this
- `YUZU_USE_FASTER_LD` (ON) Check if a faster linker is available
* Only available on UNIX
- `YUZU_USE_BUNDLED_MOLTENVK` (ON, macOS only) Download bundled MoltenVK lib)
- `YUZU_TZDB_PATH` (string) Path to a pre-downloaded timezone database (useful for nixOS)
- `ENABLE_OPENSSL` (ON for Linux and *BSD) Enable OpenSSL backend for the ssl service
* Always enabled if the web service is enabled
- `YUZU_USE_BUNDLED_OPENSSL` (ON for MSVC) Download bundled OpenSSL build
* Always on for Android
* Unavailable on OpenBSD
- `ENABLE_UPDATE_CHECKER` (OFF) Enable update checker for the Qt an Android frontends
The following options are desktop only:
- `ENABLE_SDL2` (ON) Enable the SDL2 desktop, audio, and input frontend (HIGHLY RECOMMENDED!)
* Unavailable on Android
- `YUZU_USE_EXTERNAL_SDL2` (ON for non-UNIX) Compiles SDL2 from source
- `YUZU_USE_BUNDLED_SDL2` (ON for MSVC) Download a prebuilt SDL2
* Unavailable on OpenBSD
* Only enabled if YUZU_USE_CPM and ENABLE_SDL2 are both ON
- `ENABLE_LIBUSB` (ON) Enable the use of the libusb input frontend (HIGHLY RECOMMENDED)
- `ENABLE_OPENGL` (ON) Enable the OpenGL graphics frontend
* Unavailable on Windows/ARM64 and Android
- `ENABLE_QT` (ON) Enable the Qt frontend (recommended)
- `ENABLE_QT_TRANSLATION` (OFF) Enable translations for the Qt frontend
- `YUZU_USE_BUNDLED_QT` (ON for MSVC) Download bundled Qt binaries
* Note that using **system Qt** requires you to include the Qt CMake directory in `CMAKE_PREFIX_PATH`, e.g:
* `-DCMAKE_PREFIX_PATH=C:/Qt/6.9.0/msvc2022_64/lib/cmake/Qt6`
- `YUZU_QT_MIRROR` (string) What mirror to use for downloading the bundled Qt libraries
- `YUZU_USE_QT_MULTIMEDIA` (OFF) Use QtMultimedia for camera support
- `YUZU_USE_QT_WEB_ENGINE` (OFF) Use QtWebEngine for web applet implementation (requires the huge QtWebEngine dependency; not recommended)
- `USE_DISCORD_PRESENCE` (OFF) Enables Discord Rich Presence (Qt frontend only)
- `YUZU_ROOM` (ON) Enable dedicated room functionality
- `YUZU_ROOM_STANDALONE` (ON) Enable standalone room executable (eden-room)
* Requires `YUZU_ROOM`
- `YUZU_CMD` (ON) Compile the SDL2 frontend (eden-cli) - requires SDL2
- `YUZU_CRASH_DUMPS` Compile crash dump (Minidump) support"
* Currently only available on Windows and Linux
See `src/dynarmic/CMakeLists.txt` for additional options--usually, these don't need changed

View File

@@ -5,14 +5,20 @@ This contains documentation created by developers. This contains build instructi
- **[General Build Instructions](Build.md)**
- **[Cross Compiling](CrossCompile.md)**
- **[Development Guidelines](Development.md)**
- **[Coding guidelines](Coding.md)**
- **[Dependencies](Deps.md)**
- **[Debug Guidelines](./Debug.md)**
- **[CPM - CMake Package Manager](CPMUtil.md)**
- **[CPM - CMake Package Manager](./CPMUtil)**
- **[Platform-Specific Caveats](Caveats.md)**
- **[The NVIDIA SM86 (Maxwell) GPU](./NvidiaGpu.md)**
- **[User Handbook](./user)**
- **[Release Policy](./ReleasePolicy.md)**
- **[Dynarmic](./dynarmic)**
- **[Cross compilation](./CrossCompile.md)**
- **[Driver Bugs](./DriverBugs.md)**
## Policies
Policies and information on development.
- **[AI and LLM Usage](./policies/AI.md)**
- **[Release Policy](./policies/Release.md)**
- **[Coding guidelines](./policies/Coding.md)**

View File

@@ -1,25 +0,0 @@
# Release Policy
While releases are usually made at the discretion of the team, we feel that establishing a clearer guideline on how those come to be will help expectations when it comes to features and fixes per version.
## Release candidates
Every full release is *preceded* by at least, 3 release candidates. The reasoning is that each week of the month, there will be a release candidate, with the "4th one" being the final full release.
The main expectation is that the release candidates bring both fixes and, sometimes, new features. But not guarantee a regression-free experience.
The criteria for choosing a date for a release candidate is at discretion, or "perceived necesity" at any given time.
## Full release
A full release means there are *no major* leftover regressions, importantly this means that a grand portion of regressions found between release candidates are swept out before declaring a full release. This doesn't mean a full release is regression-free; but we do a best-effort approach to reduce them for end-users.
The main expectation is that users can safely upgrade from a stable build to another, with no major regressions.
## Snapshot/rolling release
While we don't publish rolling releases, we are aware users may compile from source and/or provide binaries to master builds of the project.
This is mostly fine since we keep master very stable from major hiccups. However sometimes bugs do slip between tests or reviews - so users are advised to keep that in mind.
We advise that users also read git logs (`git log --oneline`) before recompiling to get a clearer picture of the changes given into the emulator.

107
docs/policies/AI.md Normal file
View File

@@ -0,0 +1,107 @@
# AI Policy
Use at your peril.
AI is a *tool*, not a replacement or catch-all solution. It is generally okay at a few *very specific* use cases:
- Automation of tedious changes where you have already made the pattern clear and done the necessary groundwork.
- Conversion of code from one paradigm to another.
For everything else, AI is subpar at best, and actively harmful at worst. In general, you are **heavily** encouraged to not use AI at all.
## Why?
AI is notorious for hallucinating facts out of thin air and sometimes outright lying to users. Additionally, code written by LLMs is often needlessly verbose and horrifically inefficient (not to mention the rather ridiculous level of over-commenting). The end result is often one of three things:
- Completely nonfunctional code
- Code that works, but is extraordinarily verbose or not nearly as efficient as it can be
- Code that works well and is written well, but solves a different problem than was intended, or solves the same problem but in a completely incorrect way that will break other things horribly.
Human-written code will, without exception, always be of infinitely higher quality when properly researched and implemented by someone both familiar with the surrounding code and the programming language in use. LLMs may produce a "good enough" result, but this result is often subpar. Keep in mind: all code is held under a standard of excellence. If your code sucks, it will be rejected. AI-generated code just so happens to be a particularly sucky genre of code, and will thus be held to this same standard.
On a lesser-known note, LLM outputs often contain unicode symbols such as emojis or the arrow symbol. Please don't put Unicode symbols in your code. It messes with many an IDE, and the three people viewing your code on Lynx will be very unhappy.
**Learn to code**. It's worth it, we promise!
## Acceptable Use
- As stated previously, AI is good in a few *very specific* cases. In these cases, it's usually fine to use AI, as long as you **explicitly provide notice that it was used**.
- Anything directly outside of the realm of the code written in your PR or patch is none of our business.
- This primarily covers research.
- However, we *still* strongly discourage this for the reasons mentioned above.
- Assistance with cleanups, and minor nitpicks/optimizations.
- This is still discouraged, but it's okay to occasionally use LLMs to catch any minor mistakes you made in your code.
- Debugging
- In general, LLMs are not good at debugging, but if you solve a bug you're facing with help from an AI, and said fix **works properly**, then that's fine.
## Unacceptable Use
Well, everything else. But here are a few examples:
- Commit messages
- LLMs are absolutely horrible at this. They are needlessly verbose, almost never catch the actual intent of the commit, and will almost always hallucinate false information about said changes.
- See the addendum for an example
- Solving problems
- Slapping a few files and a "please fix bug XYZ" into an LLM is a recipe for disaster that will pretty much never work.
- Fully AI-generated code
- This shouldn't need explaining. Do not do this under any circumstance, especially if you don't actually understand what's going on.
- Writing code based on pseudo-instructions
- If you don't know how to write code, don't. If you've figured out the root cause (preferably without feeding random files into an LLM) and actively know what's going on, provide information to other developers or friends of yours who have knowledge of the language and/or the codebase.
## Addendum: Commit Messages
The patchset for pull request [#3422](https://git.eden-emu.dev/eden-emu/eden/pulls/3422) was fed into several LLMs to generate a commit message. All of them sucked, and not a single one caught on to what the commit actually did. For example:
```txt
profile_manager: Refactor user deletion to use index instead of UUID
This commit improves the user profile deletion flow in the following ways:
1. **UI layer (ConfigureProfileManager)**:
- Replaces UUID-based deletion with index-based deletion
- Passes the selected row index from the tree view to the confirmation dialog
- Emits deleteUser(int index) signal from ConfigureProfileManagerDeleteDialog
- Removes lambda capture and std::function callback in favor of direct signal/slot connection
2. **Delete dialog**:
- Changes SetInfo() signature to accept index instead of accept callback
- Stores index internally and emits it via deleteUser signal on acceptance
3. **Core ProfileManager**:
- Refactors RemoveUser(UUID) → RemoveProfileAtIndex(index)
- Removes duplicated stable_partition + save logic from RemoveUser()
- Centralizes profile removal and save-file writing in RemoveProfileAtIndex()
4. **Minor follow-up**:
- Adds profile_manager.ResetUserSaveFile() call in PopulateUserList() to ensure consistent state when refreshing the user list
These changes eliminate redundant code, reduce the risk of UUID → index mismatch bugs, and make the deletion path more straightforward and maintainable.
Fixes: potential inconsistency when user order changes between UI and backend
```
This is:
- Needlessly verbose (nobody cares about most of these details)
- Doesn't address the actual purpose of the PR (fixing a double-deletion bug in the profile manager)
- Has unicode arrows
- Uses overly corporate and, well, robotic language
As another example:
```txt
profile(manager/ui): switch to index-based deletion and unify removal logic
- Make ConfigureProfileManagerDeleteDialog emit a deleteUser(int) signal instead of taking a callback. Store the target index in the dialog (m_index) and emit it on acceptance.
- Change ConfigureProfileManager to pass an index to SetInfo and to accept an index in DeleteUser. Wire the dialog signal to the new DeleteUser slot.
- Update headers: add the signal and m_index, add TODO to move dialog to a .ui file, and update slot/signature declarations.
- Add ProfileManager::RemoveProfileAtIndex(std::size_t) and refactor RemoveUser(UUID) to call RemoveProfileAtIndex to avoid duplicated removal logic. Ensure the removal path marks saves as needed and writes the user save file.
- Ensure the profile list updates immediately after deletes by calling profile_manager.ResetUserSaveFile() when populating the user list (qlaunch fix).
- Misc: update SPDX copyright year and fix build breakages caused by the API changes.
This consolidates profile removal behavior, fixes potential race conditions in the profile dialog, and removes duplicated removal code.
```
This has all of the same problems as the other one. Needlessly verbose, doesn't address *what* it actually fixes ("consolidates profile removal behavior"... okay, why? What does it fix?), etc. It even has the bonus of totally hallucinating the addition of a method!
**Don't use AI for commit messages**.

View File

@@ -11,6 +11,7 @@ Simply put, types/classes are named as `PascalCase`, same for methods and functi
Except for Qt MOC where `functionName` is preferred.
Template typenames prefer short names like `T`, `I`, `U`, if a longer name is required either `Iterator` or `perform_action` are fine as well. Do not use names like `SS` as systems like solaris define it for registers, in general do not use any of the following for short names:
- `SS`, `DS`, `GS`, `FS`: Segment registers, defined by Solaris `<ucontext.h>`
- `EAX`, `EBX`, `ECX`, `EDX`, `ESI`, `EDI`, `ESP`, `EBP`, `EIP`: Registers, defined by Solaris.
- `X`: Defined by some utility headers, avoid.
@@ -27,6 +28,7 @@ Try not using hungarian notation, if you're able.
Formatting is extremelly lax, the general rule of thumb is: Don't add new lines just to increase line count. The less lines we have to look at, the better. This means also packing densely your code while not making it a clusterfuck. Strike a balance of "this is a short and comprehensible piece of code" and "my eyes are actually happy to see this!". Don't just drop the entire thing in a single line and call it "dense code", that's just spaghetti posing as code. In general, be mindful of what other devs need to look at.
Do not put if/while/etc braces after lines:
```c++
// no dont do this
// this is more lines of code for no good reason (why braces need their separate lines?)
@@ -105,6 +107,7 @@ device = SDL_OpenAudioDevice(device_name.empty() ? nullptr : device_name.c_str()
```
A note about operators: Use them sparingly, yes, the language is lax on them, but some usages can be... tripping to say the least.
```c++
a, b, c; //<-- NOT OK multiple statments with comma operator is definitely a recipe for disaster
return c ? a : b; //<-- OK ternaries at end of return statments are clear and fine

10
docs/policies/Release.md Normal file
View File

@@ -0,0 +1,10 @@
# Release Policy
Release when lots of new changes and fixes. Hotfix if more bugs. Release candidate if lot of things to test. Simple as.
## Checklist
- [ ] Update Transifex
- [ ] Test for regressions and bugs
- [ ] Write a changelog
- [ ] Ensure all platforms work

View File

@@ -1,31 +0,0 @@
# Linux Build Scripts
* Provided script: `.ci/linux/build.sh`
* Must specify arch target, e.g.: `.ci/linux/build.sh amd64`
* Valid targets:
* `native`: Optimize to your native host architecture
* `legacy`: x86\_64 generic, only needed for CPUs older than 2013 or so
* `amd64`: x86\_64-v3, for CPUs newer than 2013 or so
* `steamdeck` / `zen2`: For Steam Deck or Zen >= 2 AMD CPUs (untested on Intel)
* `rog-ally` / `allyx` / `zen4`: For ROG Ally X or Zen >= 4 AMD CPUs (untested on Intel)
* `aarch64`: For armv8-a CPUs, older than mid-2021 or so
* `armv9`: For armv9-a CPUs, newer than mid-2021 or so
* Extra CMake flags go after the arch target.
### Environment Variables
* `NPROC`: Number of compilation threads (default: all cores)
* `TARGET`: Set `appimage` to disable standalone `eden-cli` and `eden-room`
* `BUILD_TYPE`: Build type (default: `Release`)
Boolean flags (set `true` to enable, `false` to disable):
* `DEVEL` (default `FALSE`): Disable Qt update checker
* `USE_WEBENGINE` (default `FALSE`): Enable Qt WebEngine
* `USE_MULTIMEDIA` (default `FALSE`): Enable Qt Multimedia
* AppImage packaging script: `.ci/linux/package.sh`
* Accepts same arch targets as build script
* Use `DEVEL=true` to rename app to `Eden Nightly` and disable the update checker
* This should generally not be used unless in a tailor-made packaging environment (e.g. Actions/CI)

View File

@@ -1,29 +0,0 @@
# Windows Build Scripts
* A convenience script for building is provided in `.ci/windows/build.sh`.
* You must run this with Bash, e.g. Git Bash or the MinGW TTY.
* To use this script, you must have `windeployqt` installed (usually bundled with Qt) and set the `WINDEPLOYQT` environment variable to its canonical Bash location:
* `WINDEPLOYQT="/c/Qt/6.9.1/msvc2022_64/bin/windeployqt6.exe" .ci/windows/build.sh`.
* You can use `aqtinstall`, more info on <https://github.com/miurahr/aqtinstall> and <https://ddalcino.github.io/aqt-list-server/>
* Extra CMake flags should be placed in the arguments of the script.
#### Additional environment variables can be used to control building:
* `BUILD_TYPE` (default `Release`): Sets the build type to use.
* The following environment variables are boolean flags. Set to `true` to enable or `false` to disable:
* `DEVEL` (default FALSE): Disable Qt update checker
* `USE_WEBENGINE` (default FALSE): Enable Qt WebEngine
* `USE_MULTIMEDIA` (default FALSE): Enable Qt Multimedia
* `BUNDLE_QT` (default FALSE): Use bundled Qt
* Note that using **system Qt** requires you to include the Qt CMake directory in `CMAKE_PREFIX_PATH`
* `.ci/windows/build.sh -DCMAKE_PREFIX_PATH=C:/Qt/6.9.0/msvc2022_64/lib/cmake/Qt6`
* After building, a zip can be packaged via `.ci/windows/package.sh`. You must have 7-zip installed and in your PATH.
* The resulting zip will be placed into `artifacts` in the source directory.