feat: GO언어 바인딩 추가 by kdyann · Pull Request #167 · dev-five-git/braillify

kdyann · 2026-06-02T06:47:54Z

braillify 라이브러리의 기능을 Go 생태계에서 사용할 수 있도록 지원하는 Go 바인딩을 추가합니다.

주요 구성

CGo 기반 구현: Rust 코어 엔진의 C ABI를 통해 Go에서 호출할 수 있도록 CGo를 사용하여 바인딩을 구현했습니다.
정적 링크 방식: 플랫폼별로 사전 빌드된 정적 라이브러리(.a)를 패키지에 포함하여, 런타임 동적 로딩 없이 컴파일
시점에 링크됩니다.
크로스 플랫폼 지원: Windows, Linux, macOS(Intel/ARM) 환경을 지원합니다.
제공 API:
- Encode(text string) ([]byte, error) — 점자 내부표기 바이트 반환
- EncodeToUnicode(text string) (string, error) — 점자 유니코드 문자열 반환
- EncodeToBrailleFont(text string) (string, error) — 점자 폰트용 유니코드 반환
스레드 안전: runtime.LockOSThread를 통한 스레드 바인딩으로 Rust 측 thread-local 에러 처리가 안전하게
동작합니다.

Package 구조

packages/go/
├── go.mod                  # Go module definition
├── braillify.go            # Public Go API
├── cgo.go                  # CGo bindings
├── braillify_test.go       # Tests
├── Cargo.toml             # Rust FFI crate configuration
├── src/
│   └── lib.rs             # Rust C-ABI wrapper
└── libs/
    ├── windows-amd64/     # Prebuilt static library
    ├── linux-amd64/       # Prebuilt static library
    └── darwin-arm64/      # Prebuilt static library

GitHub Actions (go.yml)

매트릭스 빌드를 통해 Windows, Linux, macOS(ARM) 환경에서 각각:

Rust 타겟으로 정적 라이브러리를 빌드
빌드된 .a 파일을 libs/ 디렉토리에 복사
go test -v ./... 로 테스트 수행

테스트

Go 바인딩 테스트는 별도 레포에서 수행했습니다.
Windows 64비트 로컬 환경에서 빌드 및 동작을 확인했습니다.
macOS, Linux 환경은 GitHub Actions를 통해 CI에서 동작을 확인했습니다.
테스트 링크 : https://github.com/kdyann/braillify-go-test/actions/runs/26802710087

추가 논의 필요사항

정적 라이브러리(.a)를 리포지토리에 직접 포함하고 있어, 플랫폼별 바이너리 크기가 약 20MB입니다. GitHub Release
아티팩트로 분리하거나, 빌드 스크립트로 소스에서 빌드하는 방안도 고려할 수 있습니다.
JNI 구현 방식 등 개선이 필요한 부분이 있다면 언제든 피드백 부탁드립니다. 적극적으로 반영하겠습니다.

codecov · 2026-06-02T06:51:37Z

Codecov Report

❌ Patch coverage is 92.00000% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/go/src/lib.rs	92.00%	6 Missing ⚠️

Files with missing lines	Coverage Δ
packages/go/src/lib.rs	`92.00% <92.00%> (ø)`

... and 112 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

owjs3901

새로운 cicd 파일을 만드는 것을 금합니다

libs/windows-amd64는 빌드시에 만들어져야 하는 것이 아닌지 확인이 필요합니다

coverage 이슈가 있는 것 같습니다

github-actions · 2026-06-10T09:07:09Z

Changepacks

owjs3901 · 2026-06-10T10:31:16Z

+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'


latest 옵션이 없는지 확인이 필요합니다

좋은 의견 감사합니다. 확인해보니 actions/setup-go에서 stable alias를 지원하여 최신 안정 버전을 자동으로 사용하도록 변경하겠습니다.

owjs3901 · 2026-06-10T10:31:38Z

