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