The Hyperspace Desktop source code also includes the necessary tools to start building the desktop app versions of Hyperspace using technologies like Electron. This document will cover how to get started building the desktop versions.
Requirements
- Git
- Node.js 8 or higher
Gather the source materials
To get started, either download the Hyperspace source code for the intended release (v1.x.x) or clone straight from GitHub:
git clone https://github.com/hyperspacedev/hyperspace.git
Then, proceed to install the project’s dependencies:
cd hyperspace
npm install
The project should now contain all of the necessary Node modules to build the desktop apps.
Note: If the dependency list includes
[email protected]
, you’ll need to modify a file to get notarization and code signing working if you plan to build for macOS. Learn more ›
Gather macOS development materials
If you are building for macOS and are on a Mac, you’ll need to download the respective certificates, provisioning profiles, and entitlements lists. You can generate these certificates and profiles on the Apple Developer website. You’ll need the following in the desktop
directory:
- Provisioning profiles for the desktop (
nonmas.provisionprofile
) and Mac App Store version (embedded.provisionprofile
). - An
info.plist
that includes the team identifier and group identifier.
Additionally, you’ll need to set up your keychain to store your App Store Connect password. You can learn more on Electron’s documentation.
Entitlements
You’ll also need to create entitlements files in the desktop
directory that list the following entitlements for your app:
com.apple.security.files.downloads.read-write
com.apple.security.files.user-selected.read-write
com.apple.security.allow-unsigned-executable-memory
For the Mac App Store, you’ll need extra entitlements due to the sandboxed environment:
com.apple.security.app-sandbox
com.apple.security.files.downloads.read-write
com.apple.security.files.user-selected.read-write
com.apple.security.allow-unsigned-executable-memory
com.apple.security.network.client
For the child entitlements on the Mac App Store (inherited entitlements.mas.inherit.plist
):
com.apple.security.app-sandbox
com.apple.security.inherit
com.apple.security.files.downloads.read-write
com.apple.security.files.user-selected.read-write
com.apple.security.allow-unsigned-executable-memory
com.apple.security.network.client
⚠️ Note that the inherited permissions are the same as that of the parent. This is due to an issue where the hardened runtime fails to pass down the inherited properties (see electron/electron#20560). This might change in future versions of macOS.
Building the desktop apps
Before starting to build the desktop apps, you need to modify config.json
to tell it to use the desktop URL. In public/config.json
, change the location
field to the following:
"location": "desktop",
To build all of the desktop apps at once, you can run the following:
npm run build-desktop
This will proceed to build and sign the Windows, macOS, and Linux builds for you.
Building specific apps
To build for a specific platform, you’ll need to first build the project:
npm run build
And then run any of the following commands below:
npm run build-desktop-win
: Builds the desktop app for Windows.npm run build-desktop-darwin
: Builds the desktop apps for macOS (eg. disk image, Mac App Store).npm run build-desktop-linux
: Builds the desktop apps for Linux (eg. Debian package, AppImage, and Snap).npm run build-desktop-linux-select
: Builds the desktop app for Linux. Target is required as a parameter.
The built products for any command will appear in dist
.
macOS Notarization
Starting with macOS 10.15 Catalina, apps are required to be signed and notarized. The Hyperspace source code includes the proper tools to enable notarization and should be handled whenever you run build-desktop
or build-desktop-darwin
. You’ll want to modify desktop/notarize.js
and change the username, account, and app identifier fields to match your app’s information. As an example:
return await notarize({
appBundleId: 'com.example.hyperspace-clone',
appPath: `${appOutDir}/${appName}.app`,
appleId: "[email protected]",
appleIdPassword: password,
ascProvider: "XXXXXXXXXXX"
});