102 빌드와 시험 — 여럿이 짓는 프로젝트의 구조

102.1 빌드가 있으면 무엇이 달라지는가#

빌드 도구가 대신해 주는 일은 셋이다.

가운데 것이 이 절의 주제다. 없을 때 무슨 일이 생기는지 실제로 일으켜 본다.

#!/bin/sh
# 낡은 산출물 사고를 재현한다.
#
#   헤더의 GREET_MAX 를 16 → 32 로 넓히고 greet.c 만 손댄다.
#   의존을 적지 않은 규칙은 greet.o 만 다시 만든다 --- greet 는 32 를 믿고 쓰는데
#   main.o 는 옛 16 으로 그릇을 잡은 채 남는다. 곧 *버퍼가 넘친다.*
set -eu
cd "$(dirname "$0")"

cp greet.h greet.h.orig
trap 'mv -f greet.h.orig greet.h 2>/dev/null || true' EXIT INT TERM

for kind in broken fixed; do
    printf '== Makefile.%s\n' "$kind"
    make -s -f "Makefile.$kind" clean >/dev/null
    make -s -f "Makefile.$kind" CFLAGS="-std=c23 -Wall -Wextra -g -fsanitize=address$([ $kind = fixed ] && printf ' -MMD -MP')" >/dev/null 2>&1
    printf '   처음        : %s\n' "$(./demo 2>&1 | head -1)"

    sed -i 's/#define GREET_MAX 16/#define GREET_MAX 32/' greet.h
    touch greet.c
    make -s -f "Makefile.$kind" CFLAGS="-std=c23 -Wall -Wextra -g -fsanitize=address$([ $kind = fixed ] && printf ' -MMD -MP')" >/dev/null 2>&1
    out=$(./demo 2>&1 | head -3 || true)
    printf '   헤더를 넓힌 뒤: %s\n' "$(printf '%s' "$out" | head -1)"
    printf '%s' "$out" | grep -q 'stack-buffer-overflow' && printf '   → ASan: stack-buffer-overflow\n' || true

    sed -i 's/#define GREET_MAX 32/#define GREET_MAX 16/' greet.h
    make -s -f "Makefile.$kind" clean >/dev/null
done

== Makefile.broken
   처음        :   GREET_MAX=16  len=15
   헤더를 넓힌 뒤: =================================================================
   → ASan: stack-buffer-overflow
== Makefile.fixed
   처음        :   GREET_MAX=16  len=15
   헤더를 넓힌 뒤:   GREET_MAX=32  len=31

무엇이 벌어졌는지 뜯어본다. 헤더에 그릇의 크기가 있다.

#define GREET_MAX 16
void greet(char *out);

greet.c 는 그 수만큼 채우고, main.c 는 그 수만큼 그릇을 잡는다. 두 파일이 같은 수를 믿는다. 그런데 Makefile.broken 의 규칙은 이렇게만 적혀 있다.

%.o: %.c
  $(CC) $(CFLAGS) -c -o $@ $<

여기 어디에도 「이 목적 파일은 greet.h 에도 딸려 있다」는 말이 없다. 그래서 헤더를 16 에서 32 로 넓히고 greet.c 만 손대면, make 는 greet.o 만 다시 만든다. 새 greet 는 31 글자와 끝의 NUL 까지 32 바이트를 쓰는데, 옛 main.o 는 여전히 16 바이트짜리 그릇을 잡는다.

★ 결과는 느림이 아니라 스택 버퍼 넘침이다. 시연이 새니타이저(18장) 아래에서 그것을 그 자리에서 잡아 준다. 잡히지 않았다면 이 프로그램은 「가끔 이상한 값이 나오는」 물건이 되었을 것이다.

CFLAGS = ... -MMD -MP
-include main.d greet.d

102.2 파일을 어떻게 나누는가 — 헤더는 계약, 소스는 사정#

파일을 나누는 기준은 「길어서」가 아니다. 함께 바뀌는 것끼리 모으고, 따로 바뀌는 것을 가른다가 기준이다. 함께 바뀌는 것을 갈라 두면 고칠 때마다 여러 파일을 오가야 하고, 따로 바뀌는 것을 붙여 두면 한쪽 때문에 다른 쪽이 자꾸 다시 만들어진다.

그 위에 C 만의 사정이 하나 얹힌다 — 헤더는 계약이고 소스는 사정이다 (53장). 헤더에 적힌 것은 부르는 쪽이 기대는 약속이고, 소스에 있는 것은 그 약속을 지키는 방법이다. 방법은 바꿔도 되지만 약속을 바꾸면 남이 깨진다.

