Getting Started¤

Follow these steps to install and run xpuz, as well as the required dependencies.

Tip

If using pip or python doesn't work, try using pip3 or python3

Installing Python and pip¤

To install Python, download its installer here, or install it with pyenv. Ensure you tick the box that says Add Python 3 to PATH in the installation wizard.
If you have Python installed without pip, follow this guide to install it.

Creating a virtual environment¤

It is strongly recommended that you create a virtual environment before installing xpuz.

WindowsMacOS/Unix

pip install virtualenv
python -m venv myEnv
myEnv\scripts\activate # (1)!

If you cannot activate the virtual environment, try running Set-ExecutionPolicy Unrestricted -Scope Process in your terminal, ensuring you follow all the prompts. Then, try this step again.

pip install virtualenv
python -m venv myEnv
source myEnv/scripts/activate

Note

Your virtual environment can be deactivated with the deactivate command.

Installing `xpuz` and its optional dependencies¤

with pip recommended¤

xpuz is published as Python package and can be installed with pip, ideally by using a virtual environment. Open up your terminal (if you are unsure how, read FAQ) and read the following instructions.

Install xpuz

Latest2.x.x

pip install xpuz # (1)!

You can add the --user flag to install xpuz in your home directory, which is useful if you aren't using a virtual environment.

pip install xpuz=="2.*.*"

Install tkinter if you are on MacOS/Linux.

MacOSLinux

sudo pip install python3-tk

sudo apt-get install python3-tk

Install pycairo (optional)
```
pip install pycairo # (1)!
```
1. pycairo is a feature dependency that is required if you want to make PDFs from your generated crosswords. If you are on an operating system other than Windows, please read pycairo's Getting Started to install the required headers for pycairo.
  
  Warning
  
  Languages whose alphabets use complex glyphs (such as Mandarin and Japanese) are not supported when making PDFs.
Initialise the GUI.
```
xpuz-ctk
```

with git¤

You can use the git version control system to clone the full repository and run xpuz directly with Python.

Note

You must install git before using this method of installation.

git clone https://github.com/tomasvana10/xpuz.git
cd xpuz
pip install -r requirements.txt # (1)!
cd src
python -m xpuz

You can also install development dependencies by using pip install -r devdeps.txt. After you have done this and wish the build the project, ensure you are at the toplevel of the repository and run python -m build to build a wheel and tarball of the project.

Updating¤

Activate your virtual environment if you are using one.
Update the package.
```
pip install -U xpuz
```

Using Quickstart¤

You can utilise one of two scripts to quickly activate a virtual environment and update and start xpuz.

First, ensure you have installed Python and pip, then follow the OS specific steps.