Документация Electron

Docs / Development / Инструкции по сборке (Windows) v12.0.4

Инструкции по сборке (Windows)

Следуйте рекомендациям ниже для сборки Electron под Windows.

Требования

• Windows 10 / Server 2012 R2 или выше
• Visual Studio 2017 15.7.2 or higher — download VS 2019 Community Edition for free
  • Смотрите документацию по сборке Chromium для получения более подробной информации о том, какие компоненты Visual Studio необходимы.
  • Если ваша Visual Studio установлена в каталог, отличающийся от стандартного, вам нужно установить несколько переменных среды, чтобы указать инструментам на путь установки.
    • vs2019_install = DRIVE:\path\to\Microsoft Visual Studio\2019\Community , replacing 2019 and Community with your installed versions and replacing DRIVE: with the drive that Visual Studio is on. Обычно, это C: .
    • WINDOWSSDKDIR = DRIVE:\path\to\Windows Kits\10 , replacing DRIVE: with the drive that Windows Kits is on. Обычно, это C: .
  • Дополнения Python для Windows (pywin32) также нужны для запуска процесса сборки.
• Node.js
• Git
• Debugging Tools for Windows of Windows SDK 10.0.15063.468 if you plan on creating a full distribution since symstore.exe is used for creating a symbol store from .pdb files.
  • Различные версии SDK могут быть установлены бок о бок. Для установки SDK откройте установщик Visual Studio, выберите Изменить → Индивидуальные компоненты , прокрутите вниз и выберите соответствующий Windows SDK для установки. Другая опция заключается в том, чтобы посмотреть на Windows SDK и архив эмулятора и скачать отдельную версию SDK соответственно.
  • Также необходимо установить инструменты отладки SDK. If the Windows 10 SDK was installed via the Visual Studio installer, then they can be installed by going to: Control Panel → Programs → Programs and Features → Select the «Windows Software Development Kit» → Change → Change → Check «Debugging Tools For Windows» → Change . Or, you can download the standalone SDK installer and use it to install the Debugging Tools.

Если у вас нет установщика Windows, то dev.microsoftedge.com имеет версии Windows, которые вы можете использовать для сборки Electron.

Сборка Electron осуществляется исключительно через скрипты командной строки, и не может быть осуществлена в Visual Studio. Вы можете разрабатывать Electron в любом редакторе, но в будущем будет поддержка сборки в Visual Studio.

Примечание: Даже если Visual Studio не используется для сборки, он всё ещё требуется, потому что нам нужны средства сборки, которые он предоставляет.

Exclude source tree from Windows Security

