From 271958cfb2e82d6d689f3f2c34f2417f9bc95454 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Mon, 15 Dec 2025 16:53:38 -0300 Subject: [PATCH] Improve Windows documentation clarity and add contributor --- CONTRIBUTORS | 1 + docs/windows.md | 146 +++++++++++++++++++++++++++--------- docs/windows_quick_start.md | 129 ------------------------------- 3 files changed, 110 insertions(+), 166 deletions(-) delete mode 100644 docs/windows_quick_start.md diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 2ec25da2d..eaac0bdff 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -255,6 +255,7 @@ Ranjit Odedra Eltaurus jariji Francisco Esteva +Daniela Silva Rocha ******************** diff --git a/docs/windows.md b/docs/windows.md index 12f4e7c39..cddefa46e 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -1,57 +1,129 @@ -# Windows +# Windows Quick Start Guide -## Requirements +> A simplified and beginner-friendly version of Anki’s official Windows documentation. +> Ideal for first-time contributors building Anki on Windows. -**Windows**: +--- -You must be running 64 bit Windows 10, version 1703 or newer. +## Minimum Requirements -**Rustup**: +- **64-bit Windows 10** (version 1703 or newer) +- Administrator access to install software -As mentioned in development.md, rustup must be installed. If you're on -ARM Windows and install the ARM64 version of rust-up, from this project folder, -run +--- -``` -rustup target add x86_64-pc-windows-msvc +## Step 1 – Install Rust (rustup) + +Anki uses the **Rust programming language** for parts of its codebase. + +1. Visit the official Rust website +2. Download and install **rustup** +3. During installation, accept the default options + +> **Windows ARM users** +> After installing rustup, run the following command in a terminal, inside the project folder: +> +> ```bash +> rustup target add x86_64-pc-windows-msvc +> ``` + +--- + +## Step 2 – Install Visual Studio + +1. Download **Visual Studio Community Edition** +2. Open the installer +3. Select: + - **Desktop Development with C++** +4. Leave the advanced options unchanged + +> **Note** +> This step is required to compile native parts of the project. + +--- + +## Step 3 – Install MSYS2 + +1. Visit the [MSYS2](https://www.msys2.org/) website +2. Install it in the default location +3. After installation, open the MSYS2 terminal +4. Run the following command: + +```bash +pacman -S git rsync ``` -**Visual Studio**: +--- -Install Visual Studio Community Edition from Microsoft. Once you've downloaded -the installer, open it, and select "Desktop Development with C++" on the left, -leaving the options shown on the right as is. +## Step 4 – Configure the PATH Environment Variable -**MSYS**: +1. Open **Windows Environment Variables** +2. Edit the **PATH** variable +3. Add the following path: -Install [msys2](https://www.msys2.org/) into the default folder location. - -After installation completes, run msys2, and run the following command: - -``` -$ pacman -S git rsync +```text +C:\msys64\usr\bin ``` -Edit your PATH environmental variable and add c:\msys64\usr\bin to it, and -reboot. +4. Reboot your computer -If you have native Windows apps relying on Git, e.g. the PowerShell extension -[posh-git](https://github.com/dahlbyk/posh-git), you may want to install -[Git for Windows](https://gitforwindows.org/) and put it on the path instead, -as msys Git may cause issues with them. You'll need to make sure rsync is -available some other way. +> **Important note** +> If you already use **Git for Windows** (for example, [posh-git](https://github.com/dahlbyk/posh-git) in PowerShell), it may conflict with the MSYS2 Git. +> +> - Prefer using [Git for Windows](https://gitforwindows.org/) +> - Ensure the `rsync` command is available -**Source folder**: +--- -Anki's source files do not need to be in a specific location, but it's best to -avoid long paths, as they can cause problems. Spaces in the path may cause -problems. +## Step 5 – Choose a Good Source Code Location -## Audio +To avoid build issues: -To play and record audio during development, mpv.exe and lame.exe must be on the path. +- Avoid long directory paths +- Avoid spaces in folder names -## More + **Recommended**: +```text +C:\anki +``` + + **Problematic**: +```text +C:\Users\Your Name\Documents\Projects\Anki Source Code +``` + +--- + +## Audio Support (Optional) + +To play and record audio during development, ensure the following executables are available in your **PATH**: + +- `mpv.exe` +- `lame.exe` + +--- + +## Common Problems + +### Build errors +- Make sure Visual Studio was installed with **Desktop Development with C++** + +### `git` command not found +- Verify that the PATH variable is configured correctly + +### Issues caused by spaces in paths +- Move the project to a shorter path, such as `C:\anki` + +--- + +## Next Steps + +For advanced topics such as running tests or building wheels, see: + +- `development.md` + +--- + +> **Note** +> This guide does not replace the official documentation. It is intended to make the first steps easier for new Anki contributors on Windows. -For info on running tests, building wheels and so on, please see -[Development](./development.md). diff --git a/docs/windows_quick_start.md b/docs/windows_quick_start.md deleted file mode 100644 index cddefa46e..000000000 --- a/docs/windows_quick_start.md +++ /dev/null @@ -1,129 +0,0 @@ -# Windows Quick Start Guide - -> A simplified and beginner-friendly version of Anki’s official Windows documentation. -> Ideal for first-time contributors building Anki on Windows. - ---- - -## Minimum Requirements - -- **64-bit Windows 10** (version 1703 or newer) -- Administrator access to install software - ---- - -## Step 1 – Install Rust (rustup) - -Anki uses the **Rust programming language** for parts of its codebase. - -1. Visit the official Rust website -2. Download and install **rustup** -3. During installation, accept the default options - -> **Windows ARM users** -> After installing rustup, run the following command in a terminal, inside the project folder: -> -> ```bash -> rustup target add x86_64-pc-windows-msvc -> ``` - ---- - -## Step 2 – Install Visual Studio - -1. Download **Visual Studio Community Edition** -2. Open the installer -3. Select: - - **Desktop Development with C++** -4. Leave the advanced options unchanged - -> **Note** -> This step is required to compile native parts of the project. - ---- - -## Step 3 – Install MSYS2 - -1. Visit the [MSYS2](https://www.msys2.org/) website -2. Install it in the default location -3. After installation, open the MSYS2 terminal -4. Run the following command: - -```bash -pacman -S git rsync -``` - ---- - -## Step 4 – Configure the PATH Environment Variable - -1. Open **Windows Environment Variables** -2. Edit the **PATH** variable -3. Add the following path: - -```text -C:\msys64\usr\bin -``` - -4. Reboot your computer - -> **Important note** -> If you already use **Git for Windows** (for example, [posh-git](https://github.com/dahlbyk/posh-git) in PowerShell), it may conflict with the MSYS2 Git. -> -> - Prefer using [Git for Windows](https://gitforwindows.org/) -> - Ensure the `rsync` command is available - ---- - -## Step 5 – Choose a Good Source Code Location - -To avoid build issues: - -- Avoid long directory paths -- Avoid spaces in folder names - - **Recommended**: -```text -C:\anki -``` - - **Problematic**: -```text -C:\Users\Your Name\Documents\Projects\Anki Source Code -``` - ---- - -## Audio Support (Optional) - -To play and record audio during development, ensure the following executables are available in your **PATH**: - -- `mpv.exe` -- `lame.exe` - ---- - -## Common Problems - -### Build errors -- Make sure Visual Studio was installed with **Desktop Development with C++** - -### `git` command not found -- Verify that the PATH variable is configured correctly - -### Issues caused by spaces in paths -- Move the project to a shorter path, such as `C:\anki` - ---- - -## Next Steps - -For advanced topics such as running tests or building wheels, see: - -- `development.md` - ---- - -> **Note** -> This guide does not replace the official documentation. It is intended to make the first steps easier for new Anki contributors on Windows. -