개발자 노트
개발자 노트 (Developer notes)
이 페이지는 Redis JSON의 디버깅, 테스트, 문서화에 관한 개발자용 메모예요. RedisJSON(JSON을 제공하는 Redis 모듈)을 개발하려면 개발 환경(리눅스 또는 macOS 기반)을 구성하고, RedisJSON을 빌드하고, 테스트와 벤치마크를 실행하고, JSON 모듈과 그 테스트를 디버깅하는 작업이 필요해요.
git 저장소 복제하기 (Cloning the git repository)
RedisJSON 모듈과 그 서브모듈을 복제하려면 다음을 실행하세요:
git clone --recursive https://github.com/RedisJSON/RedisJSON.git
격리된 환경에서 작업하기 (Working in an isolated environment)
개발 환경을 격리하는 데는 여러 이유가 있어요. 예를 들어 워크스테이션을 깨끗하게 유지하거나, 다른 리눅스 배포판을 위해 개발하는 경우가 있죠. 격리된 개발 환경으로 가상 머신(virtual machine)을 쓸 수 있는데, 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 -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 # 사전 준비물 설치
make build
DEBUG=1 # 디버그 변형 빌드
SAN=type # LLVM sanitizer로 빌드 (type=address|memory|leak|thread)
VALGRIND|VG=1 # Valgrind 테스트용 빌드
make clean # 바이너리 파일 제거
ALL=1 # 바이너리 디렉터리 제거
make all # 모든 라이브러리와 패키지 빌드
make test # cargo와 python 테스트 모두 실행
make cargo_test # 내장 rust 단위 테스트 실행
make pytest # RLTest로 플로우 테스트 실행
TEST=file:name # `file`에서 `name`에 해당하는 테스트 실행
TEST_ARGS="..." # RLTest 인자
QUICK=1 # 일반 테스트만 실행
GEN=1 # standalone Redis 토폴로지에서 일반 테스트 실행
AOF=1 # standalone 토폴로지에서 AOF 영속성 테스트 실행
SLAVES=1 # standalone 토폴로지에서 복제 테스트 실행
CLUSTER=1 # Redis Open Source Cluster 토폴로지에서 일반 테스트 실행
VALGRIND|VG=1 # 지정 테스트를 Valgrind로 실행
VERBOSE=1 # RLTest 관련 정보를 더 표시
make pack # 패키지 빌드 (RAMP 파일)
make upload-artifacts # 스냅샷 패키지를 S3로 복사
OSNICK=nick # 특정 OSNICK용 스냅샷 복사
make upload-release # 릴리스 패키지를 S3로 복사
업로드 작업 공통 옵션:
STAGING=1 # 스테이징 랩 영역으로 복사 (검증용)
FORCE=1 # CI 환경 밖에서의 작업 허용
VERBOSE=1 # 더 많은 세부 정보 표시
NOP=1 # 복사하지 않고 명령만 출력
make coverage # 커버리지 분석 수행
make show-cov # 커버리지 분석 결과 표시 (COV=1을 의미)
make upload-cov # 커버리지 분석 결과를 codecov.io에 업로드 (COV=1을 의미)
make docker # 특정 리눅스 배포판용 빌드
OSNICK=nick # 빌드할 리눅스 배포판
REDIS_VER=ver # Redis 버전 `ver` 사용
TEST=1 # 빌드 후 테스트
PACK=1 # 패키지 생성
ARTIFACTS=1 # docker 이미지에서 아티팩트 복사
PUBLISH=1 # 빌드 후 게시 (즉, docker push)
make sanbox # CLang Sanitizer 테스트용 컨테이너 생성
소스에서 빌드하기 (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 인스턴스 또는 여러분이 제공하는 인스턴스에 대해 실행할 수 있어요. "임베디드" 모드를 쓰려면 redis-server 실행 파일이 PATH에 있어야 해요.
임베디드 서버의 스폰은 REDIS_PORT 환경 변수로 Redis 포트를 지정해 덮어쓸 수 있어요. 예:
$ # 모듈 테스트에 기존 로컬 Redis 인스턴스 사용
$ REDIS_PORT=6379 make test
디버깅 (Debugging)
디버깅 정보를 포함하려면 RedisJSON을 컴파일하기 전에 DEBUG 환경 변수를 설정해야 해요. 예를 들어 export DEBUG=1을 실행하세요.
Python 테스트에는 단일 테스트 모드에서 중단점(breakpoint)을 추가할 수 있어요. 중단점을 설정하려면 테스트 안에서 BB() 함수를 호출하세요.