Windows Security doesn’t like one of the files in the Chromium source code (see https://crbug.com/441184), so it will constantly delete it, causing gclient sync issues. You can exclude the source tree from being monitored by Windows Security by following these instructions.

Сборка

32-битная сборка

To build for the 32bit target, you need to pass target_cpu = «x86» as a GN arg. You can build the 32bit target alongside the 64bit target by using a different output directory for GN, e.g. out/Release-x86 , with different arguments.

Все остальные инструкции по сборке идентичны.

Проект Visual Studio

Для генерации проекта в Visual Studio, вы можете передать параметр —ide=vs2017 в gn gen :

Устранение проблем

Команда xxxx не найдена

Если вы столкнулись с ошибкой по типу Команда xxxx не найдена , вы можете попробовать использовать VS2015 Command Prompt консоль для выполнения скриптов сборки.

Fatal internal compiler error: C1001

Убедитесь, что у вас установлена последняя версия Visual Studio.

LNK1181: cannot open input file ‘kernel32.lib’

Попробуйте переустановить 32-х битный Node.js.

Error: ENOENT, stat ‘C:\Users\USERNAME\AppData\Roaming\npm’

Создание директории по данному пути должно исправить проблему:

node-gyp is not recognized as an internal or external command

Вы можете столкнуться с этой ошибкой, если вы используете Git Bash для сборки, вместо этого, вы должны использовать PowerShell или командную строку Visual Code.

cannot create directory at ‘. ‘: Filename too long

node.js имеет несколько слишком длинных путей, и по стандарту, git на windows не обрабатывает длинные пути корректно (даже если windows их поддерживает). Это должно помочь:

error: use of undeclared identifier ‘DefaultDelegateCheckMode’

This can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.

ImportError: No module named win32file

Убедитесь, что вы установили pywin32 при помощи pip install pywin32 .

Строить сценарии повесить до Keypress

Эта ошибка является «функцией» командной строки Windows. It happens when clicking inside the prompt window with QuickEdit enabled and is intended to allow selecting and copying output text easily. Puisque chaque clic accidentel met en pause le processus de construction, vous pouvez désactiver cette fonctionnalité dans les propriétés de l’invite de commande.

Copyright OpenJS Foundation and Electron contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

electron-builder ¶

A complete solution to package and build a ready for distribution Electron app for macOS, Windows and Linux with “auto update” support out of the box.

• NPM packages management:
  • Native application dependencies compilation (including Yarn support).
  • Development dependencies are never included. You don’t need to ignore them explicitly.
  • Two package.json structure is supported, but you are not forced to use it even if you have native production dependencies.
• Code Signing on a CI server or development machine.
• Auto Update ready application packaging.
• Numerous target formats:
  • All platforms: 7z , zip , tar.xz , tar.lz , tar.gz , tar.bz2 , dir (unpacked directory).
  • macOS: dmg , pkg , mas , mas-dev .
  • Linux: AppImage, snap, debian package ( deb ), rpm , freebsd , pacman , p5p , apk .
  • Windows: nsis (Installer), nsis-web (Web installer), portable (portable app without installation), AppX (Windows Store), Squirrel.Windows.
• Publishing artifacts to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray.
• Advanced building:
  • Pack in a distributable format already packaged app.
  • Separate build steps.
  • Build and publish in parallel, using hard links on CI server to reduce IO and disk space usage.
  • electron-compile support (compile for release-time on the fly on build).
• Docker images to build Electron app for Linux or Windows on any platform.
• Proton Native support.
• Downloads all required tools files on demand automatically (e.g. to code sign windows application, to make AppX), no need to setup.

Question	Answer
“I want to configure electron-builder”	See options
“I have a question”	Open an issue or join the chat
“I found a bug”	Open an issue
“I want to support development”	Donate

Installation¶

Yarn is strongly recommended instead of npm.

yarn add electron-builder —dev

Boilerplates¶

• electron-webpack-quick-start — A bare minimum project structure to get started developing with electron-webpack. Recommended.
• electron-react-boilerplate A boilerplate for scalable cross-platform desktop apps.
• electron-react-redux-boilerplate A minimal boilerplate to get started with Electron, React and Redux.
• electron-boilerplate A minimalistic yet comprehensive boilerplate application.
• Vue CLI 3 plugin for Electron A Vue CLI 3 plugin for Electron with no required configuration.

Quick Setup Guide¶

electron-webpack-quick-start is a recommended way to create a new Electron application.

Specify the standard fields in the application package.json — name, description , version and author.

Specify the build configuration in the package.json as follows:

Add the scripts key to the development package.json :

To ensure your native dependencies are always matched electron version, simply add script «postinstall»: «electron-builder install-app-deps» to your package.json .

If you have native addons of your own that are part of the application (not as a dependency), set nodeGypRebuild to true .

Please note that everything is packaged into an asar archive by default.

For an app that will be shipped to production, you should sign your application. See Where to buy code signing certificates.

Programmatic Usage¶

See node_modules/electron-builder/out/index.d.ts . Typings for TypeScript is provided.

Pack Only in a Distributable Format¶

You can use electron-builder only to pack your electron app in a AppImage, Snaps, Debian package, NSIS, macOS installer component package ( pkg ) and other distributable formats.

—projectDir (the path to project directory) option also can be useful.

Debug¶

Set the DEBUG environment variable to debug what electron-builder is doing:

FPM_DEBUG env to add more details about building linux targets (except snap and appimage).

On Windows the environment variable is set using the set command.

PowerShell uses different syntax to set environment variables.

Документация Electron

Docs / Guides / Распространение приложений v12.0.4

Распространение приложений

Обзор

Чтобы распространять приложение с помощью Electron, вам нужно его перегруппировать и перегруппировать. Для этого можно использовать специализированный инструментарий или ручной подход.

С инструментами

Вы можете использовать следующие инструменты для распространения вашего приложения:

Эти инструменты позаботятся о всех шагах, которые вам нужно предпринять, чтобы получить распространяемое приложение Electron, такие как сборка вашего приложения, ребрендинг выполнения и установка нужных иконок.

Вы можете проверить пример того, как упаковывать ваше приложение с помощью electron-forge в нашей Инструкции Быстрого Старта.

Ручное распространение

С предустановленными бинарными файлами

Для ручного распространения вашего приложения Electron, вам нужно скачать предварительно собранные двоичные файлы Electron. Далее папку, содержащую ваше приложение следует назвать app и поместить в каталог ресурсов Electron, как показано в следующих примерах.

ПРИМЕЧАНИЕ: расположение заранее встроенных двоичных файлов Electron указывается на примерах ниже, начиная с electron/ .

На Windows и Linux:

Then execute Electron.app on macOS, electron on Linux, or electron.exe on Windows, and Electron will start as your app. The electron directory will then be your distribution to deliver to users.

С архивом исходного кода приложения

Вместо того, чтобы отправлять ваше приложение, копируя все исходные файлы, вы можете запаковать ваше приложение в asar архив, чтобы улучшить производительность чтения файлов на платформах, таких как Windows, если вы еще не используете такой пакет как Parcel или Webpack.

Чтобы использовать архив asar для замены каталога app , необходимо переименовать архив в app.asar и положить его в каталог ресурсов Electron, как показано ниже, и Electron будет пытаться прочитать архив и начать с него.

На Windows и Linux:

Более подробную информацию об использовании asar вы можете найти в репозитории electron/asar .

Ребрендинг скачанных бинарных файлов

После построения вашего приложения в Electron и перед распространением вам следует провести его ребрендинг.

macOS

Вы можете переименовать Electron.app , а также вы должны переименовать поля CFBundleDisplayName , CFBundleIdentifier и CFBundleName в следующих файлах:

• Electron.app/Contents/Info.plist
• Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist

Вы также можете переименовать helper приложения, чтобы избежать показа Electron Helper в Activity Monitor, но убедитесь, что вы переименовали имя исполняемого файла helper приложения.

Структура переименования app будет такая:

Windows

Вы можете сменить имя файла electron.exe на любое понравившееся, отредактировать его значок и другую информацию такими инструментами, как rcedit.

Linux

Electron исполняемый файл можно переименовать на любое имя, которое вам нравится.

Проведите ребрендинг, пересобрав Electron из исходных кодов

Можно изменить бренд Electron путем изменения имени продукта и сборки его из исходных кодов. Для этого вам надо установить аргумент, отвечающий за имя продукта ( electron_product_name = «YourProductName» ) в файле args.gn и пересобрать Electron.

Copyright OpenJS Foundation and Electron contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Построение Electron приложения. Введение

Около года назад на Canonium вышла статья, в которой рассказывалось о построении node-webkit приложения. Эта статья стала одной из самых популярных у меня в блоге и даже пару раз мелькала в крупных пабликах в ВК, приводя всё больше и больше читателей.

С того времени изменилось многое: от Node.js отделился io.js, node-webkit сменил имя на nw.js, GitHub выпустил стабильную версию своего редактора кода Atom, а вскоре случилось явление Electron широкой публике.

Если говорить кратко, то Electron — это альтернатива NW.js, представляющая собой среду выполнения для построения настольных приложений, написанных, разумеется, на JavaScript.

Нужно заметить, что Electron предоставляет практически равные с NW.js возможности, кроме некоторых особенностей, о которых в рамках этой серии статей я говорить не буду. Следует сказать, что Electron обладает более сдержанной и качественной документацией, которую хочется читать, в отличие от того же NW.js.

Основные отличия

Далее Electron я буду называть «Электроном».

Ни для кого не секрет, что io.js вернулся в состав Node.js, который теперь регулируется Linux Foundation. Дело в том, что io.js сыграл злую шутку с NW.js, поманив его создателя на свою сторону. Создатели Электрона тоже не оставались в стороне, но, к счастью, уже успели вернуться на Node.js и успешно его поддерживают, в то время как NW.js 12-ой и 13-ой версии всё ещё базируются на io.js, причем не первой свежести.

В NW.js главный файл — это html-файл, указанный в package.json , в то же время в Электроне главным файлом является сценарий, написанный на JavaScript. Это позволяет писать приложения, скажем так, на более низком уровне, не прибегая лишний раз к скриптам в самом браузере. На самом деле, говорить так не совсем корректно, но таким образом упрощается маршрутизация по страницам внутри приложения. Как говорится в документации, в какой-то мере Электрон здесь представляет собой подобие Node.js.

GitHub создал Atom. Вместе с Atom родился Atom Shell. Atom Shell переродился в Электрон. В этой небольшой цепочке событий есть ключевое слово — GitHub. Да, Intel поддерживает NW.js, да, NW.js медленно, но развивается. Однако, GitHub будет поддерживать свою разработку столько, сколько будет существовать редактор Atom.

На самом деле, это не все отличия Электрона от NW.js, есть и другие — более технические. С полным списком можно ознакомиться в документации проекта.

Принцип работы

Принцип работы Электрона основан на двух типах процессов:

Первый тип — основной процесс, который отвечает за интеграцию и взаимодействие с GUI операционной системы. Под этим понятием скрывается интеграция в док на OS X или панель задач на Windows, а также сворачивание в трей, полноэкранный режим и прочие обыденные и нативные для ОС штуки. Такой процесс может быть запущен только один раз на всю жизнь приложения.

Второй тип — процесс рендеринга, отвечающий за отображение окна браузера, в котором с помощью одной магической строчки может быть открыта страница приложения или любая другая веб-страница. Таких процессов может быть произвольное число. За создание процесса рендеринга отвечает основной процесс.

Для того, чтобы породить основной процесс используется следующая схема рождения приложения:

• Электрон читает package.json и ищет в нём секцию main, в которой определен основной файл приложения. Этот файл далее в статье я буду называть «точкой входа».
• Затем происходит обработка «точки входа» и создаётся основной процесс, который в свою очередь, при желании разработчика, открывает какую-либо страницу или страницы, то есть создаёт окно браузера. А если говорить точнее, то порождает процесс или процессы рендеринга.

Если попытаться графически изобразить жизнь приложения, построенного на Электроне, то она будет иметь следующий вид:

Возможности Electron

Перед тем, как приступить к написанию js-файла, который будет выступать в роли точки входа для всего приложения, необходимо взглянуть на доступный разработчику API (набор модулей), чтобы позднее можно было ссылаться на модуль без приведения его описания.

Для компактности статьи я вынес описание доступных API Электрона версии 0.33.3 в отдельный Gist.

Настройка окружения

Думаю, не стоит упоминать, что для работы с Электроном вам нужен Node.js и пакетный менеджер npm актуальной версии. Кроме этого, я рекомендую глобально установить пакет electron-prebuilt, который позволит автоматически загружать актуальную версию Электрона и запускать приложения без необходимости предварительной сборки.

После установки пакет автоматически загрузит текущую стабильную версию Электрона. Теперь, для того, чтобы запустить приложение, необходимо всего лишь выполнить команду electron . в директории проекта. Для последующей автоматизации процесса разработки я советую добавить эту команду в секцию скриптов в package.json :

Эта запись даст возможность инициировать запуск приложения по команде npm start .

При желании можно загружать последнюю или любую другую версию Электрона вручную. Подробнее об этом написано в документации.

К слову, вы можете установить этот пакет локально, но в этом случае команда electron . преобразуется в страшный и некрасивый набор символов:

Кроме самого Электрона я также советую установить пакет XO, который является оберткой над ESLint:

ESLint является самым передовым линтером js-кода, разрабатываемый Николасом Закасом.

Настройка WebStorm

Из коробки WebStorm не умеет автоматически дополнять, предлагать методы, да и вообще работать с Electron. Чтобы исправить эту несправедливость нужно выполнить пару нехитрых операций.

Сначала необходимо перейти к настройке библиотек и фреймворков и, после этого, выбрать там наш любимый JavaScript:

Нажимаем кнопку Download и выбираем слева вверху канал пакетов TypeScript community stubs. Затем ищем в большом списке всякой всячины запись github-electron, выбираем её и кликаем на кнопку Download and install. Готово!

Для поиска по списку кликните на любом элементе списка и начните вводить интересующее вас слово.

Первое приложение

Первым шагом в начале разработки любого Node.js приложения будет создание файла package.json . Вы можете создать его в полуавтоматическом режиме с помощью команды npm init , отвечая на вопросы, или же вручную, добавив лишь самое нужное:

Так как я ещё не решил, что мы будем разрабатывать в течении всей серии статей, пока что приложение будет иметь имя app.

Теперь самое время выполнить команду, добавляющую в package.json поддержу js-линтера XO:

Эта команда автоматически добавит в package.json всё самое необходимое, а также установит локальную копию XO. Остаётся лишь добавить вызов XO в скрипт start, чтобы перед запуском приложения, написанный ранее js-код, всегда оставался чистым и хорошо пахнул:

Я также добавил и изменил несколько правил проверки кода, чтобы линтер соответствовал моим личным требованиям и был удобен в использовании.

Самое время создать какой-нибудь простенький html-файл, который в последствии будет загружаться при старте приложения. Как мне кажется, нет ничего лучше, чем вывести на экран версию Node.js, Electron и Chrome. Для этого обратимся к модулю process, который был расширен Electron. Теперь, помимо информации о текущем процессе, он также может предоставлять информацию о типе процесса (основной или рендер), версию Chrome и Electron, а также путь до исполняемого js-файла.

Забыл сказать, что при написании приложения я буду по возможности и желанию использовать некоторые фишки из ES2015 (ES6).

Файл main.js является «точкой входа» для всего приложения. В нём будут создаваться окна и обрабатываться системные события.

Сначала необходимо подключить модуль app, отвечающий за управление жизненным циклом приложения и browser-window, создающий новое окно браузера.

Далее создаётся ссылка на объект Window. Это делается для того, чтобы окно не закрывалось автоматически, когда объект будет обработан сборщиком мусора.

При закрытии всех окон приложения следует из него выйти. В OS X это событие является общим для приложений и их баров меню, поэтому здесь присутствует условие, отбрасывающее эту платформу.

После того, как Электрон полностью будет инициализирован, станет доступным API управления приложением. Ниже представлен код, который создаёт новое окно браузера размерами 800 на 600 пикселей. Затем в этом окне загружается ранее созданный нами html-файл.

Важно заметить, что даже если вы не загрузите ни один из html-файлов, процесс рендеринга всё равно будет запущен, так как ранее уже было создано окно браузера.

В конце вешается обработчик события closed, которое всплывает тогда, когда окно браузера уже было закрыто. После того, как вы получили данное событие, необходимо удалить ссылку на окно и больше его не использовать.

К слову, не стоит путать событие closed с похожим на него событием close, которое посылается, когда окно будет закрыто, то есть перед closed.

Вообще, тема событий в Электроне достойна отдельной статьи, но в силу моей лени, желающие могут обратиться к документации. Скажу лишь, что жизненный цикл приложения в событиях будет выглядеть следующим образом:

• will-finish-launching
• ready
• browser-window-created
• page-title-updated
• close
• before-quit
• will-quit
• quit
• window-all-closed
• closed

События, событиями, но вернемся к нашему приложению — самое время запустить его, используя команду npm start .

В итоге мы имеем окно, в котором отображается текущая версия Node.js, Electron и Chrome. Кроме того, окно приложениия имеет служебное меню с небольшим набором стандартных пунктов. Служебным оно называется из-за того, что после сборки проекта, как вы увидите позднее, оно исчезает.

Распространение приложения

В отличие от статьи про NW.js я дам самый необходимый материал сразу же в первой статье, чтобы самые активные читатели уже имели возможность начать изучать этот инструмент самостоятельно.

Для сборки приложения я предлагаю воспользоваться пакетом electron-packager. Сначала установим его глобально:

В этот раз мы обойдемся без планировщика задач, наподобие Grunt или Gulp. Мы же взрослые люди? — думаю, да!

Просто создадим новый скрипт build в package.json с таким содержанием:

Теперь, выполнив команду npm run build вы получите сборку своего приложения под операционную систему Windows. Если же вам необходима сборка под все три платформы, то команда будет иметь вид:

После сборки приложения под все три платформы будет создано, как это ни странно, пять директорий:

• app-darwin-x64
• app-linux-ia32
• app-linux-x64
• app-win32-ia32
• app-win32-x64

Но самое забавное, что полностью собранный «комплект» весит всего лишь каких-то жалких 500Мб.

Кроме явного указания имени приложения и версии Электрона в команде, можно воспользоваться данными из package.json . Создадим два поля, которые будут содержать имя публикуемого приложения и версию, с помощью которой необходимо будет собрать его:

После этого в команде станут доступны переменные:

Разумеется, что вам никто не запрещает использовать поле name как имя приложения:

В итоге команда может принять вид:

К сожалению, на Windows я так и не смог заставить electron-packager использовать $npm_package_* . Зато на OS X это замечательно работает.

Сейчас я предлагаю немного подробнее остановиться на аргументах, передаваемых в пакет electron-packager . Шаблон команды выглядит следующим образом:

Доступные для пользователя аргументы:

Обязательные

• platform — платформа ( all или win32 , linux , darwin )
• arch — разрядность ( all или ia32 , x64 )
• version — версия Электрона для сборки

Опциональные

• all — эквивалент —platform=all —arch=all
• out — директория, в которую будут помещены сборки
• icon — иконка приложения ( .icns или .ico )
• app-bundle-id — идентификатор приложения в plist
• app-version — версия приложения
• build-version — версия сборки приложения для OS X
• cache — директория, в которой будет располагаться кэш приложения
• helper-bundle-id — идентификатор приложения для помощника plist
• ignore — исключение файлов из сборки
• prune — запуск команды npm prune —production в приложении
• overwrite — перезапись уже созданных сборок
• asar — упаковка исходников приложения в asar-архив
• asar-unpack — распаковка указанных файлов в директорию app.asar.unpacked
• sign — идентификатор для входа в codesign (OS X)
• version-string — ключи для сборки (Windows). Список ключей смотрите в документации пакета

О том, как добавлять иконки, что вообще следует делать перед распространением приложения и как создать установщик для сборки, я расскажу в заключительной части этой серии статей.

Список литературы

По традиции оставляю ссылки на то, что можно почитать, чтобы расширить свой кругозор в рамках этой статьи. На русском языке ничего нет, так как у нас Электрон как-то не особо популярен.

Статьи

Модули

Делимся на оплату хостинга или кофе.
Чем чаще пью кофе, тем чаще пишу статьи.