docs/develop/Development-Environment.md

   1 # Setting up Nominatim for Development
   2
   3 This chapter gives an overview how to set up Nominatim for development
   4 and how to run tests.
   5
   6 !!! Important
   7     This guide assumes you develop under the latest version of Debian/Ubuntu.
   8     You can of course also use your favourite distribution. You just might have
   9     to adapt the commands below slightly, in particular the commands for
  10     installing additional software.
  11
  12 ## Installing Nominatim
  13
  14 The first step is to install Nominatim itself. Please follow the installation
  15 instructions in the [Admin section](../admin/Installation.md). You don't need
  16 to set up a webserver for development, the webserver that can be started
  17 via `nominatim serve` is sufficient.
  18
  19 If you want to run Nominatim in a VM via Vagrant, use the default `ubuntu24` setup.
  20 Vagrant's libvirt provider runs out-of-the-box under Ubuntu. You also need to
  21 install an NFS daemon to enable directory sharing between host and guest. The
  22 following packages should get you started:
  23
  24     sudo apt install vagrant vagrant-libvirt libvirt-daemon nfs-kernel-server
  25
  26 ## Prerequisites for testing and documentation
  27
  28 The Nominatim test suite consists of behavioural tests (using behave) and
  29 unit tests (using PHPUnit for PHP code and pytest for Python code).
  30 It has the following additional requirements:
  31
  32 * [behave test framework](https://behave.readthedocs.io) >= 1.2.6
  33 * [phpunit](https://phpunit.de) (9.5 is known to work)
  34 * [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)
  35 * [Pylint](https://pylint.org/) (CI always runs the latest version from pip)
  36 * [mypy](http://mypy-lang.org/) (plus typing information for external libs)
  37 * [Python Typing Extensions](https://github.com/python/typing_extensions) (for Python < 3.9)
  38 * [pytest](https://pytest.org)
  39 * [pytest-asyncio](https://pytest-asyncio.readthedocs.io)
  40
  41 For testing the Python search frontend, you need to install extra dependencies
  42 depending on your choice of webserver framework:
  43
  44 * [httpx](https://www.python-httpx.org/) (Starlette only)
  45 * [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (Starlette only)
  46
  47 The documentation is built with mkdocs:
  48
  49 * [mkdocs](https://www.mkdocs.org/) >= 1.1.2
  50 * [mkdocstrings](https://mkdocstrings.github.io/) >= 0.25
  51 * [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
  52
  53 ### Installing prerequisites on Ubuntu/Debian
  54
  55 The Python tools should always be run with the most recent version.
  56 In particular, pylint tends to have a lot of breaking changes between versions.
  57 The easiest way, to handle these Python dependencies is to run your
  58 development from within a virtual environment.
  59
  60 To set up the virtual environment with all necessary packages run:
  61
  62 ```sh
  63 virtualenv ~/nominatim-dev-venv
  64 ~/nominatim-dev-venv/bin/pip install\
  65     psycopg2-binary psutil psycopg[binary] PyICU SQLAlchemy \
  66     python-dotenv jinja2 pyYAML datree \
  67     behave mkdocs mkdocstrings pytest pytest-asyncio pylint \
  68     types-jinja2 types-markupsafe types-psutil types-psycopg2 \
  69     types-pygments types-pyyaml types-requests types-ujson \
  70     types-urllib3 typing-extensions unicorn falcon
  71 ```
  72
  73 Now enter the virtual environment whenever you want to develop:
  74
  75 ```sh
  76 . ~/nominatim-dev-venv/bin/activate
  77 ```
  78
  79 For installing the PHP development tools, run:
  80
  81 ```sh
  82 sudo apt install php-cgi phpunit php-codesniffer
  83 ```
  84
  85 If your distribution does not have PHPUnit 7.3+, you can install it (as well
  86 as CodeSniffer) via composer:
  87
  88 ```
  89 sudo apt-get install composer
  90 composer global require "squizlabs/php_codesniffer=*"
  91 composer global require "phpunit/phpunit=8.*"
  92 ```
  93
  94 The binaries are found in `.config/composer/vendor/bin`. You need to add this
  95 to your PATH:
  96
  97 ```
  98 echo 'export PATH=~/.config/composer/vendor/bin:$PATH' > ~/.profile
  99 ```
 100
 101 ### Running Nominatim during development
 102
 103 The source code for Nominatim can be found in the `src` directory and can
 104 be run in-place. The source directory features a special script
 105 `nominatim-cli.py` which does the same as the installed 'nominatim' binary
 106 but executes against the code in the source tree. For example:
 107
 108 ```
 109 me@machine:~$ cd Nominatim
 110 me@machine:~Nominatim$ ./nominatim-cli.py --version
 111 Nominatim version 4.4.99-1
 112 ```
 113
 114 Make sure you have activated the virtual environment holding all
 115 necessary dependencies.
 116
 117 ## Executing Tests
 118
 119 All tests are located in the `/test` directory.
 120
 121 To run all tests, run make from the source root:
 122
 123 ```sh
 124 make tests
 125 ```
 126
 127 There are also make targets for executing only parts of the test suite.
 128 For example to run linting only use:
 129
 130 ```sh
 131 make lint
 132 ```
 133
 134 The possible testing targets are: mypy, lint, pytest, bdd.
 135
 136 For more information about the structure of the tests and how to change and
 137 extend the test suite, see the [Testing chapter](Testing.md).
 138
 139 ## Documentation Pages
 140
 141 The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
 142 built using the [MkDocs](https://www.mkdocs.org/) static site generation
 143 framework. The master branch is automatically deployed every night on
 144 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
 145
 146 To build the documentation, go to the build directory and run
 147
 148 ```
 149 make doc
 150 INFO - Cleaning site directory
 151 INFO - Building documentation to directory: /home/vagrant/build/site-html
 152 ```
 153
 154 This runs `mkdocs build` plus extra transformation of some files and adds
 155 symlinks (see `CMakeLists.txt` for the exact steps).
 156
 157 Now you can start webserver for local testing
 158
 159 ```
 160 build> make serve-doc
 161 [server:296] Serving on http://127.0.0.1:8000
 162 [handlers:62] Start watching changes
 163 ```
 164
 165 If you develop inside a Vagrant virtual machine, use a port that is forwarded
 166 to your host:
 167
 168 ```
 169 build> PYTHONPATH=$SRCDIR mkdocs serve --dev-addr 0.0.0.0:8088
 170 [server:296] Serving on http://0.0.0.0:8088
 171 [handlers:62] Start watching changes
 172 ```