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 that you develop under the latest version of Ubuntu. You
   8     can of course also use your favourite distribution. You just might have to
   9     adapt the commands below slightly, in particular the commands for installing
  10     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 is included with PHP
  17 is sufficient.
  18
  19 If you want to run Nominatim in a VM via Vagrant, use the default `ubuntu` 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 * [sanic-testing](https://sanic.dev/en/plugins/sanic-testing/getting-started.html) (sanic only)
  45 * [httpx](https://www.python-httpx.org/) (starlette only)
  46 * [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (starlette only)
  47
  48 The documentation is built with mkdocs:
  49
  50 * [mkdocs](https://www.mkdocs.org/) >= 1.1.2
  51 * [mkdocstrings](https://mkdocstrings.github.io/) >= 0.16
  52 * [mkdocstrings-python-legacy](https://mkdocstrings.github.io/python-legacy/)
  53
  54 ### Installing prerequisites on Ubuntu/Debian
  55
  56 Some of the Python packages require the newest version which is not yet
  57 available with the current distributions. Therefore it is recommended to
  58 install pip to get the newest versions.
  59
  60 To install all necessary packages run:
  61
  62 ```sh
  63 sudo apt install php-cgi phpunit php-codesniffer \
  64                  python3-pip python3-setuptools python3-dev
  65
  66 pip3 install --user behave mkdocs mkdocstrings pytest pytest-asyncio pylint \
  67                     mypy types-PyYAML types-jinja2 types-psycopg2 types-psutil \
  68                     types-ujson types-requests typing-extensions\
  69                     sanic-testing httpx asgi-lifespan
  70 ```
  71
  72 The `mkdocs` executable will be located in `.local/bin`. You may have to add
  73 this directory to your path, for example by running:
  74
  75 ```
  76 echo 'export PATH=~/.local/bin:$PATH' > ~/.profile
  77 ```
  78
  79 If your distribution does not have PHPUnit 7.3+, you can install it (as well
  80 as CodeSniffer) via composer:
  81
  82 ```
  83 sudo apt-get install composer
  84 composer global require "squizlabs/php_codesniffer=*"
  85 composer global require "phpunit/phpunit=8.*"
  86 ```
  87
  88 The binaries are found in `.config/composer/vendor/bin`. You need to add this
  89 to your PATH as well:
  90
  91 ```
  92 echo 'export PATH=~/.config/composer/vendor/bin:$PATH' > ~/.profile
  93 ```
  94
  95
  96 ## Executing Tests
  97
  98 All tests are located in the `/test` directory.
  99
 100 To run all tests just go to the build directory and run make:
 101
 102 ```sh
 103 cd build
 104 make test
 105 ```
 106
 107 For more information about the structure of the tests and how to change and
 108 extend the test suite, see the [Testing chapter](Testing.md).
 109
 110 ## Documentation Pages
 111
 112 The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
 113 built using the [MkDocs](https://www.mkdocs.org/) static site generation
 114 framework. The master branch is automatically deployed every night on
 115 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
 116
 117 To build the documentation, go to the build directory and run
 118
 119 ```
 120 make doc
 121 INFO - Cleaning site directory
 122 INFO - Building documentation to directory: /home/vagrant/build/site-html
 123 ```
 124
 125 This runs `mkdocs build` plus extra transformation of some files and adds
 126 symlinks (see `CMakeLists.txt` for the exact steps).
 127
 128 Now you can start webserver for local testing
 129
 130 ```
 131 build> make serve-doc
 132 [server:296] Serving on http://127.0.0.1:8000
 133 [handlers:62] Start watching changes
 134 ```
 135
 136 If you develop inside a Vagrant virtual machine, use a port that is forwarded
 137 to your host:
 138
 139 ```
 140 build> PYTHONPATH=$SRCDIR mkdocs serve --dev-addr 0.0.0.0:8088
 141 [server:296] Serving on http://0.0.0.0:8088
 142 [handlers:62] Start watching changes
 143 ```