개발자 노트

개발자 노트 (Developer notes)

Redis JSON(RedisJSON)은 Rust로 작성된 Redis 모듈이에요. 이 페이지는 JSON 디버깅, 테스트, 문서화를 위한 개발자용 노트예요. 직접 개발 환경을 세팅하고 빌드하고 테스트하는 과정을 하나씩 안내해 드릴게요.

출처: Redis 공식 문서 — Developer notes

RedisJSON 개발은 개발 환경 설정(Linux 기반 또는 macOS 기반), RedisJSON 빌드(JSON 기능을 제공하는 Redis 모듈), 테스트 및 벤치마크 실행, 그리고 JSON 모듈과 테스트의 디버깅을 포함해요.

Git 저장소 복제 (Cloning the git repository)

RedisJSON 모듈과 그 서브모듈을 복제하려면 다음을 실행해요.

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

격리된 환경에서 작업하기 (Working in an isolated environment)

격리된 환경에서 개발하는 데는 몇 가지 이유가 있어요. 예를 들어 워크스테이션을 깨끗하게 유지하거나, 다른 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는 원하는 OS로 바꿔도 돼요. 호스트 머신과 같은 OS를 쓰면, 빌드된 RedisJSON 바이너리를 호스트에서 바로 실행할 수 있어요.

사전 요구사항 설치 (Installing prerequisites)

RedisJSON을 빌드하고 테스트하려면 OS에 맞는 여러 패키지를 설치해야 해요. 현재 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 설치 (Installing Redis)

일반적으로 최신 Redis 버전을 실행하는 것이 가장 좋아요.

OS에 Redis 6.x 패키지가 있다면 OS 패키지 매니저로 설치할 수 있어요. 아니라면 다음을 실행해요.

$ ./deps/readies/bin/getredis

도움말 확인 (Getting help)

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 Open Source 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

소스에서 빌드하기 (Building from source)

make build를 실행해서 RedisJSON을 빌드해요.

참고 사항:

  • 바이너리 파일은 플랫폼과 빌드 변형에 따라 target/release/ 아래에 놓여요.
  • RedisJSON은 빌드 시스템으로 Cargo를 사용해요. make build는 Cargo와 그다음에 필요한 make 명령을 모두 호출해서 빌드를 완료해요.

make clean으로 빌드 산출물을 제거할 수 있어요. make clean ALL=1은 전체 bin 하위 디렉터리를 제거합니다.

테스트 실행 (Running tests)

여러 세트의 단위 테스트가 있어요.

  • 소스 코드에 통합된 Rust 테스트 — make cargo_test로 실행
  • tests/pytests에 있는 Python 테스트(RLTest 사용) — make pytest로 실행

모든 테스트는 make test로 실행할 수 있어요. 특정 테스트만 실행하려면 TEST 파라미터를 사용해요. 예를 들어 make test TEST=regex처럼요.

모듈 테스트는 "내장(embedded)"된 일회용 Redis 인스턴스나 직접 제공한 인스턴스에 대해 실행할 수 있어요. "embedded" 모드를 쓰려면 redis-server 실행 파일이 PATH에 있어야 해요.

내장 서버 생성을 재정의하려면 REDIS_PORT 환경 변수로 Redis 포트를 지정하면 돼요.

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

디버깅 (Debugging)

디버깅 정보를 포함하려면, RedisJSON을 컴파일하기 전에 DEBUG 환경 변수를 설정해야 해요. 예를 들어 export DEBUG=1처럼요.

Python 테스트에는 단일 테스트 모드에서 브레이크포인트를 추가할 수 있어요. 브레이크포인트를 설정하려면 테스트 안에서 BB() 함수를 호출하면 됩니다.

더 알아보기 (Learn more)