행 태그와 메타 태그 — 빌드마다 빼는 행, 그리고 임의 메타
테스트 행 · 작업 중인 행 · 특정 빌드용 행을 시트를 나누지 않고 산출에서 빼는 것과, 선언에
임의 key=value를 달아 두는 것에 대한 설계입니다.
지금 산출에서 무엇을 뺄지 정하는 수단은 셋이고 단위가 서로 다릅니다 — 시트는
IncludeSheets, 엔티티와 컬럼은 TargetSide, 컬럼은 필드명 앞의 #입니다. 행 단위는
없습니다. 빼려면 시트를 나눠야 하고, 나누면 스키마가 두 벌이 됩니다 —
행 벌이 이미 기재한 문제입니다.
로드맵의 항목이고, 조사는 기능 대조 §5.1에 있습니다.
이 문서의 「태그」는 와이어 태그가 아닙니다. 같은 낱말이 셋을 가리키고 있으므로 여기서는 언제나 앞의 낱말을 붙여 적습니다.
이름 무엇 어디 행 태그 그 행을 빌드마다 뺄지 정하는 낱말 마커 열 메타 태그 누가 읽을지 이 도구가 정하지 않는 key=value선언과 컬럼의 tag=와이어 태그 컬럼의 식별자. 형식이 바뀌어도 읽는 쪽이 밀리지 않게 하는 번호 필드 이름의 @N— 스키마가 바뀔 때앞의 둘이 이 문서이고, 셋째는 이름이 겹칠 뿐 관계가 없습니다.
1. 규칙 하나
제외된 행은 시트에 없던 행입니다.
레이아웃 파서가 그 행을 내보내지 않으면 끝이고, 그 아래는 격자만 보므로 특별 처리가 없습니다.
지금 마커 열의 #를 건너뛰는 자리가 이미 그것입니다.
따라오는 것들이 전부 이 규칙에서 나옵니다.
| 무엇 | 동작 |
|---|---|
| 제외된 행을 가리키는 참조 | 깨진 참조로 보고됩니다. 손으로 지웠을 때와 같고, 그 보고는 옳습니다 — 그 참조는 산출된 데이터에서 실제로 끊겨 있습니다 |
| 제외된 행이 원인이던 키 중복 | 사라집니다. 손으로 지웠을 때와 같습니다 |
.tcb의 인코딩과 크기 | 값 분포가 달라지므로 함께 달라집니다. 인코딩은 파일이 말하므로 리더는 그대로입니다 |
| 매니페스트 | 크기와 해시가 달라집니다 |
| 히스토리 | 태그 선택이 다르면 다른 산출물이고 계열도 다릅니다. 한 계열에 태그를 바꿔 가며 넣는 것은 잘못된 사용이고, 코드가 막을 것이 아닙니다 |
2. 적용 범위 — 거르는 것은 테이블의 데이터 행만
:enum과 :const은 행이 곧 생성 코드입니다(§8.4 · §8.5).
거기서 행을 빼면 태그 선택마다 타입 선언이 달라져, 이 기능의 성질인 「코드는 한 벌,
데이터만 여러 벌」이 없어집니다.
| 엔티티 | 태그를 적는 것 | 그 행이 빠지는 것 |
|---|---|---|
:table | 됩니다 | 됩니다 |
:enum · :const | 됩니다 — 읽어서 담습니다 | 안 됩니다 |
적는 것까지 막지는 않습니다. 마커 열의 낱말은 어디에 적혔든 태그이고, 그 라벨을 읽지도 않는 이 레이아웃이 거기서만 거부할 근거가 없습니다. 담기고, 요약에도 나오고, 거르는 데만 쓰이지 않습니다.
3. 적는 자리 — 마커 열
주 레이아웃의 마커 열은 엔티티의 세로 범위 전체에서 예약되어 있고, 담을 수 있는 것이 정해져 있습니다(§3.1). 거기에 한 줄이 붙습니다.
| 마커 열의 셀 | 뜻 |
|---|---|
| 빈 칸 | 데이터 행 |
# (또는 //) | 그 행을 언제나 제외 |
| 태그 | 선택되었을 때만 제외. key 또는 key=value, 쉼표로 여러 개 |
#와 태그는 자리를 공유하되 뜻이 다릅니다.#는 영구 제외이고 태그는 조건부입니다.- 레코드 첫 행이면 연장 행까지 레코드 전체, 연장 행이면 그 행의 원소들만 —
#의 규칙을 그대로 따릅니다(§7). - 이름 기반 레이아웃은 1차에서 지원하지 않습니다. 그 레이아웃에는 마커 열이 없고, 적는 자리를 새로 만드는 것은 이 기능이 요구하는 값보다 큽니다. 레이아웃이 자기 자리를 정하는 구조이므로 나중에 그 레이아웃 파일 안에서 더할 수 있습니다.
4. 행 태그의 보유와 선택
행 태그 이름을 선언하지 않습니다. 마커 열에 적힌 낱말은 그대로 그 행의 태그 집합이 되어
모델에 담깁니다 — 컬럼의 tags=(§6)와 같은 취급입니다. 무엇에 쓸지는 담은 다음에 정합니다.
마커 열의 값은 이렇게 갈립니다.
| 적힌 것 | 판정 |
|---|---|
:로 시작 | 헤더 행 키. 미지의 :key는 여전히 오류입니다 |
# · // | 영구 제외 |
| 그 밖 | 그 행의 태그. key=value 쌍이고 쉼표로 여러 개입니다. =가 없으면 값이 빈 키입니다 |
#로 시작하고 뒤가 더 있으면 오류입니다. #wip은 이름이 #wip인 태그로 읽히고,
그 이름을 부르는 레시피는 없으므로 빼려던 행이 그대로 나갑니다. # 하나로 빼거나 wip
하나로 태그를 다는 것 중 무엇인지 가려야 하는 자리입니다.
태그는 어디서나 같은 모양이고 대소문자를 가리지 않습니다 — 행의 것도 선언의 것도(§6)
key=value이고, WIP과 wip은 한 태그입니다.
오타를 검출하지 않습니다. wpi라고 적으면 이름이 wpi인 태그가 되고, 그 행은 빠지지
않습니다. 특수 목적 기능에 이름 선언을 요구하는 값보다 감수하는 쪽이 싸다고 봅니다 —
대신 변환 리포트가 이번 산출에서 본 태그 이름과 행 수를 전부 나열합니다(§5). 오타는
거기서 낯선 이름 하나로 드러납니다.
선택은 레시피에 적습니다. 한쪽만 적으면 그 키의 모든 값이, 쌍으로 적으면 그 값만 빠집니다.
"ExcludeTags": [ "wip", "stage=test" ]
| 레시피에 적은 것 | 시트의 wip | stage=test | stage=live |
|---|---|---|---|
wip | 빠집니다 | 남습니다 | 남습니다 |
stage | 남습니다 | 빠집니다 | 빠집니다 |
stage=test | 남습니다 | 빠집니다 | 남습니다 |
키를 하나 두고 값으로 갈라 쓰는 것이 이 표기의 값입니다 — stage가 여러 값을 가질 때
태그 이름을 여러 개 만들지 않아도 됩니다. 대소문자는 양쪽 다 무시합니다.
${TABBIT_ENV} 치환을 쓰면 환경마다 다르게 적을 수 있습니다. CLI 플래그로 두지 않는 이유가
둘입니다.
| 이유 | 내용 |
|---|---|
| 기록 | 어느 빌드가 무엇을 뺐는지가 명령줄이 아니라 저장소에 남습니다 |
| 빌드 캐시 | 캐시 키는 ${} 치환이 끝난 레시피에서 나오므로(BuildCache) 자동으로 잡힙니다. CLI 옵션이면 [Cache(CacheRelevance.Output)]를 빼먹었을 때 지난 산출물을 그대로 재사용하고 오류 없이 끝납니다 |
5. 보고
위험을 감수하고 쓰는 기능이므로 무엇을 감수했는지는 보여야 합니다. 본 태그를 전부
남기고, 각각 몇 행에 붙었는지와 그중 몇 행이 빠졌는지 적습니다. 이름을 선언하지
않으므로(§4) 오타를 알아볼 자리가 여기뿐입니다 — wpi가 1행에 붙어 0행을 뺐다고 적히면
그것이 오타입니다.
| 어디 | 무엇 |
|---|---|
| 요약 문서 | run.rowTags — 태그마다 tag · rows · omitted. 태그를 쓰지 않은 프로젝트의 요약에는 이 항목이 없습니다, 그래야 전에 쓰인 요약이 그대로 남습니다 |
| 변환 로그 | 같은 내용을 한 줄로 |
요약에 두는 이유는 그것이 다른 모든 화면이 그려 내는 문서이기 때문입니다. 로그는
지나가고, 리포트와 웹 조회는 요약을 읽습니다. run 아래인 것은 이것이 시트가 선언한 것이
아니라 이 빌드가 한 일이기 때문입니다. 그 이상은 하지 않습니다 — 아래는 전부 시끄럽게 실패하므로
따로 막지 않습니다.
| 막지 않습니다 | 무엇이 잡습니까 |
|---|---|
| 제외된 행을 가리키는 참조 | 검증 |
| 빠진 컬럼을 쓰던 소비자 코드 | 컴파일 |
6. 메타 태그 — 표기와 보존까지
선언에 임의 key=value를 답니다. 소비는 정하지 않습니다 — 무엇에 쓸지가 정해지기 전에
내보내면 되돌리기 어렵기 때문입니다.
| 어디 | 표기 |
|---|---|
| 엔티티 | :table Item(tag="owner=combat") |
| 컬럼과 struct 멤버 | 타입 괄호의 tag= — 이미 예약되어 있던 키입니다 |
tag는 STRUCT DSL이 「소비 측의 라벨」로 이미 잡아 둔 이름이고, 지금까지는 담지 않는 키로 거부되고 있었습니다. 새 표기를 만들지 않고 그것을 담는 쪽으로 바꿉니다.key=value쌍이 쉼표로 여러 개입니다.=가 없으면 값이 빈 키입니다. 그 내용은 이 도구가 읽지도 검사하지도 않습니다.- 대소문자를 가리지 않습니다 — 행 태그와 같습니다.
Owner와owner는 한 키입니다. - 행 태그와 모양은 같고 자리가 다릅니다 — 행 태그는 마 커 열, 메타는 괄호의
tag=입니다. - 1차의 범위는 읽어서 모델에 담는 것까지입니다. 산출물에 내보내지 않습니다.
- 모델의 자리 이름은
MetaTags입니다.WireTag·ReservedTags가 와이어 태그(@N)를 가리키고 있어, 같은 낱말을 그대로 쓰면 둘이 섞입니다.
7. 활용 사례
7.1 행 거르기
| 사례 | 시트에 | 레시피에 |
|---|---|---|
| 작업 중인 행 | wip | 릴리스 빌드만 "wip" |
| 테스트·디버그 데이터 | test | 라이브 빌드만 "test" |
| 미출시 콘텐츠 | season=3 | 시즌 열기 전까지 "season=3" |
| 빌드마다 갈리는 데이터 | stage=live · stage=test | 각 빌드가 반대쪽을 적습니다 |
| 플랫폼별 행 | store=ios · store=android | 각 빌드가 나머지를 적습니다 |
| 기간 한정 이벤트 | event=halloween | 기간 밖 빌드가 적습니다 |
키 하나에 값을 여럿 두는 것이 표기의 값입니다. stage를 두면 stage_live ·
stage_test처럼 이름을 늘리지 않아도 되고, 「stage가 붙은 행 전부」와 「stage=test인
행만」을 레시피에서 갈라 적을 수 있습니다.
7.2 행 벌과의 차이
stage=live · stage=test처럼 쓰면 행 벌과 겹쳐 보이지만 나오는
것이 다릅니다.
| — | 행 벌 | 태그 |
|---|---|---|
| 산출물 | 벌마다 파일 하나. Profile.tcb와 Profile_BCCN.tcb | 빌드마다 파일 하나. 그 빌드가 담은 벌만 들어 있습니다 |
| 고르는 쪽 | 읽는 프로그램이 파일을 고릅니다 | 빌드가 정하고, 실행 파일에는 고를 것이 없습니다 |
| 맞는 자리 | 한 실행 파일이 지역마다 다른 데이터를 읽을 때 | 빌드가 갈릴 때 — 릴리스와 개발, 스토어별 빌드 |
| 안 실리는 것 | 없습니다. 모든 벌이 배포에 들어갑니다 | 뺀 행은 파일에 없습니다. 미출시 콘텐츠가 여기 해당합니다 |
뺀 행은 데이터에서 사라지므로 남은 행이 그것을 가리키면 깨진 참조입니다(§1). 벌끼리 서로를 가리키는 데이터를 태그로 가르면 그 자리에서 보고됩니다 — 행 벌은 모든 벌이 파일에 있으므로 그 문제가 없습니다.
7.3 임의 메타
시트가 적고 이 도구가 읽지 않는 것들입니다. 지금은 모델에 담기는 데까지이고, 무엇에 쓸지는 담은 다음에 정합니다(§6).
| 사례 | 표기 |
|---|---|
| 담당 | :table Skill(tag="owner=combat") |
| 사내 에디터의 위젯 | int (tag="editor=slider") |
| 에디터에서 감추기 | string (tag="hidden") — 값 없는 키 |
| 외부 도구의 분류 | :enum Grade(tag="export=analytics") |
8. 들이지 않는 것
| 무엇 | 이유 |
|---|---|
unchecked — 검증만 건너뛰는 태그 | 검사받지 않은 데이터가 산출물에 실립니다. 조용히 틀리는 부류이고, 빼고 싶으면 행을 빼면 됩니다. 주 레이아웃 §10.3의 미채택 판정 그대로입니다 |
## — 태그 칸의 영구 제외 표시 | 우리는 #가 이미 그 자리에 있습니다. 한 칸에 두 일을 넣을 이유가 없습니다 |
--include-tag — 포함 목록 | Exclude 하나로 충분합니다. 포함과 제외가 함께 있으면 우선순위 규칙이 생기고, 그것을 기억해야 하는 사람이 생깁니다 |
| CLI 단독 플래그 | §4. 덧붙여 -e는 이미 --env가 쓰고 있습니다 |
9. 갱신한 문서
| 무엇 | 어디 |
|---|---|
| 마커 열이 담을 수 있는 것 | 주 레이아웃 §3.1의 표 |
| Luban 대조의 판정 | §10.3 — 「예약」에서 「채택 · 변형」으로 |
| 시트 쓰는 법 | 시트 레이아웃 — 표기 · 사례 · 행 벌과의 차이 |
| 레시피 키 | 공통 설정의 ExcludeTags |
| 요약 문서의 항목 | 요약과 히스토리의 run.rowTags |
| 행 벌과의 차이 | 행 벌 머리에 §7.2로 가는 한 줄 |