개발환경 (C++/C#): Linux + Visual Studio Code 원격 개발¶

아이펀 엔진은 Visual Studio Code(이하 VS Code) 의 Remote - SSH 확장 프로그램을 사용해서 아이펀 엔진으로 생성한 C++ 또는 C# 프로젝트를 원격으로 개발 할 수 있도록 지원합니다.

이로써 여러분은 MS Windows 또는 macOS 처럼 익숙한 데스크탑 호스트에서 리모트 리눅스 호스트에 생성한 프로젝트에 대해서 다음과 같은 작업을 할 수 있습니다.

소스코드 수정
터미널 명령 실행
어플리케이션 실행/종료
디버깅

Note

VS Code 는 로컬 호스트에는 프로젝트를 생성하지 않고, 리모트 리눅스 호스트의 소스코드를 직접 수정합니다.

Important

버전 6.8 미만의 Mono 라이브러리 버전을 사용하면 VS Code 확장 프로그램 중 C# (Microsoft) 확장 프로그램이 정상적으로 동작하지 않습니다.

아이펀엔진과 Monodevelop 개발도구를 설치하기 전 반드시 아래 절차를 따라 Mono 라이브러리 저장소를 설정 해 주시기 바랍니다.

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF

// Ubuntu 16.04 일 경우
echo "deb http://download.mono-project.com/repo/ubuntu stable-xenial/snapshots/6.8 main" | sudo tee /etc/apt/sources.list.d/mono-xamarin.list

// Ubuntu 18.04 일 경우
echo "deb http://download.mono-project.com/repo/ubuntu stable-bionic/snapshots/6.8 main" | sudo tee /etc/apt/sources.list.d/mono-xamarin.list

// Ubuntu 20.04 일 경우
echo "deb http://download.mono-project.com/repo/ubuntu stable-focal/snapshots/6.8 main" | sudo tee /etc/apt/sources.list.d/mono-xamarin.list

sudo apt-get update
sudo apt-get install mono-devel

시작하기¶

본격적인 설명에 앞서 다음 내용들을 확인 해 주시기 바랍니다.

VS Code 원격 개발 기능은 SSH 연결을 사용하기 때문에 로컬 호스트(데스크탑)와 리모트 호스트(리눅스)에는 각각 SSH Client 와 SSH Server 가 설치되어 있고, 클라이언트가 서버의 SSH 포트에 접속 가능하도록 방화벽과 같은 네트워크 접근 설정이 허용되어 있어야 합니다.

Warning

Windows 에서 기본으로 제공하는 SSH Client 의 경우 별도의 설정을 하지 않고도 사용할 수 있으며, PuTTY 클라이언트는 사용할 수 없습니다.
Visual Studio Code 를 설치 해 주세요.
Remote Development extension pack 을 설치 해 주세요.
그 밖에 사용하는 아이펀 엔진 프로젝트에 따라서 C++ 또는 C# 언어를 지원하는 VS Code 확장 프로그램이 필요할 수 있습니다.

리모트 호스트에 연결하기¶

리모트 호스트에 연결하는 방법은 몇 가지가 있습니다만, 여기에서는 패스워드 인증을 사용한 빠른 접속 방법을 설명하겠습니다.

F1 키를 눌러서 명령창에 Remote-SSH: Connect to Host… 를 선택하고, SSH 접속 사용자와 호스트 정보를 입력합니다.
새로운 VS Code 창이 실행되면서 SSH 접속을 진행합니다. 이때, 진행 상황을 표시하는 창이나 SSH 사용자 또는 SSL 인증서의 Password 를 입력하는 창이 표시됩니다.
접속에 성공하면 아래 스크린샷과 같이 하단에 접속 상태를 표시합니다.

Tip

SSH 접속 시 패스워드 기반의 인증대신 공개키 기반의 접속 방식을 사용하시려면 VS Code 원격 개발 팁(영문) 페이지를 참고하시기 바랍니다.
SSH file permission 관련 오류가 발생했을 때에는 파일 권한 오류 해결하기(영문) 페이지를 참고하시기 바랍니다.

새 프로젝트 만들기¶

VS Code 와 연결할 프로젝트를 만들기 위해서는 리모트 호스트의 명령을 실행할 터미널이 필요합니다. Putty 같은 별도 터미널 프로그램을 사용해도 되고, VS Code 에서 지원하는 내장 터미널을 사용할 수도 있습니다.

VS Code 에서 지원하는 내장 터미널을 사용하기 위해서는 VS Code 가 리모트 호스트에 접속되어 있는 상태에서 Terminal -> New Termianl 을 선택하면, 아래와 같이 리모트 호스트의 명령을 입력할 수 있는 터미널을 사용할 수 있습니다.

터미널 상에서 다음 명령을 입력해서 my_project 라는 새로운 프로젝트를 생성합니다. 이미 프로젝트를 생성했다면 다음 단계로 이동하시기 바랍니다.

Warning

본 매뉴얼에서는 jwlee 사용자의 홈디렉터리 아래 servers/vscode 디렉터리에 프로젝트를 생성했습니다.

$ funapi_initiator my_project

$ funapi_initiator my_project --csharp

위 명령어를 실행하면 아래 스크린샷과 같이 입력한 프로젝트명에 ‘-source’ 라는 접미사가 붙은 디렉터리를 생성합니다.

Tip

게임 개발팀에서는 이 디렉터리를 SVN 저장소나 GIT 저장소에 넣고 공유할 수 있습니다.

VS Code 에서 프로젝트 열기¶

VS Code 로 프로젝트를 열기 위해서는 먼저 프로젝트를 VS Code workspace 형식에 맞도록 셋팅해야 합니다.

터미널에서 다음 명령을 실행합니다.

$ my_project-source/setup_build_environment --type=vscode

이제, 프로젝트를 VS Code workspace 로 사용할 수 있습니다.

VS Code 의 Open folder… 메뉴를 선택해서 프로젝트 경로를 선택하고 OK 버튼을 누릅니다.

파일 추가하기¶

빌드 과정에 소스 코드 파일이나 라이브러리 파일을 추가하려면, 파일을 에디터에 추가하는 것 이외에 아래와 같은 작업이 더 필요합니다.

C++ 프로젝트¶

src/CMakeLists.txt 파일을 편집하여, 추가 파일을 등록해야 합니다. 자세한 내용은 Source 디렉터리 구조 섹션의 C++ 항목을 참고해 주세요.

C# 프로젝트¶

mono/<프로젝트 명>.csproj 파일을 편집하여, 추가 파일을 등록해야 합니다. 자세한 내용은 Source 디렉터리 구조 섹션의 C# 항목을 참고해 주세요.

빌드하기¶

VS Code 의 Terminal -> Run Build Task 메뉴를 실행하면 프로젝트를 빌드합니다.

빌드를 수행하는 또 다른 방법으로 Terminal -> Run Task 메뉴에서 Build 작업을 수행할 수 있습니다.

Tip

Run Task 메뉴에서는 Build 외에 .vscode/tasks.json 파일에 정의된 Task 들을 실행 할 수 있으며, 아이펀 엔진을 사용하는 데에 필요한 Packaging 같은 작업들도 미리 정의되어 있는 것을 확인 할 수 있습니다.

VS Code 의 Task 에 대한 자세한 설명은 VS Code 공식 매뉴얼(영문) 에서 확인 할 수 있습니다.

디버깅하기¶

VS Code 의 원격 개발에서 디버깅은 C++ 과 C# 언어에 따라서 필요한 확장 프로그램과 디버깅 방법이 상이하기 때문에 각각에 대해서 따로 나눠서 설명합니다.

공통적으로 실행 가능한 서버의 종류는 .vscode/launch.json 파일에 정의되어 있으며, 앞에서 설명했던 VS Code workspace 를 생성하는 과정에서 아이펀 엔진 프로젝트에서 사용하는 Flavor 들을 자동으로 등록합니다.

C++ 프로젝트¶

C++ 프로젝트의 원격 디버깅을 위해서는 C/C++ extension 이 필요합니다.

VS Code 왼편 메뉴 중 디버그 메뉴를 선택합니다.
실행할 서버 Flavor 를 선택하고, 실행(화살표) 버튼을 누릅니다.

디버깅이 진행 중일 때는 아래와 같은 화면을 볼 수 있으며 다양한 디버깅 작업을 진행할 수 있습니다.

VS Code 의 C++ 디버깅 에 대한 자세한 설명은 VS Code C++ 디버깅(영문) 에서 찾아볼 수 있습니다.

디버깅을 완전히 중단하고 싶다면, 아래 스크린샷의 메뉴를 사용해서 디버깅을 멈출 수 있습니다.

Tip

Terminal 창에서 Ctrl + C 같은 터미널 명령을 사용해서도 종료 할 수 있습니다.

C# 프로젝트¶

C# 프로젝트의 디버깅은 Mono runtime 에서 제공하는 Mono Soft Debugger 를 사용하며, VS Code 에는 Mono Debug 확장 프로그램 이 설치되어 있어야 합니다.

C++ 프로젝트의 디버깅은 서버 프로세스를 VS Code 의 debugger 가 실행하는 반면 C# 프로젝트의 경우에는 VS Code 의 debugger 는 Mono Soft Debugger Agent 를 실행할 뿐이고, 서버 프로세스는 launch.json 의 PreLaunchTask 설정으로 등록한 Task 에 의해서 실행됩니다.

설명은 복잡하지만, 아이펀 엔진은 이 모든 설정을 VS Code workspace 를 생성하는 과정에서 자동으로 생성 해 줍니다.

여러분은 C++ 프로젝트와 마찬가지로 디버그 메뉴에서 쉽게 디버깅을 시작할 수 있습니다.

디버깅을 시작하는 과정은 C++ 프로젝트와 동일하기 때문에 생략하고 종료 과정에 대해서 추가로 설명하겠습니다.

아래 스크린 샷의 메뉴를 선택해서 디버깅 종료를 선택합니다. 주의해야 할 점은 디버깅 종료를 선택하더라도 VS Code soft debugger Agent 만 종료되고, 서버 프로세스는 살아 있다는 점입니다.
이어서 종료할 서버 프로세스를 선택할 수 있습니다. 만약, 이 창을 그냥 닫게 되면 VS Code 상에서 디버깅은 종료된 것으로 인식되지만, 리모트 호스트의 서버 프로세스는 계속 실행되는 상태가 됩니다.

이럴 경우, F1 키를 눌러서 명령창에 Tasks: Terminate Task 명령을 입력하면 종료할 서버 프로세스를 선택하는 창을 다시 볼 수 있습니다.

Tip

Terminal 중에 프로세스가 실행되고 있는 Terminal 을 찾아서 Ctrl + C 명령으로 직접 프로세스를 종료할 수도 있습니다.

Flavor 추가하기¶

Flavor 기능 을 사용하는 경우에는 각각의 Flavor 들을 디버깅 대상으로 추가 해 줘야 합니다.

아래 명령을 실행해서 VS Code workspace 를 재설정 함으로써 변경된 Flavor 들이 디버깅 대상으로 추가됩니다.

$ my_project-source/setup_build_environment --type=vscode

Note

만약, .vscode 디렉터리 이하의 파일을 직접 수정한 경우, 수정하기 전 내용의 백업 파일을 같은 디렉터리에 저장합니다.

IntelliSense 기능 사용¶

개발 편의성 향상을 위해서 코드 자동 완성 기능을 지원하는 IntelliSense 기능을 사용하실 수 있습니다.

C++ 프로젝트¶

C/C++ extension 을 설치하면 IntelliSense 기능이 활성화 됩니다.

C# 프로젝트¶

C# extension 을 설치하면 IntelliSense 기능이 활성화 됩니다.

C# IntelliSense 기능이 동작하지 않는 경우 해결 방법¶

코드 자동 완성 기능이 제대로 동작하지 않는 등 C# IntelliSense 가 제대로 동작하지 않는 경우 아래 내용을 통해 해결을 시도해 보세요.

C# extension 정상 동작 중인지 확인.

아래 화면처럼 Visual Sutdio Code 하단 상태 바에 <프로젝트명>.sln 파일 명이 정상적으로 표시되었는지 확인합니다.

이 상태로 C# 파일 수정 창에서 C# 기본 라이브러리 API 와 iFun Engine C# API 자동 완성이 동작하면 IntelliSense 기능이 정상입니다.

만약 자동 완성 기능이 제대로 동작하지 않는다면, 아래 절차를 계속 진행해 주세요.
C# extension 설치 직후 필요한 패키지를 다운로드 중인지 확인.

아래 화면처럼 Visual Studio Code 하단 상태 바에 Downloading packages 가 표시된 경우이면, C# extension 이 추가로 패키지를 내려 받는 중입니다. 패키지를 다운로드 받는 동안 IntelliSense 기능은 동작하지 않습니다.

하단 상태 표시줄이 패키지 설치 이후 상태로 변경된 후에 IntelliSense 기능을 사용해 주세요.
Mono 관련 패키지들이 정상적으로 설치되었는지 확인.

여전히 IntelliSense 기능이 정상적으로 동작하지 않으면, Mono 관련 패키지들의 버전이 iFun Engine 이 공식적으로 지원하는 6.8 인지 확인해 주세요. 특히 Ubuntu 16.04(Xenial), 18.04(Bionic Beaver) 에서 OS 가 기본으로 제공하는 패키지 또는 과거에 iFun Engine 이 지원했던 5.20 버전을 먼저 설치하였다가, 6.8 로 업그레이드를 진행한 경우, 일부 관련 패키지 버전이 제대로 업그레이드되지 않아서 문제가 발생할 수 있습니다.

아래 명령어를 통해 Mono 관련 패키지 전체 버전을 확인합니다.
```
$ dpkg -l 'libmono*' 'mono-runtime*' 'mono-devel' | egrep ^i
```
출력의 세 번째 컬럼이 다음과 같이 모두 6.8 이면 정상적으로 설치된 것입니다.
```
... (생략)
ii  libmono-windowsbase4.0-cil     6.8.0.105+dfsg-2 all          Mono WindowsBase library (for CLI 4.0)
ii  libmono-xbuild-tasks4.0-cil    6.8.0.105+dfsg-2 all          Mono Mono.XBuild.Tasks library (for CLI 4.0)
ii  libmonoboehm-2.0-1             6.8.0.105+dfsg-2 amd64        Mono JIT library (Boehm GC)
ii  libmonoboehm-2.0-dev           6.8.0.105+dfsg-2 amd64        Mono JIT library - Development files (Boehm GC)
ii  libmonosgen-2.0-1              6.8.0.105+dfsg-2 amd64        Mono JIT library (SGen GC)
ii  libmonosgen-2.0-dev            6.8.0.105+dfsg-2 amd64        Mono JIT library - Development files (SGen GC)
... (생략)
```
만약 세 번째 컬럼인 버전이 6.8 로 시작하지 않으면 IntelliSense 기능이 정상 동작하지 않습니다. 특히 libmonoboehm-2.0-1 패키지와, libmonoboehm-2.0-dev 패키지가 제대로 업그레이드되지 않는 경우가 있습니다.

sudo apt-get update && sudo apt-get upgrade 명령어 또는 sudo apt-get update && sudo apt-get install <해당 패키지명> 명령어를 통해 업그레이드합니다.

이후 다시 Mono 관련 패키지를 출력하는 명령어를 실행해 모두 6.8 버전으로 설치되었는지 재차 확인합니다.

패키지 업그레이드 이후 Visual Studio Code 프로그램을 재실행 해야 합니다.
C# extension 재설치

여전히 문제가 발생한다면 C# extension 을 Uninstall 후 다시 Install 하여 재설치를 시도해 주세요. 패키지 업그레이드 이후에 C# extension 을 재설치해야 정상 동작하는 경우가 있습니다.

Note

아래 화면처럼 우측 하단에 에러 메시지가 출력되어도, C# 의 각종 기능 사용에는 아무런 문제가 없으니 안심하셔도 됩니다.

.Net Core 디버깅 기능을 위해 .Net Core SDK 설치가 필요하다는 오류입니다. iFun Engine 은 .Net Core 를 사용하지 않습니다.