Developing RedisTimeSeries involves setting up the development environment (which can be either Linux-based or macOS-based), building RedisTimeSeries, running tests and benchmarks, and debuugging both the RedisTimeSeries module and its tests.
Cloning the git repository¶
By invoking the following command, RedisTimeSeries module and its submodules are cloned:
git clone --recursive https://github.com/RedisTimeSeries/RedisTimeSeries.git
Working in an isolated environment¶
There are several reasons to develop in an isolated environment, like keeping your workstation clean, and developing for a different Linux distribution. The most general option for an isolated environment is a virtual machine (it's very easy to set one up using Vagrant). Docker is even a more agile solution, as it offers an almost instant solution:
ts=$(docker run -d -it -v $PWD:/build debian:buster bash) docker exec -it $ts bash
Then, from whithin the container,
cd /build and go on as usual.
In this mode, all installations remain in the scope of the Docker container.
Upon exiting the container, you can either re-invoke the container with the above
docker exec or commit the state of the container to an image and re-invoke it on a later stage:
docker commit $ts ts1 docker stop $ts ts=$(docker run -d -it -v $PWD:/build ts1 bash) docker exec -it $ts bash
To build and test RedisTimeSeries one needs to install serveral packages, depending on the underlying OS. Currently, we support the Ubuntu/Debian, CentOS, Fedora, and macOS.
If you have
gnu make installed, you can execute
cd RedisTimeSeries make setup
Alternatively, just invoke the following:
cd RedisTimeSeries ./deps/readies/bin/getpy2 ./system-setup.py
system-setup.py will install various packages on your system using the native package manager and pip. This requires root permissions (i.e. sudo) on Linux.
If you prefer to avoid that, you can:
- Review system-setup.py and install packages manually,
- Use an isolated environment like explained above,
- Utilize a Python virtual environment, as Python installations known to be sensitive when not used in isolation.
Next, execute the following, to complete dependency acquisition:
As a rule of thumb, you're better off running the latest Redis version.
If your OS has a Redis 5.x package, you can install it using the OS package manager.
Otherwise, you can invoke
make help provides a quick summary of the development features.
Building from source¶
make build will build RedisTimeSeries.
To enable unit tests, add
Note that RedisTimeSeries uses CMake as its build system.
make build will invoke both CMake and the subsequent make command that's required to complete the build.
make clean to remove built artifacts.
make clean ALL=1 will remove the entire
To get a glimpse into CMake decesion process, add
WHY=1 to the build command.
CMake stores its intermediate files in
Afterwards, one can use:
cd build make -n
cd build make V=1
to further diagnose the build process.
Running Redis with RedisTimeSeries¶
The following will run
redis and load RedisTimeSeries module.
You can open
redis-cli in another terminal to interact with it.
There are several sets of unit tests:
C tests, located in
src/tests, run by
C++ tests (enabled by GTest), located in
src/cpptests, run by
* Python tests (enabled by RLTest), located in
src/pytests, run by
One can run all tests by invoking
A single test can be run using the
TEST parameter, e.g.
make test TEST=regex.
To build for debugging (enabling symbolic information and disabling optimization), run
One can the use
make run DEBUG=1 to invoke
In addition to the usual way to set breakpoints in
gdb, it is possible to use the
BB macro to set a breakpoint inside RedisTimeSeries code. It will only have an effect when running under
Similarly, Python tests in a single-test mode, one can set a breakpoint by using the
BB() function inside a test.