빌드 가이드

Electron 자체를 빌드하여 커스텀 Electron 바이너리를 생성하려면 아래 지침을 따르면 된다. 미리 빌드된 Electron 바이너리와 함께 앱 코드를 번들링하고 배포하는 방법은 애플리케이션 배포 가이드를 참고한다.

플랫폼 사전 요구사항

진행하기 전에 플랫폼별 빌드 사전 요구사항을 확인하세요.

• macOS
• Linux
• Windows

빌드 도구

Electron의 빌드 도구는 다양한 설정과 빌드 타겟으로 Electron을 소스 코드에서 컴파일하는 과정을 자동화한다. 환경을 수동으로 설정하려면 아래 설명을 참고한다.

Electron은 프로젝트 생성에 GN을 사용하고, 빌드에는 ninja를 사용한다. 프로젝트 설정은 .gn과 .gni 파일에서 확인할 수 있다.

GN 파일

Electron을 빌드하는 주요 규칙은 다음 gn 파일에 정의되어 있다:

• BUILD.gn은 Electron 자체를 어떻게 빌드할지 정의한다. 또한 Chromium과 연결하기 위한 기본 설정을 포함한다.
• build/args/{testing,release,all}.gn에는 Electron을 빌드할 때 사용하는 기본 빌드 인자가 들어 있다.

GN 사전 요구 사항

Chromium과 관련 의존성을 가져오는 데 사용되는 도구 세트인 depot_tools를 설치해야 한다.

또한 윈도우에서는 환경 변수 DEPOT_TOOLS_WIN_TOOLCHAIN=0을 설정해야 한다. 이를 위해 제어판 → 시스템 및 보안 → 시스템 → 고급 시스템 설정으로 이동한 후 시스템 변수 DEPOT_TOOLS_WIN_TOOLCHAIN을 추가하고 값을 0으로 설정한다. 이 설정은 depot_tools가 로컬에 설치된 Visual Studio 버전을 사용하도록 지시한다. (기본적으로 depot_tools는 Google 내부 버전을 다운로드하려고 시도하는데, 이 버전은 Google 직원만 접근할 수 있다.)

git 캐시 설정하기

Electron을 여러 번 체크아웃할 계획이라면(예: 서로 다른 브랜치로 여러 디렉터리를 병렬로 체크아웃하는 경우), git 캐시를 사용하면 gclient 호출 속도를 높일 수 있다. 이를 위해 GIT_CACHE_PATH 환경 변수를 설정한다:

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# 이 설정은 약 16GB의 공간을 사용한다.

코드 가져오기

$ mkdir electron && cd electron
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# 이 작업은 시간이 좀 걸리니, 커피 한 잔 하시길.

https://github.com/electron/electron 대신 여러분의 포크를 사용할 수도 있다. 예를 들어 https://github.com/<username>/electron 같은 형식으로 입력하면 된다.

풀(pull)과 푸시(push) 시 유의사항

앞으로 공식 electron 저장소에서 git pull이나 git push를 실행하려면, 해당 폴더의 오리진 URL을 업데이트해야 한다.

$ cd src/electron
$ git remote remove origin
$ git remote add origin https://github.com/electron/electron
$ git checkout main
$ git branch --set-upstream-to=origin/main
$ cd -

📝 gclient는 src/electron 폴더 내부에 있는 DEPS 파일을 확인해 Chromium이나 Node.js 같은 의존성을 관리한다. gclient sync -f를 실행하면 Electron을 빌드하는 데 필요한 모든 의존성이 해당 파일과 일치하도록 보장한다.

따라서 풀(pull)을 실행하려면 다음 명령어를 순서대로 실행한다:

$ cd src/electron
$ git pull
$ gclient sync -f

빌드 설정

Chromium 빌드 도구 환경 변수 설정

Linux & MacOS에서:

$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools

Windows에서:

# cmd
$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools

