패키지 매니저

Vais는 vaisc CLI에 통합된 강력한 패키지 매니저를 제공합니다. 의존성 관리, 버전 해결, 워크스페이스 지원 등 현대적인 언어 생태계에 필요한 모든 기능을 갖추고 있습니다.

개요

Vais 패키지 매니저는 다음 기능을 제공합니다:

프로젝트 초기화 (vais init) — 새 프로젝트 생성
의존성 설치 (vais install) — path/레지스트리 의존성 자동 해결
패키지 배포 (vais publish) — 레지스트리에 패키지 게시
SemVer 관리 — caret/tilde 버전 범위, 충돌 감지
워크스페이스 — 멀티 크레이트 프로젝트 지원
Lockfile — 재현 가능한 빌드 보장
문서 생성 — Markdown/HTML 자동 생성

패키지 레지스트리는 Axum과 SQLite 기반으로 구현되어 있습니다.

프로젝트 생성

새 프로젝트 초기화

# 바이너리 프로젝트 생성
vais init my-app

# 라이브러리 프로젝트 생성
vais init my-lib --template lib

# 현재 디렉토리에 초기화
vais init

디렉토리 구조

프로젝트 초기화 후 다음과 같은 구조가 생성됩니다:

my-app/
├── Vais.toml          # 매니페스트 파일
├── src/
│   └── main.vais      # 진입점 (바이너리)
│   └── lib.vais       # 진입점 (라이브러리)
└── .gitignore         # Git 무시 파일

Vais.toml 매니페스트

프로젝트 설정은 Vais.toml 파일에 정의됩니다:

[package]
name = "my-app"
version = "0.1.0"
authors = ["Your Name <your@email.com>"]
edition = "2024"
description = "A Vais application"
license = "MIT"
repository = "https://github.com/username/my-app"

[dependencies]
# 의존성 목록

[dev-dependencies]
# 개발 전용 의존성

[[bin]]
name = "my-app"
path = "src/main.vais"

[lib]
name = "my-lib"
path = "src/lib.vais"

템플릿

두 가지 템플릿을 제공합니다:

bin (기본값) — 실행 가능한 바이너리 프로젝트
lib — 라이브러리 프로젝트

라이브러리는 다른 프로젝트에서 의존성으로 사용할 수 있습니다.

의존성 관리

의존성 추가

Vais.toml의 [dependencies] 섹션에 의존성을 추가합니다:

[dependencies]
# 레지스트리 의존성 (SemVer 버전)
vais-json = "0.1.0"
vais-regex = "^0.2.0"  # >= 0.2.0, < 0.3.0
vais-uuid = "~0.1.5"   # >= 0.1.5, < 0.2.0

# path 의존성 (로컬 개발)
my-utils = { path = "../my-utils" }

# Git 의존성
vais-http = { git = "https://github.com/vaislang/vais-http", branch = "main" }

SemVer 버전 관리

Vais는 Semantic Versioning 2.0을 따릅니다:

정확한 버전: "0.1.0" — 정확히 0.1.0
Caret 요구사항: "^0.1.0" — >= 0.1.0, < 0.2.0 (major 0일 때는 minor 고정)
Tilde 요구사항: "~0.1.5" — >= 0.1.5, < 0.2.0 (patch만 업데이트)
와일드카드: "0.1.*" — 0.1.x의 모든 버전

Path 의존성

로컬 개발 시 path 의존성을 사용합니다:

[dependencies]
shared = { path = "../shared" }

이는 monorepo 환경이나 워크스페이스에서 유용합니다.

패키지 설치

의존성 설치

# Vais.toml의 모든 의존성 설치
vais install

# 특정 패키지 추가 및 설치
vais install vais-json

# 개발 의존성 포함 설치
vais install --dev

의존성 해결 알고리즘

Vais 패키지 매니저는 다음 알고리즘을 사용합니다:

