패키지 모드는 언어에 새 문법을 추가하지 않고 기존 Topaz 모듈에 루트, 의존성, 잠금 파일, 오프라인 입력을 결합합니다.
기본 규칙
topaz.toml은 패키지 이름, 언어 버전, 진입점, 의존성을 선언합니다. topaz.lock은 선택된 의존성과 무결성 정보를 고정합니다. 로컬 의존성은 경로로, 레지스트리 의존성은 vendor/<name>/<version>에 복사된 내용으로 해석됩니다.
사용 방법
topaz init으로 패키지를 만들고, add로 의존성을 추가하고, lock으로 잠금 파일을 갱신합니다. vendor는 외부 의존성을 로컬에 복사하고, --locked는 매니페스트와 잠금 파일이 다르면 작업을 멈춥니다. 진입 파일을 생략하면 패키지에 지정된 진입점을 사용합니다.
편집기에서 topaz lsp를 시작할 때 패키지 디렉터리를 initialize.rootUri로 전달하세요. 유효한 잠금 파일이 있으면 LSP 진단도 topaz check와 같은 패키지 그래프로 로컬 모듈과 벤더링된 의존성을 해석하며, 열어 둔 문서의 내용은 디스크에 저장된 파일보다 우선합니다.
Topaz 5.7.0에는 topaz init --target web-app이 포함되고, [build].target이 패키지 빌드의 실제 기본값이 됩니다. 엄격한 [web] 표에는 title, 정규화된 styles/*.css, assets/**만 쓸 수 있습니다. 스타일시트의 CSS @import와 원격 또는 이스케이프된 url() 참조는 허용하지 않으므로, 각 스타일시트를 직접 선언하고 관련 리소스를 관리 자산으로 함께 제공해야 합니다. topaz dev는 이 패키지 대상에서만 동작하며 루프백에만 바인딩합니다.
애플리케이션 산출물에서 파일을 사용하려면 [capabilities.fs]에 허용할 루트를 선언하고, 런타임의 data 및 출력 디렉터리가 놓인 경로에서 산출물을 실행하세요. 네이티브 실행 파일과 패키지 모드 Python 빌드는 실행 시점의 작업 디렉터리를 기준으로 이 루트를 해석하므로 소스 패키지 없이 실행할 수 있습니다. Python 번들은 Python 3.11 이상이 필요하며 표준 출력·오류, 인자, 표준 입력, 명시적 main 종료 코드를 직접 애플리케이션 동작으로 제공합니다.
현재 지원
Topaz v5.7은 패키지 생성, 의존성 추가, 잠금, 벤더링, 오프라인 검사·실행·빌드를 지원합니다. 공개 topaz-lang@5.7.0 패키지는 현재 플랫폼에 맞는 Topaz CLI를 설치하며, Topaz 소스 의존성 형식과는 별개입니다.
제한 사항
패키지 모드는 모듈의 가시성, 순환 참조, 초기화 규칙을 완화하지 않습니다. 네트워크에서 자동으로 의존성을 가져오거나 신뢰하지 않으며, 오프라인 빌드는 필요한 파일이 미리 보존되어 있을 때만 성공합니다.
topaz emit --target python은 계속 소스 검사와 trace 통합을 위한 경계입니다. 물리 파일 시스템을 사용하는 애플리케이션 번들이 필요하면 패키지 모드에서 topaz build --target python을 사용하세요.
명령 예시
topaz init --root my-app
topaz add utility@1.2.0 --root my-app
topaz lock --root my-app
topaz vendor --root my-app --from ./registry
topaz check --root my-app --locked
topaz build --root my-app --locked --out-dir ./dist/native
topaz build --target python --root my-app --locked --out-dir ./dist/python