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