Merge pull request #645 from pekempy/macos-install-guide

Add MacOS Install guide to the Wiki

wiki/pages/Getting Started.md

@@ -7,43 +7,50 @@
 <img src="../images/os_windows.png" alt="Windows" style="max-width: 80px"> <img src="../images/os_apple.png" alt="MacOS" style="max-width: 80px"> <img src="../images/os_ubuntu.png" alt="Ubuntu" style="max-width: 80px"> <img src="../images/os_debian.png" alt="Debian" style="max-width: 80px"> <img src="../images/os_pop.png" alt="PopOS" style="max-width: 80px"> <img src="../images/os_arch.png" alt="Arch Linux" style="max-width: 80px">
 
 - Windows
-- MacOS
+- MacOS (see: [macOS Installation](/wiki/pages/MacOS%20Installation.md))
 - Linux, tested and confirmed working on the following distros:
   - Ubuntu 24.04
   - Debian 12
-  - Pop!_OS 22.04 LTS
+  - Pop!\_OS 22.04 LTS
   - Arch Linux
 
 ## Requirements
+
 ### Windows
+
 - [Python 3.12](https://www.python.org/downloads/windows/) **Windows installer 64-bit**
   - Tick `Add Python to PATH` when installing Python
 
 ### MacOS
+
 - [Python 3.12](https://www.python.org/downloads/macos/) **macOS 64-bit universal2 installer** or `brew install [email protected]`
 - mGBA 0.10.x `brew install mgba`
 
 Note: `brew` requires [Homebrew](https://brew.sh/) to be installed.
 
 ### Linux
+
 - [Python 3.12](https://www.python.org/downloads/source/) or `sudo apt install python3.12`
 - Install the following packages with `apt` or appropriate package manager: `sudo apt install python3-distutils python3-tk libmgba0.10 portaudio19-dev`
 - If `libmgba0.10` is not available on your distro, you can manually install the [mGBA 0.10.x .deb package](https://mgba.io/downloads.html) which includes `libmgba0.10`
 
 ## Download the Bot
+
 ### Stable Releases
 
 Visit the [releases](https://github.com/40Cakes/pokebot-gen3/releases) page for the latest stable releases, download the **pokebot-DATE.zip** file.
 
 The bot has an auto-updater that will check for new stable releases, once a day.
 
 ### Dev Releases
+
 <details>
 <summary>Expand</summary>
 
 To download the latest dev releases, go to the top of the repo page > click the green **Code** button > **Download ZIP**.
 
 Alternatively, if you'd like to be able to easily pull the latest dev releases, use git:
+
 - Install [GitHub Desktop](https://desktop.github.com/) (you don't need an account)
 - Click **Clone a repository from the Internet...**
 - Use repository URL `https://github.com/40Cakes/pokebot-gen3.git` and choose a save location on your PC
@@ -53,10 +60,12 @@ Alternatively, if you'd like to be able to easily pull the latest dev releases,
 </details>
 
 ### Optional
-- [Windows Terminal](https://github.com/microsoft/terminal/releases) - recommended for full 🌈<span style="color:#FF0000">c</span><span style="color:#FF7F00">o</span><span style="color:#FFFF00">l</span><span style="color:#00FF00">o</span><span style="color:#00FFFF">u</span><span style="color:#CF9FFF">r</span>🌈 and  ✨emoji support✨ in the console output
+
+- [Windows Terminal](https://github.com/microsoft/terminal/releases) - recommended for full 🌈<span style="color:#FF0000">c</span><span style="color:#FF7F00">o</span><span style="color:#FFFF00">l</span><span style="color:#00FF00">o</span><span style="color:#00FFFF">u</span><span style="color:#CF9FFF">r</span>🌈 and ✨emoji support✨ in the console output
 - [Notepad++](https://notepad-plus-plus.org/) - recommended for syntax highlighting while editing `.yml` config files
 
 ### Use a `venv` (optional)
+
 <details>
 <summary>Expand</summary>
 If you're using Python for any other projects, it is **highly recommended** to use a virtual environment (`venv`) to isolate these packages from your base environment.
@@ -68,7 +77,7 @@ Once Python is installed, set up a `venv`, open a shell in the bot directory and
 A `venv` may be “activated” using a script in its binary directory (`bin` on POSIX; `Scripts` on Windows). This will prepend that directory to your PATH, so that running python will invoke the environment’s Python interpreter and you can run installed scripts without having to use their full path. The invocation of the activation script is platform-specific (`<venv>` must be replaced by the path to the directory containing the virtual environment):
 
 | Platform | Shell                                         | Command to activate virtual environment                                                                                                       |
-|----------|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| -------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | POSIX    | bash/zsh<br/>fish<br/>csh/tcsh<br/>PowerShell | `$ source <venv>/bin/activate`<br/>`$ source <venv>/bin/activate.fish`<br/>`$ source <venv>/bin/activate.csh`<br/>`$ <venv>/bin/Activate.ps1` |
 | Windows  | cmd.exe<br/>PowerShell                        | `C:\> <venv>\Scripts\activate.bat`<br/>`PS C:\> <venv>\Scripts\Activate.ps1`                                                                  |
 
@@ -81,6 +90,7 @@ Once activated, run the bot (your shell should show `(venv)` if activated correc
 </details>
 
 ## Run the Bot
+
 - Place some **official** Pokémon .gba ROMs into the `./roms/` folder
 - Double click `pokebot.py` or run `python pokebot.py` in a terminal and follow the on-screen steps to create and/or select a profile
 
@@ -89,16 +99,18 @@ The bot ships with the default mGBA input mapping, see [here](pages/Configuratio
 You **must** ensure you are able to escape battle **100% of the time**, otherwise the bot will get stuck.
 If you have a save from mGBA that you'd like to import and use with the bot, then you will need to import the save state.
 
-This bot is still in development, as such, functionality is subject to change - always make sure you back up your `./profiles/` folder before updating your bot! 
+This bot is still in development, as such, functionality is subject to change - always make sure you back up your `./profiles/` folder before updating your bot!
 
 ## Import a Save
+
 - In mGBA (standalone), run a game and load into the save file
 - **File** > **Save State File...** > **Save**
 - Double click `pokebot.py` or run `python pokebot.py` in a terminal > type a profile **name** > click **Load Existing Save**
 - Open the save state file you just saved
 - A new bot profile will be created in the `./profiles/` folder, and launched
 
 ## Debugging (advanced)
+
 <details>
 <summary>Expand</summary>
 

wiki/pages/MacOS Installation.md

@@ -0,0 +1,135 @@
+# MacOS Installation Guide
+
+<img src="../images/os_apple.png" alt="MacOS" style="max-width: 80px">
+
+> All of these instructions are assuming you are using Apple Silicon.
+
+#### Install Brew
+
+Navigate to [HomeBrew](https://brew.sh/)'s website and use the command provided.
+
+#### Update and upgrade brew
+
+`brew update && brew upgrade`
+
+#### Install pyenv, and mgba
+
+`brew install pyenv`
+`brew install mgba`
+
+#### Pokébot Folder
+
+Download the latest version of the Pokébot (either release or dev), and move it to the directory you want to store it in.
+
+#### Terminal
+
+Close your existing terminal, and open a new one.
+Create a `.zshrc` file for your user by running:
+`touch ~/.zshrc`
+
+#### .zshrc
+
+Edit this new file with textedit, nano, vim, or a text editor of your choice.
+If using a GUI editor, ensure you save it as **Plain Text** format.
+Insert the following text into .zshrc file:
+
+```bash
+eval "$(pyenv init -)"
+if which pyenv-virtualenv-init > /dev/null; then eval "$(pyenv virtualenv-init -))"; fi
+```
+
+Close and re-open the terminal again.
+
+#### Install tcl/tk version 8.6.16 for your local user
+
+Unfortuantely, Brew does not have 8.6.16 (at the time of writing this), so we have to do this ourselves.
+
+- Make a new directory `mkdir ~/local-tcltk-src`
+- Download tcl 8.6.16 source and tk 8.6.16 source files - the `.tar.gz` files for both from https://www.tcl-lang.org/software/tcltk/download.html
+- Move both files to the `~/local-tcltk-src` folder we just created.
+- Navigate to ~/local-tcltk-src and run the following commands:
+  `tar xzf tcl8.6.16-src.tar.gz`
+  `tar xzf tcl8.6.16-src.tar.gz`
+- You should now have to files: `tcl8.6.16` and `tk8.6.16`
+- Create a dedicated install directory (aka 'Prefix') so Tcl/Tk does not interfere with system-wide or homebrew versions.
+- In a new terminal, `mkdir -p ~/local-tcltk`
+- Navigate to `~/local-tcltk-src/tcl8.6.16/unix` in the terminal, and enter:
+
+```bash
+./configure --prefix="$HOME/local-tcltk" \
+            --enable-threads \
+            --enable-64bit
+make
+make install
+```
+
+- Navigate to `~/local-tcltk-src/tck8.6.16/unix` in the terminal, and enter:
+
+```bash
+./configure --prefix="$HOME/local-tcltk" \
+            --enable-aqua \
+            --without-x \
+            --with-tcl="$HOME/local-tcltk/lib" \
+            --enable-threads \
+            --enable-64bit
+make
+make install
+```
+
+- Close and re-open the terminal
+
+#### Export linker/compiler flags, so Python build process uses your local Tcl/Tk:
+
+```bash
+export LDFLAGS="-L$HOME/local-tcltk/lib"
+export CPPFLAGS="-I$HOME/local-tcltk/include"
+export PKG_CONFIG_PATH="$HOME/local-tcltk/lib/pkgconfig"
+export TCL_LIBRARY="$HOME/local-tcltk/lib/tcl8.6"
+export TK_LIBRARY="$HOME/local-tcltk/lib/tk8.6"
+```
+
+#### Use PYTHON_CONFIGURE_OPTS when installing via pyenv
+
+```bash
+env \
+PYTHON_CONFIGURE_OPTS="--with-tcltk-includes='-I$HOME/local-tcltk/inc
+lude' \
+--with-tcltk-libs='-L$HOME/local-tcltk/lib -ltcl8.6 -ltk8.6'" \
+pyenv install 3.12.8
+```
+
+#### Verify dependencies:
+
+```bash
+pyenv shell 3.12.8
+python -V
+```
+
+- You should see `3.12.8`
+
+```bash
+python -m tkinter
+```
+
+- You should see a small window open
+
+#### Create your pyenv and activate it
+
+> Replace `myproject` with anything you like such as `pokebot`
+
+```bash
+pyenv virtualenv 3.12.8 myproject
+pyenv local myproject
+```
+
+#### Finished!
+Now your prompt should start with `(myproject)` (or whatever you named it).
+If it does, you are safe to go ahead and run the command:
+```python
+python /path-to/pokebot-gen3/pokebot.py
+```
+
+You should now see the bot window open as expected.
+
+#### Credits
+Thanks to **.orch** in the discord for figuring these steps out and creating a guide for future MacOS users!