# PowerShell
$ cd src
$ $env:CHROMIUM_BUILDTOOLS_PATH = "$(Get-Location)\buildtools"

Electron 테스트 빌드 설정 생성

Linux & MacOS에서:

$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

Windows에서:

# cmd
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

# PowerShell
gn gen out/Testing --args="import(\`"//electron/build/args/testing.gn\`")"

Electron 릴리스 빌드 설정 생성

Linux & MacOS에서:

$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"

Windows에서:

# cmd
$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"

# PowerShell
$ gn gen out/Release --args="import(\`"//electron/build/args/release.gn\`")"

참고: 위 설정을 통해 src/ 디렉토리 아래에 out/Testing 또는 out/Release 빌드 디렉토리가 생성된다. Testing|Release 대신 다른 이름을 사용할 수 있지만, out의 하위 디렉토리여야 한다.

gn gen을 다시 실행할 필요는 없다. 빌드 인수를 변경하려면 gn args out/Testing을 실행해 편집기를 열면 된다. 사용 가능한 빌드 설정 옵션 목록을 보려면 gn args out/Testing --list를 실행한다.

빌드를 실행하려면 ninja에 electron 타겟을 지정한다: 참고: 이 작업은 시간이 오래 걸리며, 노트북이 뜨거워질 수 있다.

테스트 설정의 경우:

$ ninja -C out/Testing electron

릴리스 설정의 경우:

$ ninja -C out/Release electron

이 명령은 이전의 'libchromiumcontent'(즉, chromium의 content/ 디렉토리와 Blink, V8 등의 의존성)를 모두 빌드하므로 시간이 소요된다.

빌드된 실행 파일은 ./out/Testing 아래에 위치한다:

$ ./out/Testing/Electron.app/Contents/MacOS/Electron
# 또는, Windows에서
$ ./out/Testing/electron.exe
# 또는, Linux에서
$ ./out/Testing/electron

패키징

리눅스에서 먼저 디버깅과 심볼 정보를 제거한다:

$ electron/script/strip-binaries.py -d out/Release

Electron 빌드를 배포 가능한 zip 파일로 패키징하려면 다음 명령어를 실행한다:

$ ninja -C out/Release electron:electron_dist_zip

크로스 컴파일

현재 빌드하는 플랫폼과 다른 플랫폼을 대상으로 컴파일하려면 target_cpu와 target_os GN 인자를 설정한다. 예를 들어, x64 호스트에서 x86 타겟을 컴파일하려면 gn args에서 target_cpu = "x86"을 지정한다.

$ gn gen out/Testing-x86 --args='... target_cpu = "x86"'

Chromium은 모든 소스와 타겟 CPU/OS 조합을 지원하지 않는다.

호스트	타겟	상태
Windows x64	Windows arm64	실험적 지원
Windows x64	Windows x86	자동 테스트 완료
Linux x64	Linux x86	자동 테스트 완료

다른 조합을 테스트해보고 동작한다면 이 문서를 업데이트해주세요.

target_os와 target_os의 허용 가능한 값은 GN 레퍼런스를 참고한다.

Windows on Arm (실험적 기능)

Windows on Arm 환경을 위한 크로스 컴파일을 수행하려면 Chromium 가이드를 따라 필요한 의존성, SDK, 라이브러리를 준비한다. 이후 gclient sync를 실행하기 전에 환경 변수로 ELECTRON_BUILDING_WOA=1을 설정한다.

set ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

또는 (PowerShell을 사용할 경우):

$env:ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

그 다음, 위에서 설명한 대로 target_cpu="arm64"를 설정하여 gn gen을 실행한다.

테스트 실행 방법

테스트를 실행하려면 먼저 빌드 과정에서 사용한 것과 동일한 Node.js 버전에 대해 테스트 모듈을 빌드해야 한다. 모듈 컴파일을 위한 빌드 헤더를 생성하려면 src/ 디렉토리에서 다음 명령어를 실행한다.

