0.5. 표준 라이브러리 계층
표준 라이브러리는 가상 네임스페이스 rok::* 아래 세 개의 패키지 계층으로 나뉩니다. 사용 가능한 환경과 노출하는 동작의 위험도를 기준으로 구분합니다.
0.5.1. 세 계층
먼저 전체 구조는 다음과 같습니다.
rok::bare ← 안전 보장 없음. 원시 메모리·FFI·전송 가능 비트 캐스팅·MLIR 직접 접근.
↑
rok::core ← 모든 타깃에서 사용 가능한 안전 foundation. 내부적으로는 rok::bare 를 쓴다.
↑
rok::std ← 타깃 종속 계층. 파일 시스템·네트워크·OS 스레드 등.
여기서 화살표는 의존 방향을 나타냅니다. rok::core 는 rok::bare 를 내부 구현에 사용할 수 있고, rok::std 는 rok::core 와 rok::bare 를 모두 사용할 수 있습니다. 다만 그 반대 방향의 의존은 금지됩니다.
세 계층 모두 가상 네임스페이스 rok:: 아래에 자리 잡습니다 (5.7.4 rok::). rok 자체는 path 루트 컨텍스트 키워드 (1.5.4) 이며, 사용자 식별자와 충돌하지 않습니다.
0.5.2. 각 계층의 책임
rok::bare
rok::bare 는 저수준이며 위험한 영역입니다. 컴파일러가 안전성을 보증할 수 없는 동작이 이곳에 모이게 되는데, 대표적으로 다음과 같은 항목들이 포함됩니다. 우선 원시 포인터 형태(raw pointer 추상) 가 있고, 임의 비트 캐스팅(transmute 류) 도 여기에 속합니다. 또한 핀(pinning) 과 volatile 메모리 접근, 그리고 C ABI 호환 메모리 할당의 원형 역시 rok::bare 의 영역입니다. MLIR 다이얼렉트 직접 호출 (rok::bare::mlir) 과 사용자 정의 다이얼렉트 plugin 등록 (rok::bare::mlir::plugin) 도 이 계층에 자리하여, 외부 텐서 / SIMD / GPU 라이브러리가 가속 영역에 접근하는 통로로 쓰입니다.
이 계층의 함수를 호출하는 쪽이 안전성을 책임지게 되며, 경로 자체가 그 사실을 분명하게 알려 줍니다.
rok::core (foundation)
rok::core 영역은 가장 자주 쓰이는 안전한 라이브러리이며, foundation 의 모든 모듈이 이곳에 자리 잡습니다 (예: rok::core::vec, rok::core::iter, rok::core::ops). 본 사양이 보증하는 모든 빌드 타깃에서 동일하게 사용 가능해야 합니다. 포함되는 항목은 매우 폭넓은데, 숫자, 문자, 문자열 타입과 메서드를 비롯하여 컬렉션(리스트, 맵, 셋, 튜플) 이 들어 있습니다. 그리고 산술, 비교, 논리, 비트 연산자의 트레잇 정의가 있으며, 반복자, 스트림, 미래값도 함께 제공됩니다. 동시성 프리미티브(atomic, mutex, channel) 와 태스크, 병렬 실행의 API 표면 역시 이 계층에 속합니다. 마지막으로 형식화, 표시, 디버그와 리플렉션, 인스펙션까지 포괄합니다.
텐서 / 자동 미분 / SIMD / GPU 같은 가속 영역은 rok::core 에 포함되지 않으며, 외부 라이브러리가 rok::bare::mlir 위에서 직접 구현합니다. 표준 라이브러리는 일반 코드의 표면 의미만 책임지고, 가속 영역은 라이브러리 layer 의 결정에 맡깁니다.
rok::core 의 항목은 컴파일러가 모든 rok 소스 시작 시점에 묵시적으로 use rok::core::**; 를 적용해 가시화합니다. 즉 rok::core::vec::Vec 을 그냥 Vec 으로 쓸 수 있다는 뜻입니다. 별도의 prelude 모듈을 두지 않으며, 묵시 recursive glob 자체가 그 역할을 수행합니다.
rok::core 의 항목은 기본적으로 pub 입니다. 외부 패키지에 노출되는 표면이 곧 자동 가시 표면이기 때문에, 별도의 단계가 필요하지 않습니다.
rok::std
rok::std 는 특정 환경(주로 OS 위) 에서만 의미가 있는 영역입니다. 여기에는 파일 시스템과 네트워크가 들어 있고, 시간과 시계, 표준 입출력, 환경 변수, 프로세스 그리고 OS 스레드 직접 제어와 같은 기능들이 포함됩니다.
rok::std 의 함수는 타깃에 따라 존재하지 않을 수도 있습니다. 일부 영역이 의미를 가지지 않는 환경(예를 들어 브라우저 안에서 동작하는 노트북 커널) 에서는 해당 모듈이 빌드되지 않습니다.
0.5.3. 가시 규약
가시성 규칙은 다음과 같습니다.
| 영역 | 묵시 import | 명시 import 필요 | 비고 |
|---|---|---|---|
rok::core::** | ✓ 자동 | ✗ 불필요 | use rok::core::**; 자동 적용 |
rok::bare::** | ✗ | ✓ 필요 | 위험 시그널을 코드에 보이도록 |
rok::std::** | ✗ | ✓ 필요 | 타깃 의존성이 코드에 드러나도록 |
| 사용자 패키지 | ✗ | ✓ 필요 | 다른 패키지의 항목 |
"끌어옴" 의 구체 구문(use, import 등) 은 모듈 시스템 사양에서 정의합니다.
0.5.4. 제공 형태와 링크 메커니즘
세 계층은 컴파일러가 함께 배포하는 사전 빌드된 정적 아카이브 형태로 제공됩니다.
librok_bare.a (-NL bare)
librok_core.a (-NL core)
librok_std.a (-NL std)
각 archive 는 별도의 패키지 ABI 를 가지며, 컴파일러가 빌드 시점에 -NL <name> 메커니즘으로 자동 링크합니다. 사용자 패키지의 일반 의존성과는 분리된 경로이며, 이는 사용자 패키지가 우연히 같은 이름 (예: mod bare, mod std) 을 가져도 충돌하지 않게 합니다.
세 archive 는 컴파일러 자체와 마찬가지로 의존성 0 원칙을 따르고 있습니다. 따라서 사용자 패키지를 빌드하면 필요한 계층만 링크되며, 결과 산출물은 추가 외부 라이브러리를 요구하지 않습니다.
0.5.5. 세 계층으로 나눈 이유
마지막으로 왜 세 계층으로 나누었는지 설명합니다. 만약 2 계층(안전, 위험)으로만 구분한다면 "어디서나 쓸 수 있는 안전" 과 "OS 가 있어야만 쓸 수 있는 안전" 을 구분하지 못하게 되며, OS 의 일부 기능이 없는 환경(브라우저 노트북 등) 에서 무너지고 맙니다. 반대로 4 계층 이상은 사용자가 외워야 할 규칙을 늘리고, 모듈 경계의 가치를 떨어뜨리게 됩니다.
3 계층은 현장에서 충분히 검증된 구분이며, 가장 단순하면서도 유의미한 분할입니다.
가상 네임스페이스 rok:: 아래에 모두 묶인 형태는 학습 비용을 더 낮춰 줍니다. 사용자는 "표준 라이브러리는 모두 rok:: 아래" 라는 한 줄 규칙만 기억하면 되며, 그 안에서 bare / core / std 의 책임 구분을 점진적으로 익히게 됩니다.