전이적 의존성 수집 — 모든 직간접 의존성 탐색
SemVer 제약 해결 — 버전 범위 충돌 감지 및 해결
다이아몬드 의존성 처리 — 공통 의존성의 최적 버전 선택

예시:

my-app
├── pkg-a ^1.2.0
│   └── pkg-c ^2.0.0
└── pkg-b ~1.5.0
    └── pkg-c ~2.3.0

이 경우 pkg-c의 버전은 2.3.x 범위에서 선택됩니다 (두 제약 모두 만족).

충돌 감지

호환되지 않는 버전 요구사항이 있을 경우 컴파일 에러가 발생합니다:

Error: Version conflict detected
  pkg-a requires pkg-c ^2.0.0
  pkg-b requires pkg-c ^3.0.0
  No version satisfies both constraints

Lockfile

Vais.lock 파일

vais install 실행 시 Vais.lock 파일이 생성됩니다:

# This file is automatically generated by Vais package manager.
# Do not edit manually.

[[package]]
name = "vais-json"
version = "0.1.2"
source = "registry+https://registry.vaislang.org"
checksum = "a3f2b..."

[[package]]
name = "my-utils"
version = "0.1.0"
source = "path+../my-utils"

[[package]]
name = "my-app"
version = "0.1.0"
dependencies = [
    "vais-json 0.1.2",
    "my-utils 0.1.0"
]

결정적 직렬화

Lockfile은 다음을 보장합니다:

재현 가능한 빌드 — 동일한 의존성 버전으로 빌드
체크섬 검증 — 패키지 무결성 확인
알파벳 순 정렬 — Git diff 친화적

버전 관리

Lockfile은 반드시 버전 관리에 포함시켜야 합니다:

git add Vais.lock
git commit -m "Update dependencies"

워크스페이스

멀티 크레이트 프로젝트

여러 패키지를 하나의 저장소에서 관리할 수 있습니다:

my-workspace/
├── Vais.toml          # 워크스페이스 루트
├── app/
│   ├── Vais.toml
│   └── src/main.vais
├── lib/
│   ├── Vais.toml
│   └── src/lib.vais
└── utils/
    ├── Vais.toml
    └── src/lib.vais

워크스페이스 설정

루트 Vais.toml에 워크스페이스 정의:

[workspace]
members = [
    "app",
    "lib",
    "utils"
]

# 공통 의존성 (모든 멤버에 적용)
[workspace.dependencies]
vais-json = "0.1.0"

멤버 간 의존성

워크스페이스 멤버는 서로를 path 의존성으로 사용할 수 있습니다:

# app/Vais.toml
[dependencies]
lib = { path = "../lib" }
utils = { path = "../utils" }

워크스페이스 빌드

# 모든 멤버 빌드
vais build --workspace

# 특정 멤버만 빌드
vais build -p app

# 모든 멤버 테스트
vais test --workspace

패키지 배포

레지스트리 계정 설정

패키지를 배포하려면 레지스트리 계정이 필요합니다:

# 레지스트리 로그인
vais login

# API 토큰 설정
vais config set registry.token <YOUR_TOKEN>

배포 절차

# 배포 전 검증
vais publish --dry-run

# 패키지 배포
vais publish

배포 시 다음 검증이 수행됩니다:

Vais.toml 필수 필드 확인 (name, version, description, license)
테스트 실행 (cargo test)
문서 생성 확인

배포 요청 구조

vais publish는 다음 형식으로 패키지를 아카이브합니다:

{
  "name": "my-package",
  "version": "0.1.0",
  "description": "My Vais package",
  "tarball": "<base64-encoded .tar.gz>"
}

버전 관리 모범 사례

Breaking changes — major 버전 증가 (1.0.0 → 2.0.0)
New features — minor 버전 증가 (1.0.0 → 1.1.0)
Bug fixes — patch 버전 증가 (1.0.0 → 1.0.1)
0.x.y 버전 — 불안정 API, 언제든 변경 가능

