Setup with WSL

Here I will describe how to install Python and Lua + dependencies inside WSL and have VSCode utilize them.

⚠️ This page is deprecated in favor of using a development container.

• Enable and Install Ubuntu
• Install Dependencies
• Configure Git
• Clone/Install the Plugins
• Editing in Visual Studio Code

Enable and Install Ubuntu (latest)

Follow the instructions here to enable WSL 2 on your machine and start a Linux subsystem. When you reach the point where it asks you to choose a flavor of Linux from the Microsoft Store, install the latest version of Ubuntu. Create a username and password for your WSL linux account when you start it for the first time.

We also recommend you install Windows Terminal, which offers a terminal experience closer to iTerm on OSX.

Install Dependencies

Next we'll install our language dependencies, Lua and Python.

sudo apt update
sudo apt install git-lfs tig zip unzip cmake build-essential
sudo apt install python-is-python3 pylint
sudo apt install lua5.3 liblua5.3-dev

Running the following commands will confirm the versions of each language:

$ python --version
Python 3.10.12
$ lua -v
Lua 5.3.3  Copyright (C) 1994-2016 Lua.org, PUC-Rio

Install LuaRocks + Lua Dependencies

Lua uses the luarocks package manager to install its dependencies. Ubuntu provides luarocks via apt, but only at version 2. We need version 3 or greater to install the lua-format script.

Install LuaRocks version 3+ using the instructions on their website. As of version 3.7.0, the exact instructions were:

wget https://luarocks.org/releases/luarocks-3.7.0.tar.gz
tar zxpf luarocks-3.7.0.tar.gz
cd luarocks-3.7.0
./configure && make && sudo make install
cd .. && rm -rf luarocks-3.7.0*

This will install LuaRocks into the /usr/local tree. Any libraries (rocks) installed with sudo will also be installed into /usr/local.

Next we install the specific libraries/scripts that we need:

sudo luarocks install luacheck
sudo luarocks install --server=https://luarocks.org/dev luaformatter

Configure Git

Next you will want to configure Git with your username and email to match your GitHub account.

git config --global user.name "<username>"
git config --global user.email "<email>"
git config --global pull.rebase true

The last command (pull.rebase true) tells Git to not create a merge commit every time you run a git pull, and instead attempt to keep the history nice and linear with a rebase.

Make sure your SSH key is configured and registered with GitHub. Copying an existing key or creating new keys is outside the scope of this doc, but you can find more information here.

Clone and Install the Plugins

We are now ready to clone a copy of the source repository from GitHub. The project must be cloned outside of WSL or it will cause issues with the Battle.net client¹. For this example we will clone to C:\\handynotes-plugins.

cd /mnt/c/
git clone [email protected]:zarillion/handynotes-plugins.git

⚠️ If you get Operation not permitted errors, the location you are cloning to is not mounted with metadata enabled. You can remount the drive with metadata enabled using: sudo mount -t drvfs C: /mnt/c -o metadata

Once cloned, you can install the plugins to your AddOns/ directory using the install.py script. You must run Windows Terminal as Administrator for the symlink creation to work!

cd /mnt/c/handynotes-plugins
python scripts/install.py -c /mnt/c/Program\ Files\ \(x86\)/World\ of\ Warcraft/_retail_/Interface/Addons

Change _retail_ to _beta_ or _ptr_ to install the plugins for Beta/PTR servers.

_{[1] The Battle.net client gets stuck in an infinite update loop if any addon file or directory is symlinked to a WSL network path like \\wsl$\Ubuntu\...}

Editing in Visual Studio Code

To work on the project in Code, install the Remote - WSL extension. This will allow you to open the project folder inside the WSL environment and allow the Python and Lua extensions to utilize the interpreters we installed above.