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