## Build instructions

*Crosswords* and *Crossword Editor* build on most modern Linux
distributions and MacOS ([build hints](docs/macos-build.md)). It was
developed primarily on Fedora and OpenSuse and should build easily on
those platforms with few add-ons. It has dependencies on GTK 4.8 and
libadwaita-1.2, which will be built submodules if not installed.

The easiest way to build and test Crosswords from source is by
building a flatpak. This command will build and install it:

```shell
$ flatpak-builder  --force-clean _flatpak/ org.gnome.Crosswords.Devel.json  --user --install
$ # To run the output:
$ flatpak run org.gnome.Crosswords.Devel
```

### Local build from a container image

An easy way to set up a development environment is to use `podman` to
download and run a container image.  This image already contains all
the dependencies for Crosswords, so you don't have to mess around with
your system packages.

Install `podman` and `distrobox` or `toolbox` on your distro, and then:

```shell
cd crosswords   # wherever you did your "git clone"
sh ci/pull-container-image.sh
```

In the Crosswords source tree, ``ci/pull-container-image.sh`` is a script
that will invoke ``podman pull`` to download the container image that
you can use for development.  It is the same image that Crosswords uses
for its continuous integration pipeline (CI), so you can have exactly
the same setup on your own machine.

Then, the `pull-container-image.sh` script will give you instructions
on how to use `distrobox` or `toolbox` to build and install Crosswords inside
the container:

```
You can now run either of these, depending on your preference
for distrobox or toolbox:

  distrobox create --image $image_name --name crosswords
  distrobox enter crosswords

  toolbox create --image $image_name --name crosswords
  toolbox enter crosswords

Once inside the container, you can build and install with this:

  sudo sh ci/build-and-install.sh

You can just run crosswords on the shell afterwards.  It is installed to
the overlay /usr filesystem, and will not intefere with your system:

  crosswords
```

Now you can build Crosswords while inside the container, and install
it.  With the instructions above, the Crosswords program will get
installed to the container's overlay file system for `/usr` without
affecting your main system.


### Local build

Use standard meson tools to build it locally on Linux:

```shell
$ meson setup _build -Dlocaledir=/usr/share/locale
$ ninja -C _build
```

**Note:** We set localedir just so that we can find translations of
language names. It's not necessary, but there will be a runtime
warning about missing translations without it.

**Note:** The meson in Ubuntu 21.10 isn't recent enough to build this
app. You can install a local version of meson that's sufficiently new
by running `pip3 install --user meson`.

### Load .puz files (Optional)

In order to use the convertor to load other crossword types, you need
to install some python dependencies. The easiest way to do this is to
use pip:

```shell
$ pip install -r requirements.txt
```

## Running Crosswords without installation

Running it locally out of the `builddir` is a little more involved as
it requires some environment variables set to work. To make this
simple and avoid a full system installation, a `run` script is
included.

Use it as follows:

```shell
$ cd _build/

$ # To run the game
$ ./run ./src/crosswords

$ # To run the crossword editor
$ ./run ./src/crossword-editor

$ # To use the convertor
$ ./run ./tools/ipuz-convertor -i puzzle.puz -o /path/to/puzzle.ipuz

$ # To debug the game
$ ./run gdb ./src/crosswords
```

## Loading Puzzle Sets

If you want to test the game with another puzzle-set without installation, you can use the `PUZZLE_SET_PATH` and `PATH` environment variables. As an example:

```shell
$ PATH=~/Projects/puzzle-sets-xword-dl/ PUZZLE_SET_PATH=~/Projects/puzzle-sets-xword-dl/_build/puzzle-sets/ ./run src/crosswords
```

## Common problems

### gschemas.compiled

Meson doesn't rebuild the compiled gschemas file when the source gschema file changes. If you see an error that looks similar to this after a rebuild:

```shell
$ ./run src/crosswords
(crosswords:100131): GLib-GIO-ERROR **: 09:46:51.527: Settings schema 'org.gnome.Crosswords' does not contain a key named 'hidden-puzzle-sets'
Trace/breakpoint trap (core dumped)
```

You'll have to recreate the compiled file. Assuming you're still in _build, this should fix it:

```shell
$ rm data/gschemas.compiled
$ ninja -C .
```