문서 생성

Markdown 문서

소스 코드에서 자동으로 문서를 생성합니다:

# Markdown 문서 생성
vais doc --format markdown

# HTML 문서 생성 (기본값)
vais doc

# 출력 디렉토리 지정
vais doc --output ./docs

문서화 주석

Vais는 특수 주석으로 문서를 작성합니다:

# Adds two numbers together.
#
# ## Arguments
# - `a` — first operand
# - `b` — second operand
#
# ## Returns
# The sum of a and b
#
# ## Example
# ```vais
# result := add(5, 3)
# # result == 8
# ```
P F add(a: i64, b: i64) -> i64 {
    R a + b
}

생성된 문서는 함수 시그니처, 설명, 예제를 포함합니다.

HTML 문서

HTML 문서는 다음 구조로 생성됩니다:

target/doc/
├── index.html
├── my-package/
│   ├── index.html
│   ├── fn.add.html
│   └── struct.MyStruct.html
└── static/
    ├── main.css
    └── main.js

공식 패키지

Vais 생태계는 다음 공식 패키지를 제공합니다:

데이터 형식

vais-json — JSON 파싱 및 직렬화
vais-csv — CSV 파싱 및 생성

암호화 및 해싱

vais-aes — AES-256 암호화 (ECB/CBC/CTR 모드)
vais-sha256 — SHA-256 해싱 (FIPS 180-4)
vais-crc32 — CRC32 체크섬

압축

vais-lz4 — LZ4 압축 및 해제

인코딩

vais-base64 — Base64 인코딩/디코딩
vais-uuid — UUID 생성 및 파싱

텍스트 처리

vais-regex — 정규 표현식 매칭

사용 예시

[dependencies]
vais-json = "0.1.0"
vais-regex = "0.1.0"
vais-uuid = "0.1.0"

U json::{parse, stringify}
U uuid::v4

F main() {
    # JSON 파싱
    data := parse(~{"name": "Vais", "version": 1})!

    # UUID 생성
    id := v4()
    println(~"Generated UUID: {id}")
}

추가 명령어

패키지 검색

# 레지스트리에서 패키지 검색
vais search json

# 카테고리로 필터링
vais search --category crypto

보안 감사

# 의존성 보안 취약점 검사
vais audit

# 자세한 보고서 출력
vais audit --verbose

캐시 관리

# 캐시 상태 확인
vais cache info

# 캐시 정리
vais cache clean

# 특정 패키지 캐시 제거
vais cache remove vais-json

의존성 트리

# 전체 의존성 트리 표시
vais tree

# 특정 패키지의 의존성 추적
vais tree --package vais-json

# 중복 의존성 표시
vais tree --duplicates

벤더링

# 모든 의존성을 vendor/ 디렉토리에 복사
vais vendor

# 오프라인 빌드를 위한 벤더링
vais vendor --sync

벤더링은 오프라인 환경이나 빌드 재현성이 중요한 경우에 유용합니다. vendor/ 디렉토리를 버전 관리에 포함하면 네트워크 없이도 빌드가 가능합니다.

트러블슈팅

의존성 해결 실패

Error: Could not resolve dependencies
  Conflicting versions for pkg-x

해결책: Vais.toml에서 버전 제약을 완화하거나 Vais.lock 삭제 후 재설치

Lockfile 불일치

Error: Vais.lock is out of sync with Vais.toml

해결책:

rm Vais.lock
vais install

레지스트리 연결 실패

Error: Failed to connect to registry

해결책: 네트워크 연결 확인 또는 프록시 설정

vais config set http.proxy http://proxy.example.com:8080

추가 정보

표준 라이브러리 — 내장 모듈 목록
에코시스템 패키지 — 서드파티 패키지
패키지 레지스트리 — 공식 레지스트리

Vais Programming Language