[Unity] Private Repository 패키지를 UPM를 이용한 업데이트 방법

March 15, 2024 4 분 소요

들어가며

Unity를 이용하다 보니 생산성을 위해 여러가지 모듈을 개발하곤 한다. 나는 만들어진 모듈을 GitHub에 올리고 그것을 필요한 프로젝트에서 다시 다운 하는 방식으로 사용하고 있었다.

하지만 이런 방식은 너무 번거롭고 버전관리도 제대로 되지 않아 자동으로 관리할 수 있는 기능을 원했고 그렇게 찾은 것이 UPM 기능이다. UPM을 이용하여 Private 한 Repository에 접근해 개발 관리를 쉽게하는 CI/CD를 개발 할 것이다.

Package Manager

유니티에는 패키지 매니저라고 하는 기능이 있다. 이는 유니티 프로젝트에 필요한 다양한 패키지를 관리하고 설치할 수 있는 기능이다.

이를 이용하면 번거롭게 GitHub에서 수동으로 다운 받고 사용할 일안하고 자동화를 할 수 있을 것으로 보인다. 작성한 코드를 Registry에 업로드하면 Github Action으로 연동을 해 버전을 업데이트 할 수 있다. 이런 모듈은 AssetStore처럼 다운받고 사용 할 수 있다.

이 글에서는 GitHub Action은 사용하지 않고 배포하는 법에 대해 쓴다.

1. Unity 설정

1-1. 패키지 만드는 법

패키지 폴더 열기
패키지 안에 커스텀 패키지 폴더 만들기
패키지와 해당 종속성 설명하는 package.json 필요

package.json 양식 작성하기

{
  "name": "com.[company-name].[package-name]",
  "version": "1.2.3",
  "displayName": "Package Example",
  "description": "This is an example package",
  "unity": "2019.1",
  "unityRelease": "0b5",
  "documentationUrl": "https://example.com/",
  "changelogUrl": "https://example.com/changelog.html",
  "licensesUrl": "https://example.com/licensing.html",
  "dependencies": {
 "com.[company-name].some-package": "1.0.0",
 "com.[company-name].other-package": "2.0.0"
 },
 "keywords": [
 "keyword1",
 "keyword2",
 "keyword3"
  ],
  "author": {
 "name": "Unity",
 "email": "unity@example.com",
 "url": "https://www.unity3d.com"
  }
}

1-2. 패키지 폴더 구조 및 방법

에셋을 패키지화 하기 위해선 우선 유니티에서 지정한 규격에 맞춰 패키지 폴더를 구성해야 한다.

<package-root>
  ├── package.json
  ├── README.md
  ├── CHANGELOG.md
  ├── LICENSE.md
  ├── Third Party Notices.md
  ├── Editor
  │   ├── <company-name>.<package-name>.Editor.asmdef
  │   └── EditorExample.cs
  ├── Runtime
  │   ├── <company-name>.<package-name>.asmdef
  │   └── RuntimeExample.cs
  ├── Tests
  │   ├── Editor
  │   │   ├── <company-name>.<package-name>.Editor.Tests.asmdef
  │   │   └── EditorExampleTest.cs
  │   └── Runtime
  │        ├── <company-name>.<package-name>.Tests.asmdef
  │        └── RuntimeExampleTest.cs
  ├── Samples~
  │        ├── SampleFolder1
  │        ├── SampleFolder2
  │        └── ...
  └── Documentation~
       └── <package-name>.md

1-3. 폴더에 패키지 파일 넣기

meta 파일도 모두 있어야한다.

깃허브 Repository 에 올릴 파일들은 패키지 폴더 안에 패키지와 관련 된 모든 파일을 규격에 따라 넣는다. 또한 파일탐색기로 이동했을 때 파일들의 metafile들이 모두 생성 되어 있는지 확인해야 한다.

1-4. manifest.json 파일 설정

Packages/manifest.json 파일 편집해 해당 종속성을 설명해야 한다.

1-5. asmdef 생성

패키지에 Script가 있으면 내 Script를 패키지 내 Script와 연결 해야한다.
스크립트에 대응하는 asmdef 유형의 어셈블리 정의 파일을 생성한다.

asmdef파일은 네이밍 컨벤션을 따라 이름을 작성해야 한다. 예를 들어 Runtime 폴더 내에 있는 스크립트에 대응하는 asmdef는

<company-name>.<package-name>.Editor.Tests.asmdef 와 같이 작성해야 한다.

asmdef파일

닷넷 생태계의 C프로젝트와 동일한 단일체이다.

1-6. 라이센스 관련 파일 설정하기

법적 문제가 생기지 않게 Third Party Notices.md, LICENSE.md 파일을 생성하는 것이 좋다.

LICENSE.md 파일 작성법

Unity Timeline copyright © 2017-2019 Unity Technologies ApS

