From 586183f32771748e8b8c5499d5a864797bae2ae7 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Mon, 15 Dec 2025 01:38:31 -0300 Subject: [PATCH 01/10] Add Windows quick start guide for new contributors --- docs/windows_quick_start.md | 129 ++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/windows_quick_start.md diff --git a/docs/windows_quick_start.md b/docs/windows_quick_start.md new file mode 100644 index 000000000..cddefa46e --- /dev/null +++ b/docs/windows_quick_start.md @@ -0,0 +1,129 @@ +# 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. + 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 02/10] 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. - From 210fb084cc265319eb85c5a5218723731bafdc15 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Tue, 16 Dec 2025 00:48:22 -0300 Subject: [PATCH 03/10] Format markdown files with dprint --- docs/windows.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/windows.md b/docs/windows.md index cddefa46e..19c56c270 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -20,7 +20,7 @@ Anki uses the **Rust programming language** for parts of its codebase. 2. Download and install **rustup** 3. During installation, accept the default options -> **Windows ARM users** +> **Windows ARM users**\ > After installing rustup, run the following command in a terminal, inside the project folder: > > ```bash @@ -34,11 +34,11 @@ Anki uses the **Rust programming language** for parts of its codebase. 1. Download **Visual Studio Community Edition** 2. Open the installer 3. Select: - - **Desktop Development with C++** + - **Desktop Development with C++** 4. Leave the advanced options unchanged -> **Note** -> This step is required to compile native parts of the project. +> **Note**\ +> This step is required to compile native parts of the project. --- @@ -67,7 +67,7 @@ C:\msys64\usr\bin 4. Reboot your computer -> **Important note** +> **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/) @@ -79,15 +79,17 @@ C:\msys64\usr\bin To avoid build issues: -- Avoid long directory paths -- Avoid spaces in folder names +- Avoid long directory paths +- Avoid spaces in folder names + +**Recommended**: - **Recommended**: ```text C:\anki ``` - **Problematic**: +**Problematic**: + ```text C:\Users\Your Name\Documents\Projects\Anki Source Code ``` @@ -105,13 +107,16 @@ To play and record audio during development, ensure the following executables ar ## Common Problems -### Build errors +### Build errors + - Make sure Visual Studio was installed with **Desktop Development with C++** -### `git` command not found +### `git` command not found + - Verify that the PATH variable is configured correctly -### Issues caused by spaces in paths +### Issues caused by spaces in paths + - Move the project to a shorter path, such as `C:\anki` --- @@ -124,6 +129,5 @@ For advanced topics such as running tests or building wheels, see: --- -> **Note** +> **Note**\ > This guide does not replace the official documentation. It is intended to make the first steps easier for new Anki contributors on Windows. - From b6a64eaf8dadc2816740e7513facbe305dee25a9 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 17 Dec 2025 19:06:28 -0300 Subject: [PATCH 04/10] Update docs/windows.md Co-authored-by: user1823 <92206575+user1823@users.noreply.github.com> --- docs/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/windows.md b/docs/windows.md index 19c56c270..367dca70a 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -68,7 +68,7 @@ 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. +> If you already have native Windows apps relying on Git (for example, [posh-git](https://github.com/dahlbyk/posh-git) in PowerShell), they may conflict with the MSYS2 Git. > > - Prefer using [Git for Windows](https://gitforwindows.org/) > - Ensure the `rsync` command is available From e5602d79f45158158163e3ebc1c4c7cca95bb272 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 17 Dec 2025 19:06:54 -0300 Subject: [PATCH 05/10] Update docs/windows.md Co-authored-by: user1823 <92206575+user1823@users.noreply.github.com> --- docs/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/windows.md b/docs/windows.md index 367dca70a..062188e23 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -70,7 +70,7 @@ C:\msys64\usr\bin > **Important note**\ > If you already have native Windows apps relying on Git (for example, [posh-git](https://github.com/dahlbyk/posh-git) in PowerShell), they may conflict with the MSYS2 Git. > -> - Prefer using [Git for Windows](https://gitforwindows.org/) +> - In that case, prefer using [Git for Windows](https://gitforwindows.org/) over msys2. > - Ensure the `rsync` command is available --- From e879373856d9235df97014448853040fc7a0a907 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 17 Dec 2025 19:07:19 -0300 Subject: [PATCH 06/10] Update docs/windows.md Co-authored-by: user1823 <92206575+user1823@users.noreply.github.com> --- docs/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/windows.md b/docs/windows.md index 062188e23..8bb1a079e 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -71,7 +71,7 @@ C:\msys64\usr\bin > If you already have native Windows apps relying on Git (for example, [posh-git](https://github.com/dahlbyk/posh-git) in PowerShell), they may conflict with the MSYS2 Git. > > - In that case, prefer using [Git for Windows](https://gitforwindows.org/) over msys2. -> - Ensure the `rsync` command is available +> - Ensure that `rsync` is available some other way --- From ee3b17ae3c1c548becfc05aff047569af6adf1cb Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 17 Dec 2025 19:21:09 -0300 Subject: [PATCH 07/10] Apply review suggestions to Windows documentation --- docs/windows.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/windows.md b/docs/windows.md index 8bb1a079e..42ba9d084 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -55,7 +55,7 @@ pacman -S git rsync --- -## Step 4 – Configure the PATH Environment Variable +### Configure the PATH Environment Variable 1. Open **Windows Environment Variables** 2. Edit the **PATH** variable @@ -75,7 +75,7 @@ C:\msys64\usr\bin --- -## Step 5 – Choose a Good Source Code Location +## Step 4 – Choose a Good Source Code Location To avoid build issues: @@ -129,5 +129,3 @@ For advanced topics such as running tests or building wheels, see: --- -> **Note**\ -> This guide does not replace the official documentation. It is intended to make the first steps easier for new Anki contributors on Windows. From cf9e2442173015d8546036cce1145ff71e07b379 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 17 Dec 2025 19:27:27 -0300 Subject: [PATCH 08/10] Format docs/windows.md with dprint --- docs/windows.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/windows.md b/docs/windows.md index 42ba9d084..84353b82e 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -128,4 +128,3 @@ For advanced topics such as running tests or building wheels, see: - `development.md` --- - From a5698f8ead4b33becdf5eae968485df2b0f58373 Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 31 Dec 2025 18:43:43 -0300 Subject: [PATCH 09/10] docs(windows): clarify why Visual Studio is required --- docs/windows.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/windows.md b/docs/windows.md index 84353b82e..d9d81c390 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -37,8 +37,11 @@ Anki uses the **Rust programming language** for parts of its codebase. - **Desktop Development with C++** 4. Leave the advanced options unchanged -> **Note**\ +> **Note** > This step is required to compile native parts of the project. +> On Windows, compiling native code requires Microsoft's MSVC toolchain and the Windows SDK +> (system headers and libraries), which are typically installed via Visual Studio or +> Visual Studio Build Tools. --- From 64c4628d7e2c08a332e897b3fb7b65986e4e05af Mon Sep 17 00:00:00 2001 From: Daniela Silva <152733853+DaniSilvaCodes@users.noreply.github.com> Date: Wed, 31 Dec 2025 19:20:49 -0300 Subject: [PATCH 10/10] docs: adjustment in the windows.md file --- docs/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/windows.md b/docs/windows.md index d9d81c390..8dad5fe6c 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -37,7 +37,7 @@ Anki uses the **Rust programming language** for parts of its codebase. - **Desktop Development with C++** 4. Leave the advanced options unchanged -> **Note** +> **Note**: > This step is required to compile native parts of the project. > On Windows, compiling native code requires Microsoft's MSVC toolchain and the Windows SDK > (system headers and libraries), which are typically installed via Visual Studio or