docs/develop/Development-Environment.md

   1 # Setting up Nominatim for Development
   2
   3 This chapter gives an overview how to set up Nominatim for developement
   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). It has the following additional requirements:
  30
  31 * [behave test framework](https://behave.readthedocs.io) >= 1.2.5
  32 * [nose](https://nose.readthedocs.io)
  33 * [phpunit](https://phpunit.de) >= 7.3
  34 * [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)
  35
  36 The documentation is built with mkdocs:
  37
  38 * [mkdocs](https://www.mkdocs.org/) >= 1.1.2
  39
  40 ### Installing prerequisites on Ubuntu/Debian
  41
  42 Some of the Python packages require the newest version which is not yet
  43 available with the current distributions. Therefore it is recommended to
  44 install pip to get the newest versions.
  45
  46 To install all necessary packages run:
  47
  48 ```sh
  49 sudo apt install php-cgi phpunit php-codesniffer \
  50                  python3-pip python3-setuptools python3-dev
  51
  52 pip3 install --user behave nose mkdocs
  53 ```
  54
  55 The `mkdocs` executable will be located in `.local/bin`. You may have to add
  56 this directory to your path, for example by running:
  57
  58 ```
  59 echo 'export PATH=~/.local/bin:$PATH' > ~/.profile
  60 ```
  61
  62 If your distribution does not have PHPUnit 7.3+, you can install it (as well
  63 as CodeSniffer) via composer:
  64
  65 ```
  66 sudo apt-get install composer
  67 composer global require "squizlabs/php_codesniffer=*"
  68 composer global require "phpunit/phpunit=8.*"
  69 ```
  70
  71 The binaries are found in `.config/composer/vendor/bin`. You need to add this
  72 to your PATH as well:
  73
  74 ```
  75 echo 'export PATH=~/.config/composer/vendor/bin:$PATH' > ~/.profile
  76 ```
  77
  78
  79 ## Executing Tests
  80
  81 All tests are located in the `\test` directory.
  82
  83 ### Preparing the test database
  84
  85 Some of the behavioural test expect a test database to be present. You need at
  86 least 2GB RAM and 10GB disk space to create the database.
  87
  88 First create a separate directory for the test DB and fetch the test planet
  89 data and the Tiger data for South Dakota:
  90
  91 ```
  92 mkdir testdb
  93 cd testdb
  94 wget https://www.nominatim.org/data/test/nominatim-api-testdata.pbf
  95 wget -O - https://nominatim.org/data/tiger2018-nominatim-preprocessed.tar.gz | tar xz --wildcards --no-anchored '46*'
  96 ```
  97
  98 Configure and build Nominatim in the usual way:
  99
 100 ```
 101 cmake $USERNAME/Nominatim
 102 make
 103 ```
 104
 105 Create a minimal test settings file:
 106
 107 ```
 108 tee .env << EOF
 109 NOMINATIM_DATABASE_DSN="pgsql:dbname=test_api_nominatim"
 110 NOMINATIM_USE_US_TIGER_DATA=yes
 111 NOMINATIM_TIGER_DATA_PATH=tiger
 112 NOMINATIM_WIKIPEDIA_DATA_PATH=$USERNAME/Nominatim/test/testdb
 113 EOF
 114 ```
 115
 116 Inspect the file to check that all settings are correct for your local setup.
 117 In particular, the wikipedia path should point to the test directory in your
 118 Nominatim source directory.
 119
 120 Now you can import the test database:
 121
 122 ```
 123 dropdb --if-exists test_api_nominatim
 124 ./utils/setup.php --all --osm-file nominatim-api-testdb.pbf 2>&1 | tee import.log
 125 ./utils/specialphrases.php --wiki-import | psql -d test_api_nominatim 2>&1 | tee -a import.log
 126 ./utils/setup.php --import-tiger-data 2>&1 | tee -a import.log
 127 ```
 128
 129 ### Running the tests
 130
 131 To run all tests just go to the test directory and run make:
 132
 133 ```sh
 134 cd test
 135 make
 136 ```
 137
 138 To skip tests that require the test database, run `make no-test-db` instead.
 139
 140 For more information about the structure of the tests and how to change and
 141 extend the test suite, see the [Testing chapter](Testing.md).
 142
 143 ## Documentation Pages
 144
 145 The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
 146 built using the [MkDocs](https://www.mkdocs.org/) static site generation
 147 framework. The master branch is automatically deployed every night on
 148 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
 149
 150 To build the documentation, go to the build directory and run
 151
 152 ```
 153 make doc
 154 INFO - Cleaning site directory
 155 INFO - Building documentation to directory: /home/vagrant/build/site-html
 156 ```
 157
 158 This runs `mkdocs build` plus extra transformation of some files and adds
 159 symlinks (see `CMakeLists.txt` for the exact steps).
 160
 161 Now you can start webserver for local testing
 162
 163 ```
 164 build> mkdocs serve
 165 [server:296] Serving on http://127.0.0.1:8000
 166 [handlers:62] Start watching changes
 167 ```
 168
 169 If you develop inside a Vagrant virtual machine, use a port that is forwarded
 170 to your host:
 171
 172 ```
 173 build> mkdocs serve --dev-addr 0.0.0.0:8088
 174 [server:296] Serving on http://0.0.0.0:8088
 175 [handlers:62] Start watching changes
 176 ```