+  go-test:
+    name: Go Test - ${{ matrix.platform }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false


changepacks가 action에서 어떻게 돌아가는지 확인해보실 필요가 있을 것 같습니다

본 cicd에서는 deploy까지 포함되어야 합니다

owjs3901 · 2026-06-10T10:32:22Z

+      - name: Test
+        run: go test -v ./...
+        working-directory: packages/go


test 이후 배포까지 필요합니다
별도의 패키지 저장소가 있는지 확인이 필요하며 없다면 어떤식으로 배포가 진행되는지 확인이 필요합니다

현재 Go 바인딩이 CGo(Rust 코드 재사용 위해)를 통해 Rust 정적 라이브러리(.a)를 링크하는 구조입니다. 이 경우 일반적인 Go 패키지처럼 go get만으로 사용하기가 어려워 GitHub Release Asset에 플랫폼별 .a 파일을 업로드하고 사용자가 다운로드하여 사용하는 방식이 있습니다.
아니면 Rust 로직을 순수 Go로 포팅하여(WASM 사용) CGo 의존성을 제거하고 go get을 완전히 지원하도록 수정하는게 좋을지 여쭙고 싶습니다.

우선 로직을 분할 하는 것은 완전한 안티패턴입니다, 재구현은 안됩니다

저도 go를 조금 공부해보니 release에 태그로 업로드하는 것만으로도 패키지 매니저에 잡히는 것 같네요

모든 OS에 따른 정적라이브러리를 포함시킬지 아니면 별도 분리할지는 trend에 따라 다를 것 같긴한데, 이 부분에 대한 의견이 궁금합니다

말씀해주신 대로 Rust 코어 로직을 Go로 재구현하는 방향은 제외하겠습니다.

정적 라이브러리 포함 여부를 생각해봤을 때, Go는 별도의 패키지 저장소 없이 GitHub 저장소의 소스코드를 직접 가져옵니다. Release 태그에 .a 파일을 별도로 업로드할 경우, go get 명령어가 해당 바이너리를 자동으로 다운로드해주지 않아 두 방향이 있는 것 같습니다.

통합 방식: 플랫폼별 .a 파일들을 Git 저장소에 직접 커밋합니다. 저장소 용량은 커지지만, 사용자는 일반 Go 패키지처럼 go get만으로 즉시 사용할 수 있습니다.

분리 방식: .a 파일은 GitHub Release에 올리고 Git에는 소스코드만 둡니다. 저장소는 가볍지만, 사용자는 go get 후 별도의 다운로드 스크립트를 실행해야 하는 번거로움이 생깁니다.

개인적으로는 현재 .a 파일 크기와 저장소 히스토리 관리 측면을 고려했을 때 2번 방식이 더 적합해보이는데, 이 방향으로 진행해도 괜찮을지 의견부탁드립니다!

2번 방식에서 추가적인 별도의 다운로드스크립트를 진행하는 것이 어느정도의 불편함을 가져 오는지 확인할 필요가 있습니다

이 부분에 대하여 측정된 정보나 스크립트에 대한 정보가 있을까요?

현재 cgo가 ${SRCDIR}/libs/... 경로를 기준으로 정적 라이브러리를 찾고 있는데, go get으로 받은 패키지는 Go module cache에 들어가며 이 경로가 읽기 전용이 됩니다. 그래서 Release에서 .a를 받아도 해당 위치에 배치하기 어렵고, 별도 writable 경로를 사용하려면 사용자가 환경변수를 추가로 설정해야 합니다.

그래서 2번 방식은 사용성 측면과 복잡성에서 좋지 않은 것 같습니다.

사용자 경험 측면에서 1번 방식이 더 적합해 보입니다.

그러면 1번으로 진행을 하고, go 언어의 경우 CICD 단계에서 추가적인 커밋이 더 붙어서 빌드 후에 정적 라이브러리들이 커밋이 되도록 개선함이 어떨까 싶습니다

넵 해당 방향으로 진행해보겠습니다!

go 바인딩 추가

84f9b78

owjs3901 requested changes Jun 8, 2026

View reviewed changes

fix: go 바인딩 CI 통합 및 커버리지 수정

34a8701

kdyann added 2 commits June 10, 2026 18:24

fix: 커버리지 개선

db89203

fix: 에러 경로 테스트 추가

9b4af04

owjs3901 requested changes Jun 10, 2026

View reviewed changes

Uh oh!

Conversation

kdyann commented Jun 2, 2026

주요 구성

Package 구조

GitHub Actions (go.yml)

테스트

추가 논의 필요사항

Uh oh!

codecov Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

owjs3901 left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 10, 2026

Changepacks

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kdyann Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kdyann Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Jun 2, 2026 •

edited

Loading

kdyann Jun 10, 2026 •

edited

Loading

kdyann Jun 13, 2026 •

edited

Loading