★ 마지막 줄에는 널리 쓰이는 예외가 하나 있다. 아주 짧은 함수를 헤더에 두고 싶을 때 static inline 으로 적는 관행이다(C99 부터). 사본이 생기는 것은 같지만 컴파일러가 대개 펼쳐 넣고, 쓰이지 않아도 경고가 나지 않는다. 그래도 그 함수의 몸이 헤더에 드러난다는 사실은 남으므로, 고칠 여지가 있는 것은 여전히 소스에 둔다.

★ 세 번째 줄이 규모에서 가장 비싸다. 헤더에 struct 의 멤버를 적어 두면 그 배치가 공개 약속이 되어, 멤버 하나를 늘리는 일이 부르는 쪽 전부를 다시 만드는 일이 된다. 그래서 큰 프로젝트는 자주 이름만 내놓고 속은 감춘다.

/* 헤더: 이름만 있고 속이 없다 */
typedef struct config config;
config *config_open(const char *path);
int     config_get_int(const config *c, const char *key, int fallback);
void    config_close(config *);

부르는 쪽은 config 가 몇 바이트인지 모른다. 그래서 알 필요도 없고, 바뀌어도 안 깨진다. 대가는 값으로 못 쓰고 포인터로만 다뤄야 한다는 것이다.

102.3 공개와 내부의 경계#

프로젝트가 커지면 헤더도 두 갈래가 된다 — 밖에 내놓는 것과 안에서만 쓰는 것이다. 이 경계를 파일 배치로 못박은 대표 사례가 리눅스 커널이다. 커널은 사용자 공간에 나가는 선언을 include/uapi/ 로 갈라내고, 안쪽 헤더가 그것을 포함하는 구조로 바꾸었다. 갈라낸 까닭은 두 가지로 알려져 있다 — 헤더끼리의 얽힘을 줄이는 것, 그리고 무엇이 공개 약속인지 눈으로 분명해지는 것이다.

102.4 폴더 구조 — 관행은 무엇을 위한 것인가#

프로젝트마다 이름은 조금씩 다르지만 갈래는 대개 같다. 외울 목록이 아니라 각각이 무엇을 위한 것인지를 보는 것이 요점이다.

★ build/ 를 따로 두는 것이 생각보다 크게 남는 장사다. 산출물이 소스 옆에 흩어져 있으면 「지금 이 .o 가 어느 설정으로 만들어진 것인가」를 아무도 모르고, 설정을 바꿔 가며 빌드할 수도 없다. 자리를 나누면 build/debug 와 build/release 가 나란히 살 수 있다.

102.5 시험의 갈래 — 각각 무엇을 잡는가#

「시험을 짠다」는 한 가지 일이 아니다. 갈래마다 잡는 사고가 다르다.

이 책이 이미 그중 둘을 보였다. 18장의 새니타이저는 퍼즈와 짝이고, 92장에서 본 「실패하는 껍데기」는 단위 시험이 잘 안 도는 경로를 일부러 밟게 하는 기법이다.

102.6 골든 시험 — 정답을 파일로 굳힌다#

갈래 가운데 규모가 커질수록 가장 크게 보답하는 것이 골든이다. 출력이 있는 프로그램이라면 거의 공짜로 세울 수 있기 때문이다. 입력을 파일로 두고, 지금 옳다고 확인한 출력을 정답 파일로 굳혀 두고, 다음부터는 기계가 diff 로 견준다.

PostgreSQL 이 이 방식을 크게 쓴다. src/test/regress/ 아래에 입력을 담은 sql/, 정답을 담은 expected/, 이번 결과가 쌓이는 results/ 를 두고, 어긋난 것을 regression.diffs 에 남긴다. 견주는 도구는 특별한 것이 아니라 그냥 diff 다.

같은 것을 열 몇 줄로 세울 수 있다.

