1# Developing RediSearch
2
3Developing RediSearch involves setting up the development environment (which can be either Linux-based or macOS-based), building RediSearch, running tests and benchmarks, and debugging both the RediSearch module and its tests.
4
5## Cloning the git repository
6By invoking the following command, RediSearch module and its submodules are cloned:
7```sh
8git clone --recursive https://github.com/RediSearch/RediSearch.git
9```
10## Working in an isolated environment
11There are several reasons to develop in an isolated environment, like keeping your workstation clean, and developing for a different Linux distribution.
12The most general option for an isolated environment is a virtual machine (it's very easy to set one up using [Vagrant](https://www.vagrantup.com)).
13Docker is even a more agile, as it offers an almost instant solution:
14
15```
16search=$(docker run -d -it -v $PWD:/build debian:bullseys bash)
17docker exec -it $search bash
18```
19Then, from within the container, ```cd /build``` and go on as usual.
20
21In this mode, all installations remain in the scope of the Docker container.
22Upon exiting the container, you can either re-invoke it with the above ```docker exec``` or commit the state of the container to an image and re-invoke it on a later stage:
23
24```
25docker commit $search redisearch1
26docker stop $search
27search=$(docker run -d -it -v $PWD:/build rediseatch1 bash)
28docker exec -it $search bash
29```
30
31You can replace `debian:bullseye` with your OS of choice, with the host OS being the best choice (so you can run the RediSearch binary on your host once it is built).
32
33## Installing prerequisites
34
35To build and test RediSearch one needs to install several packages, depending on the underlying OS. Currently, we support the Ubuntu/Debian, CentOS, Fedora, and macOS.
36
37First, enter `RediSearch` directory.
38
39If you have ```gnu make``` installed, you can execute,
40
41On Linux:
42```
43sudo make setup
44```
45On macOS:
46```
47make setup
48```
49
50Alternatively, invoke the following (with `sudo` for Linux):
51
52```
53./deps/readies/bin/getpy2
54./system-setup.py
55```
56Note that ```system-setup.py``` **will install various packages on your system** using the native package manager and pip.
57
58If you prefer to avoid that, you can:
59
60* Review `system-setup.py` and install packages manually,
61* Use an isolated environment like explained above,
62* Use a Python virtual environment, as Python installations are known to be sensitive when not used in isolation: `python2 -m virtualenv venv; . ./venv/bin/activate`
63
64## Installing Redis
65As a rule of thumb, you're better off running the latest Redis version.
66
67If your OS has a Redis 6.x package, you can install it using the OS package manager.
68
69Otherwise, you can invoke ```sudo ./deps/readies/bin/getredis```.
70Skip `sudo` on macOS.
71
72## Getting help
73```make help``` provides a quick summary of the development features.
74
75## Building from source
76```make build``` will build RediSearch.
77To enable unit tests, add ```TEST=1```.
78Note that RediSearch uses [CMake](https://cmake.org) as its build system. ```make build``` will invoke both CMake and the subsequent make command that's required to complete the build.
79Use ```make clean``` to remove built artifacts. ```make clean ALL=1``` will remove the entire ```RediSearch/build``` directory.
80
81### Diagnosing CMake
82To get a glimpse into CMake decesion process, add ```WHY=1``` to the build command.
83CMake stores its intermediate files in ```RediSearch/build```.
84Afterwards, one can use:
85```
86cd build
87make -n
88```
89or:
90```
91cd build
92make V=1
93```
94to further diagnose the build process.
95
96## Running Redis with RediSearch
97The following will run ```redis``` and load RediSearch module.
98```
99make run
100```
101You can open ```redis-cli``` in another terminal to interact with it.
102
103## Running tests
104There are several sets of unit tests:
105* C tests, located in ```tests/ctests```, run by ```make c_tests```.
106* C++ tests (enabled by GTest), located in ```tests/cpptests```, run by ```make cpp_tests```.
107* Python tests (enabled by RLTest), located in ```tests/pytests```, run by ```make pytest```.
108
109One can run all tests by invoking ```make test```.
110A single test can be run using the ```TEST``` parameter, e.g. ```make test TEST=regex```.
111
112## Debugging
113To build for debugging (enabling symbolic information and disabling optimization), run ```make DEBUG=1```.
114One can the use ```make run DEBUG=1``` to invoke ```gdb```.
115In addition to the usual way to set breakpoints in ```gdb```, it is possible to use the ```BB``` macro to set a breakpoint inside RediSearch code. It will only have an effect when running under ```gdb```.
116
117Similarly, Python tests in a single-test mode, one can set a breakpoint by using the ```BB()``` function inside a test.
118
119