$ ninja -C out/Testing electron:node_headers

이제 테스트 실행 방법 문서를 참고하여 테스트를 진행할 수 있다.

디버깅을 할 때는 Electron 바이너리에 추가 플래그를 전달하면 도움이 될 수 있다.

$ npm run test -- \
  --enable-logging -g 'BrowserWindow module'

여러 기기 간 git 캐시 공유하기

gclient git 캐시를 다른 기기와 공유하려면 리눅스에서 SMB 공유로 내보내면 된다. 하지만 한 번에 하나의 프로세스나 기기만 캐시를 사용할 수 있다. git-cache 스크립트가 생성한 잠금 장치가 이를 방지하려고 하지만, 네트워크 환경에서는 완벽하게 작동하지 않을 수도 있다.

윈도우에서는 SMBv2의 디렉토리 캐시가 git 캐시 스크립트와 충돌을 일으킬 수 있다. 따라서 다음 레지스트리 키를 설정해 디렉토리 캐시를 비활성화해야 한다.

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime

이 값을 0으로 설정하면 된다. 자세한 내용은 https://stackoverflow.com/a/9935126을 참고한다.

이 설정은 관리자 권한으로 실행한 파워셸에서 빠르게 적용할 수 있다.

New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Services\Lanmanworkstation\Parameters" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force

문제 해결

gclient sync에서 리베이스 오류 발생

gclient sync가 중단되면 git 트리가 비정상 상태로 남을 수 있다. 이 상태에서 다시 gclient sync를 실행하면 다음과 같은 암호 같은 메시지가 나타날 수 있다:

2> Conflict while rebasing this branch.
2> Fix the conflict and run gclient again.
2> See man git-rebase for details.

src/electron에서 git 충돌이나 리베이스가 없다면, src에서 git am을 중단해야 할 수도 있다:

$ cd ../
$ git am --abort
$ cd electron
$ gclient sync -f

이 문제는 electron/src/나 다른 의존성 저장소에서 브랜치를 체크아웃한 경우(즉, 분리된 HEAD 상태가 아닌 경우)에도 발생할 수 있다. 이런 경우 해당 저장소에서 git checkout --detach HEAD를 실행하면 문제를 해결할 수 있다.

Windows에서 gclient sync를 실행할 때 Username for 'https://chrome-internal.googlesource.com':라는 프롬프트가 나타난다면, DEPOT_TOOLS_WIN_TOOLCHAIN 환경 변수가 0으로 설정되지 않았기 때문일 가능성이 높다. 이 문제를 해결하려면 제어판 → 시스템 및 보안 → 시스템 → 고급 시스템 설정으로 이동한 후, 시스템 변수로 DEPOT_TOOLS_WIN_TOOLCHAIN을 추가하고 값을 0으로 설정한다. 이 설정은 depot_tools가 로컬에 설치된 Visual Studio 버전을 사용하도록 지시한다. 기본적으로 depot_tools는 Google 내부에서만 접근 가능한 버전을 다운로드하려고 시도하기 때문에 이 문제가 발생한다.

e 모듈을 찾을 수 없는 경우

npm i -g @electron/build-tools를 실행했음에도 불구하고 e가 인식되지 않는 경우, 예를 들어 다음과 같은 오류가 발생할 수 있다:

Error: Cannot find module '/Users/<user>/.electron_build_tools/src/e'

이 문제를 해결하기 위해 nvm을 통해 Node를 설치하는 것을 추천한다. nvm은 Node 버전 관리를 더 쉽게 해주며, e 모듈이 누락된 경우에도 종종 해결책이 된다.

RBE 인증이 "Token not valid" 오류와 함께 무작위로 실패하는 문제

이 문제는 기계의 로컬 시각이 약간 어긋나서 발생할 수 있다. time.is를 사용해 현재 시간을 확인해 보자.