#!/bin/sh
# 골든 시험 --- 정답을 파일로 굳혀 두고 기계가 견준다.
#   in/X.txt 를 먹여 나온 것을 expected/X.txt 와 diff 로 맞대어 본다.
#   --accept 를 주면 지금 결과를 정답으로 굳힌다(처음 한 번, 그리고 *의도한* 변경 뒤).
set -eu
cd "$(dirname "$0")"
cc -std=c23 -Wall -Wextra -o wordcount wordcount.c
mkdir -p results
fail=0 n=0
for input in in/*.txt; do
    name=$(basename "$input" .txt)
    ./wordcount < "$input" > "results/$name.txt"
    n=$((n + 1))
    if [ "${1:-}" = "--accept" ]; then
        cp "results/$name.txt" "expected/$name.txt"
        continue
    fi
    if ! diff -u "expected/$name.txt" "results/$name.txt" > "results/$name.diff"; then
        printf '  ✗ %s\n' "$name"
        sed -n '3,6p' "results/$name.diff" | sed 's/^/      /'
        fail=$((fail + 1))
    else
        printf '  ✓ %s\n' "$name"
        rm -f "results/$name.diff"
    fi
done
[ "${1:-}" = "--accept" ] && { printf '정답 %d 개를 굳혔다\n' "$n"; exit 0; }
[ "$fail" -eq 0 ] && printf '골든 %d 개 통과\n' "$n" || { printf '어긋남 %d 개\n' "$fail"; exit 1; }

  ✓ empty
  ✓ spaces
  ✓ two-lines
골든 3 개 통과

이렇게 굳혀 둔 입력과 정답을 픽스처라 부른다 — 시험이 딛고 서는 준비물이다. 그 성질과 함정은 103장에서 따로 본다.

세 가지를 눈여겨본다.

1. 정답은 손으로 적지 않는다. --accept 로 지금 결과를 굳힌다. 손으로 적으면 틀리고, 틀린 정답은 시험을 거꾸로 만든다.
2. 실패는 어긋난 줄만 보여 준다. diff 가 그 일을 이미 한다.
3. 그래서 이 시험은 「무엇이 옳은가」를 모르는 채로도 쓸모가 있다 — 어제와 달라졌는가를 묻기 때문이다.

102.7 얼마나, 그리고 무엇을 시험하지 않는가#

「얼마나 시험해야 하는가」에 답이 있는가. 상한을 보여 주는 사례가 하나 있다.

SQLite 는 자기 시험 문서에서 수를 밝힌다¹ — 3.42.0(2023년 5월) 기준으로 라이브러리 본체가 약 155.8 KSLOC 인데 시험 코드와 스크립트는 92,053.1 KSLOC, 곧 본체의 590배 라고 적는다. 시험을 돌리는 틀 — 하네스 — 도 하나가 아니라 넷이고(TCL 시험, TH3, SQL Logic Test, 그리고 dbsqlfuzz), 기본 구성의 핵심 부분에 대해 TH3 아래에서 분기 커버리지 100% 를 유지한다고 밝힌다 — 「라이브러리 전체가 언제나」가 아니라는 단서가 원문에 붙어 있다.

★ 여기서 배울 것은 「590배를 따라 하라」가 아니다. 두 가지다.

1. 틀을 여럿 두는 까닭 — 한 방식이 눈감는 자리를 다른 방식이 본다. 같은 생각으로 짠 시험 백 개보다 다르게 짠 시험 열 개가 낫다.
2. 시험의 양은 목적이 아니라 결과다 — SQLite 가 그만큼 시험하는 것은 그것이 「어디서나 도는 데이터베이스」를 표방하기 때문이다. 목표가 다르면 답도 다르다.

그리고 반대편 물음이 더 중요하다.

102.8 협업 — 기계가 막는 것과 사람이 보는 것#

여럿이 일하기 시작하면 물음이 하나 늘어난다. 어긋난 것을 누가 막는가.

답은 둘로 나뉜다. 기계가 막는 것(게이트) 과 사람이 보는 것(리뷰) 이다. 이 둘을 섞으면 양쪽 다 나빠진다 — 기계가 셀 수 있는 것을 사람에게 시키면 사람이 지치고, 사람이 판단할 것을 기계에 맡기면 규칙이 엉뚱한 것을 막는다.

102.9 적어 두어야 하는 것#

마지막으로, 남이 들어올 자리를 만드는 일이다. 문서는 많을수록 좋은 것이 아니라 각각이 다른 물음에 답할 때 쓸모가 있다.

★ 마지막 줄이 가장 자주 빠지고 가장 비싸다. 몇 달 뒤 그 결정을 되돌리려는 사람은 무엇을 견주어 그렇게 정했는지 모르므로, 이미 검토하고 버린 길을 다시 걷는다.

여기까지가 무엇을 어디에 둘 것인가다. 다음 장은 그 위에서 어떻게 일할 것인가를 본다 — 여럿이 굴릴 때 쓰는 어휘와 절차, 그리고 검사가 정말 무는지 확인하는 법이다.