开发者笔记

关于JSON调试、测试和文档的注意事项。

开发Redis JSON涉及设置开发环境（可以是基于Linux或macOS的），构建RedisJSON（提供JSON的Redis模块），运行测试和基准测试，以及调试JSON模块及其测试。

克隆 git 仓库

要克隆 RedisJSON 模块及其子模块，请运行：

git clone --recursive https://github.com/RedisJSON/RedisJSON.git

在隔离环境中工作

使用隔离环境进行开发有几个原因，比如保持你的工作站清洁以及为不同的Linux发行版进行开发。

你可以使用虚拟机作为隔离的开发环境。要设置一个，你可以使用Vagrant或Docker。

设置一个带有Docker的虚拟机：

rejson=$(docker run -d -it -v $PWD:/build debian:bullseye bash)
docker exec -it $rejson bash

然后在容器内运行 cd /build。

在这种模式下，所有安装都保留在Docker容器的范围内。退出容器后，您可以使用之前的docker exec命令重新启动它，或者将容器的状态保存为镜像并在以后恢复：

docker commit $rejson redisjson1
docker stop $rejson
rejson=$(docker run -d -it -v $PWD:/build redisjson1 bash)
docker exec -it $rejson bash

你可以将debian:bullseye替换为你选择的操作系统。如果你使用与主机相同的操作系统，你可以在构建后在主机上运行RedisJSON二进制文件。

安装先决条件

要构建和测试RedisJSON，需要根据底层操作系统安装几个软件包。目前，我们支持Ubuntu/Debian、CentOS、Fedora和macOS。

进入 RedisJSON 目录并运行：

$ ./sbin/setup

这将在您的系统上安装各种包，使用本地的包管理器和pip。它会自动调用sudo，提示获取权限。

如果您希望避免这种情况，您可以：

查看 system-setup.py 并手动安装包，
使用 system-setup.py --nop 显示安装命令而不执行它们，
使用如上所述的隔离环境，
使用Python虚拟环境，因为已知Python安装在不隔离使用时非常敏感：python -m virtualenv venv; . ./venv/bin/activate

安装Redis

通常，最好运行最新版本的Redis。

如果您的操作系统有 Redis 6.x 包，您可以使用操作系统的包管理器进行安装。

否则，你可以调用

$ ./deps/readies/bin/getredis

获取帮助

make help 提供了开发功能的快速摘要：

make setup         # install prerequisites

make build
  DEBUG=1          # build debug variant
  SAN=type         # build with LLVM sanitizer (type=address|memory|leak|thread)
  VALGRIND|VG=1    # build for testing with Valgrind
make clean         # remove binary files
  ALL=1            # remove binary directories

make all           # build all libraries and packages

make test          # run both cargo and python tests
make cargo_test    # run inbuilt rust unit tests
make pytest        # run flow tests using RLTest
  TEST=file:name     # run test matching `name` from `file`
  TEST_ARGS="..."    # RLTest arguments
  QUICK=1            # run only general tests
  GEN=1              # run general tests on a standalone Redis topology
  AOF=1              # run AOF persistency tests on a standalone Redis topology
  SLAVES=1           # run replication tests on standalone Redis topology
  CLUSTER=1          # run general tests on a Redis Community Edition Cluster topology
  VALGRIND|VG=1      # run specified tests with Valgrind
  VERBOSE=1          # display more RLTest-related information

make pack          # build package (RAMP file)
make upload-artifacts   # copy snapshot packages to S3
  OSNICK=nick             # copy snapshots for specific OSNICK
make upload-release     # copy release packages to S3

common options for upload operations:
  STAGING=1             # copy to staging lab area (for validation)
  FORCE=1               # allow operation outside CI environment
  VERBOSE=1             # show more details
  NOP=1                 # do not copy, just print commands

make coverage      # perform coverage analysis
make show-cov      # show coverage analysis results (implies COV=1)
make upload-cov    # upload coverage analysis results to codecov.io (implies COV=1)

make docker        # build for specific Linux distribution
  OSNICK=nick        # Linux distribution to build for
  REDIS_VER=ver      # use Redis version `ver`
  TEST=1             # test after build
  PACK=1             # create packages
  ARTIFACTS=1        # copy artifacts from docker image
  PUBLISH=1          # publish (i.e. docker push) after build

make sanbox        # create container for CLang Sanitizer tests

从源代码构建

运行 make build 来构建 RedisJSON。

注释：

二进制文件根据平台和构建变体放置在 target/release/ 目录下。
RedisJSON 使用 Cargo 作为其构建系统。make build 将调用 Cargo 以及完成构建所需的后续 make 命令。

使用 make clean 来移除构建产物。make clean ALL=1 将移除整个 bin 子目录。

运行测试

有几组单元测试：

Rust 测试，集成在源代码中，通过 make cargo_test 运行。
Python 测试（由 RLTest 启用），位于 tests/pytests，通过 make pytest 运行。

你可以使用make test运行所有测试。要仅运行特定测试，请使用TEST参数。例如，运行make test TEST=regex。

您可以针对“嵌入式”一次性Redis实例或您提供的实例运行模块的测试。要使用“嵌入式”模式，您必须在PATH中包含redis-server可执行文件。

您可以通过指定REDIS_PORT环境变量来覆盖嵌入式服务器的生成，例如：

$ # use an existing local Redis instance for testing the module
$ REDIS_PORT=6379 make test

调试

要包含调试信息，你需要在编译 RedisJSON 之前设置 DEBUG 环境变量。例如，运行 export DEBUG=1。

您可以在单测试模式下向Python测试添加断点。要设置断点，请在测试内部调用BB()函数。