From f0107d64a9e568d6fa269f8b621938907b71df62 Mon Sep 17 00:00:00 2001 From: James Salter Date: Wed, 16 Feb 2022 11:25:14 +0000 Subject: [PATCH] Refactor the build docs into something easier to follow (#324) * Refactor the build docs into something easier to follow * fix typo --- README.md | 91 +++-------------------------------- docs/native-node-modules.md | 95 +++++++++++++++++++++++++++++++++---- 2 files changed, 93 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index d2fe695..2e28d36 100644 --- a/README.md +++ b/README.md @@ -49,30 +49,17 @@ ln -s ../element-web/webapp ./ [TODO: add support for fetching develop builds, arbitrary URLs and arbitrary paths] - Building ======== -Now you have a copy of Element, you're ready to build packages. If you'd just like to -run Element locally, skip to the next section. -If you'd like to build the native modules (for searching in encrypted rooms and -secure storage), do this first. This will take 10 minutes or so, and will -require a number of native tools to be installed, depending on your OS (eg. -rust, tcl, make/nmake). +## Native Build -You'll also to need to make sure you've built the native modules for the same -architecture as your package, so for anything more advanced than just building -the modules and app for the host architecture see 'Other Architectures'. +TODO: List native pre-requisites -If you don't need these features, you can skip this step. - -To just build these for your native architecture: -``` -yarn run build:native -``` - -Now you can build the package: +Optionally, [build the native modules](https://github.com/vector-im/element-desktop/blob/develop/docs/native-node-modules.md), +which include support for searching in encrypted rooms and secure storage. Skipping this step is fine, you just won't have those features. +Then, run ``` yarn run build ``` @@ -82,9 +69,9 @@ This will do a couple of things: * Run electron-builder to build a package. The package built will match the operating system you're running the build process on. -This build step will not build any native modules. +## Docker -You can also build using docker, which will always produce the linux package: +Alternatively, you can also build using docker, which will always produce the linux package: ``` # Run this once to make the docker image yarn run docker:setup @@ -107,70 +94,6 @@ yarn add electron yarn start ``` -Other Architectures -=================== -Building the native modules will build for the host architecture (and only the -host architecture) by default. On Windows, this will automatically determine -the architecture to build for based on the environment. Make sure that you have -all the [tools required to perform the native modules build](docs/windows-requirements.md) - - -On macOS, you can build universal native modules too: -``` -yarn run build:native:universal -``` - -...or you can build for a specific architecture: -``` -yarn run build:native --target x86_64-apple-darwin -``` -or -``` -yarn run build:native --target aarch64-apple-darwin -``` - -You'll then need to create a built bundle with the same architecture. -To bundle a universal build for macOS, run: - -``` -yarn run build:universal -``` - -If you're on Windows, you can choose to build specifically for 32 or 64 bit: -``` -yarn run build:32 -``` -or -``` -yarn run build:64 -``` - -Note that the native module build system keeps the different architectures -separate, so you can keep native modules for several architectures at the same -time and switch which are active using a `yarn run hak copy` command, passing -the appropriate architectures. This will error if you haven't yet built those -architectures. eg: - -``` -yarn run build:native --target x86_64-apple-darwin -# We've now built & linked into place native modules for Intel -yarn run build:native --target aarch64-apple-darwin -# We've now built Apple Silicon modules too, and linked them into place as the active ones - -yarn run hak copy --target x86_64-apple-darwin -# We've now switched back to our Intel modules -yarn run hak copy --target x86_64-apple-darwin --target aarch64-apple-darwin -# Now our native modules are universal x86_64+aarch64 binaries -``` - -The current set of native modules are stored in `.hak/hakModules`, -so you can use this to check what architecture is currently in place, eg: - -``` -$ lipo -info .hak/hakModules/keytar/build/Release/keytar.node -Architectures in the fat file: .hak/hakModules/keytar/build/Release/keytar.node are: x86_64 arm64 -``` - Config ====== If you'd like the packaged Element to have a configuration file, you can create a diff --git a/docs/native-node-modules.md b/docs/native-node-modules.md index 8a3904e..b6270a7 100644 --- a/docs/native-node-modules.md +++ b/docs/native-node-modules.md @@ -10,20 +10,26 @@ modules from source to ensure we can trust the compiled output. In the future, we may offer a pre-compiled path for those who want to use these features in a custom build of Element without installing the various build tools required. -Do note that compiling a module for a particular operating system -(Linux/macOS/Windows) will need to be done on that operating system. -Cross-compiling from a host OS for a different target OS may be possible, but -we don't support this flow with Element dependencies at this time. - The process is automated by [vector-im/element-builder](https://github.com/vector-im/element-builder) -when releasing. -The following sections explain the manual steps you can use with a custom build of Element to enable -these features if you'd like to try them out. -It is possible to [build those native modules locally automatically](https://github.com/vector-im/element-desktop#building). +when releasing. +## Building + +Install the pre-requisites for your system: + +* [Windows pre-requisites](https://github.com/vector-im/element-desktop/blob/develop/docs/windows-requirements.md) +* Linux: TODO +* OS X: TODO + +Then optionally, [add seshat and dependencies to support search in E2E rooms](#Adding Seshat for search in E2E encrypted rooms). + +Then, to build for an architecture selected automatically based on your system (recommended), run: ``` yarn run build:native ``` + +If you need to build for a specific architecture, see [here](#Compiling for specific architectures). + ## Adding Seshat for search in E2E encrypted rooms Seshat is a native Node module that adds support for local event indexing and @@ -59,3 +65,74 @@ After this is done the Electron version of Element can be run from the main fold as usual using: yarn start + +## Compiling for specific architectures + +### macOS + +On macOS, you can build universal native modules too: +``` +yarn run build:native:universal +``` + +...or you can build for a specific architecture: +``` +yarn run build:native --target x86_64-apple-darwin +``` +or +``` +yarn run build:native --target aarch64-apple-darwin +``` + +You'll then need to create a built bundle with the same architecture. +To bundle a universal build for macOS, run: + +``` +yarn run build:universal +``` + +### Windows + +If you're on Windows, you can choose to build specifically for 32 or 64 bit: +``` +yarn run build:32 +``` +or +``` +yarn run build:64 +``` + +### Cross compiling + +Compiling a module for a particular operating system (Linux/macOS/Windows) needs +to be done on that operating system. Cross-compiling from a host OS for a different +target OS may be possible, but we don't support this flow with Element dependencies +at this time. + +### Switching between architectures + +The native module build system keeps the different architectures +separate, so you can keep native modules for several architectures at the same +time and switch which are active using a `yarn run hak copy` command, passing +the appropriate architectures. This will error if you haven't yet built those +architectures. eg: + +``` +yarn run build:native --target x86_64-apple-darwin +# We've now built & linked into place native modules for Intel +yarn run build:native --target aarch64-apple-darwin +# We've now built Apple Silicon modules too, and linked them into place as the active ones + +yarn run hak copy --target x86_64-apple-darwin +# We've now switched back to our Intel modules +yarn run hak copy --target x86_64-apple-darwin --target aarch64-apple-darwin +# Now our native modules are universal x86_64+aarch64 binaries +``` + +The current set of native modules are stored in `.hak/hakModules`, +so you can use this to check what architecture is currently in place, eg: + +``` +$ lipo -info .hak/hakModules/keytar/build/Release/keytar.node +Architectures in the fat file: .hak/hakModules/keytar/build/Release/keytar.node are: x86_64 arm64 +```