]> git.openstreetmap.org Git - nominatim.git/blob - docs/develop/Development-Environment.md
Merge pull request #2450 from mtmail/tiger-data-2021
[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 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) >= 7.3
34 * [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)
35 * [Pylint](https://pylint.org/) (2.6.0 is used for the CI)
36 * [pytest](https://pytest.org)
37
38 The documentation is built with mkdocs:
39
40 * [mkdocs](https://www.mkdocs.org/) >= 1.1.2
41 * [mkdocstrings](https://mkdocstrings.github.io/)
42
43 ### Installing prerequisites on Ubuntu/Debian
44
45 Some of the Python packages require the newest version which is not yet
46 available with the current distributions. Therefore it is recommended to
47 install pip to get the newest versions.
48
49 To install all necessary packages run:
50
51 ```sh
52 sudo apt install php-cgi phpunit php-codesniffer \
53                  python3-pip python3-setuptools python3-dev pylint
54
55 pip3 install --user behave mkdocs mkdocstrings pytest
56 ```
57
58 The `mkdocs` executable will be located in `.local/bin`. You may have to add
59 this directory to your path, for example by running:
60
61 ```
62 echo 'export PATH=~/.local/bin:$PATH' > ~/.profile
63 ```
64
65 If your distribution does not have PHPUnit 7.3+, you can install it (as well
66 as CodeSniffer) via composer:
67
68 ```
69 sudo apt-get install composer
70 composer global require "squizlabs/php_codesniffer=*"
71 composer global require "phpunit/phpunit=8.*"
72 ```
73
74 The binaries are found in `.config/composer/vendor/bin`. You need to add this
75 to your PATH as well:
76
77 ```
78 echo 'export PATH=~/.config/composer/vendor/bin:$PATH' > ~/.profile
79 ```
80
81
82 ## Executing Tests
83
84 All tests are located in the `/test` directory.
85
86 To run all tests just go to the build directory and run make:
87
88 ```sh
89 cd build
90 make test
91 ```
92
93 For more information about the structure of the tests and how to change and
94 extend the test suite, see the [Testing chapter](Testing.md).
95
96 ## Documentation Pages
97
98 The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
99 built using the [MkDocs](https://www.mkdocs.org/) static site generation
100 framework. The master branch is automatically deployed every night on
101 [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
102
103 To build the documentation, go to the build directory and run
104
105 ```
106 make doc
107 INFO - Cleaning site directory
108 INFO - Building documentation to directory: /home/vagrant/build/site-html
109 ```
110
111 This runs `mkdocs build` plus extra transformation of some files and adds
112 symlinks (see `CMakeLists.txt` for the exact steps).
113
114 Now you can start webserver for local testing
115
116 ```
117 build> mame serve-doc
118 [server:296] Serving on http://127.0.0.1:8000
119 [handlers:62] Start watching changes
120 ```
121
122 If you develop inside a Vagrant virtual machine, use a port that is forwarded
123 to your host:
124
125 ```
126 build> PYTHONPATH=$SRCDIR mkdocs serve --dev-addr 0.0.0.0:8088
127 [server:296] Serving on http://0.0.0.0:8088
128 [handlers:62] Start watching changes
129 ```