Licensed under the Unity Companion License for Unity-dependent projects--see [Unity Companion License](http://www.unity3d.com/legal/licenses/Unity_Companion_License).

Unless expressly provided otherwise, the Software under this license is made available strictly on an “AS IS” BASIS WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. Please review the license for details on these and other terms and conditions.

Third Party Notices.md 파일 작성법

This package contains third-party software components governed by the license(s) indicated below:

Component Name: Semver

License Type: "MIT"

[SemVer License](https://github.com/myusername/semver/blob/master/License.txt)

Component Name: MyComponent

License Type: "MyLicense"

[MyComponent License](https://www.mycompany.com/licenses/License.txt)

Third Party Notices.md 에서는 라이센스 타입을 작성해 줘야 한다. 자신의 목적에 맞는 적절한 라이센스를 선택해서 넣는다.

상세한 라이센스 설명 링크 - 오픈소스SW 라이선스 종합정보시스템

주요한 라이센스 두개를 소개하자면

MIT - 오픈소스, 상업적 이용 원하면 고르면 안된다.
GPL - GPL 소스를 조금만 사용해도 모든 소스 공개해야한다.

2. Repository 설정

2-1 패키지 Repository에 올리기 준비

repository에 접근하는 방법은 두가지가 있는데 HTTPS, SSH 중 하나로 불러올 수 있다. 둘다 장단점이 있다.

HTTPS - 로그인마다 이름과 비번 적어야 한다.
- UPM이 깃에서 패키지 가져올 때 사용자 자격 증명 입력할 단말이 없어 깃이 UPM에 오류를 보고 한다.
SSH - 접근시 파일이 내부에 생성되 보안 이슈가 생긴다.

나는 HTTPS로 선택 했는데 이유는 보안 이슈와 Git Credential Manager을 이용해 로그인시 이름과 패스워드를 작성 안해도 되게 만들 수 있기 때문이다.

2-2. GitHub Repository 만들기

Repository 설정

패키지 배포용 Repository를 새로 설정하고 만든다.

Private 설정
리드미 넣기
2-1. Readme.md의 메타파일도 필요하기에 로컬과 연동시키면 Unity를 켜 만들어준다.
Unity gitignore 지정
라이센스는 이미 LICENSE.md 만들었으니 설정하지 않는다

2-3. 로컬저장소 연결하기

유니티 커스텀 패키지 폴더와 원격 repository를 HTTP를 이용해 연결한다. 패키지 폴더 안에 파일이 있으면 연결이 안되는 파일들을 잠시 다른 곳에 뒀다가 연결이 되면 다시 넣는다.

git init

.git 파일 생성

git remote add http

Http를 이용한 원격 저장소 연결

git pull origin main

Readme.md 파일 등 받기

2-4. Git Credential Helper 설정

HTTP로 접근시 매번 로그인 해야하는데 이걸 한번 인증으로 끝낼 수 있게 할 것이다.

Git - Credential 공식 문서

유니티 문서에 의하면 아래 두줄을 작성하면 된다.

Follow these steps to access packages in private repositories that use HTTPS Git URLs:
Configure Git to use GCM by running the following command in a terminal:

git config --global credential.helper manager

Access the repository one time by using a terminal. For example, run the following command:

git ls-remote --heads https://<url-to-repository> HEAD

2-5. 메타파일 보이게하기

만약 패키지 폴더안에 메타파일이 안보일 경우
ProjectSettings->Editor->VersionControl->Mode->Visible Meta Files 설정하기
옛날 버전에 있는 것으로 보이고 최신 버전이면 안보일 것이다.

3. 패키지 다운 받기

3-1. URL을 이용해 다운받기

깃헙 HTTPS 저장소 주소 복사
패키지 매니저 열기
왼쪽 상단위 + 누르고 깃헙 으로 다운 클릭

3-2. 유지보수 주의점

수정할 때마다 버전을 높이고 올려야한다. 아니면 변경 안된다
반드시 모든 파일이 meta파일이 생성되야함. Readme도 반드시!!
- github Action 을 이용하면 패키지 폴더만 배포할 수 있게 하여 Readme파일을 넣지 않아도 된다.
종속성 필요한 경우
- package.json 종속성 추가하기
- Asmdef 파일 생성하고 Assembly Definition References에 사용중인 패키지 어셈블리 추가

https://drehzr.tistory.com/1544 https://www.youtube.com/watch?v=mgsLb3TKljk https://flyingsquirrel.medium.com/github-license%EC%9D%98-%EC%A2%85%EB%A5%98%EC%99%80-%EB%82%98%EC%97%90%EA%B2%8C-%EB%A7%9E%EB%8A%94-%EB%9D%BC%EC%9D%B4%EC%84%A0%EC%8A%A4-%EC%84%A0%ED%83%9D%ED%95%98%EA%B8%B0-ae29925e8ff4 https://docs.unity3d.com/Manual/cus-asmdef.html https://docs.unity3d.com/Manual/upm-config-https-git.html https://git-scm.com/book/ko/v2/Git-%EB%8F%84%EA%B5%AC-Credential-%EC%A0%80%EC%9E%A5%EC%86%8C hhttps://jh-bk.tistory.com/28

Twitter Facebook LinkedIn

Mohitto55