mirror of
https://github.com/vector-im/element-desktop.git
synced 2024-09-05 03:50:06 +00:00
224 lines
7.9 KiB
Markdown
224 lines
7.9 KiB
Markdown
Element Desktop
|
|
===============
|
|
|
|
Element Desktop is a Matrix client for desktop platforms with Element Web at its core.
|
|
|
|
First Steps
|
|
===========
|
|
Before you do anything else, fetch the dependencies:
|
|
|
|
```
|
|
yarn install
|
|
```
|
|
|
|
Fetching Element
|
|
================
|
|
Since this package is just the Electron wrapper for Element Web, it doesn't contain any of the Element Web code,
|
|
so the first step is to get a working copy of Element Web. There are a few ways of doing this:
|
|
|
|
```
|
|
# Fetch the prebuilt release Element package from the element-web GitHub releases page. The version
|
|
# fetched will be the same as the local element-desktop package.
|
|
# We're explicitly asking for no config, so the packaged Element will have no config.json.
|
|
yarn run fetch --noverify --cfgdir ""
|
|
```
|
|
|
|
...or if you'd like to use GPG to verify the downloaded package:
|
|
```
|
|
# Fetch the Element public key from the element.io web server over a secure connection and import
|
|
# it into your local GPG keychain (you'll need GPG installed). You only need to to do this
|
|
# once.
|
|
yarn run fetch --importkey
|
|
# Fetch the package and verify the signature
|
|
yarn run fetch --cfgdir ""
|
|
```
|
|
|
|
...or either of the above, but fetching a specific version of Element:
|
|
```
|
|
# Fetch the prebuilt release Element package from the element-web GitHub releases page. The version
|
|
# fetched will be the same as the local element-desktop package.
|
|
yarn run fetch --noverify --cfgdir "" v1.5.6
|
|
```
|
|
|
|
If you only want to run the app locally and don't need to build packages, you can
|
|
provide the `webapp` directory directly:
|
|
```
|
|
# Assuming you've checked out and built a copy of element-web in ../element-web
|
|
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).
|
|
|
|
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'.
|
|
|
|
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:
|
|
|
|
```
|
|
yarn run build
|
|
```
|
|
This will do a couple of things:
|
|
* Run the `setversion` script to set the local package version to match whatever
|
|
version of Element you installed above.
|
|
* 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.
|
|
|
|
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
|
|
|
|
yarn run docker:install
|
|
# if you want to build the native modules (this will take a while)
|
|
yarn run docker:build:native
|
|
yarn run docker:build
|
|
```
|
|
|
|
After running, the packages should be in `dist/`.
|
|
|
|
Starting
|
|
========
|
|
If you'd just like to run the electron app locally for development:
|
|
```
|
|
# Install electron - we don't normally need electron itself as it's provided
|
|
# by electron-builder when building packages
|
|
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
|
|
config directory and place `config.json` in there, then specify this directory
|
|
with the `--cfgdir` option to `yarn run fetch`, eg:
|
|
```
|
|
mkdir myconfig
|
|
cp /path/to/my/config.json myconfig/
|
|
yarn run fetch --cfgdir myconfig
|
|
```
|
|
The config dir for the official Element app is in `element.io`. If you use this,
|
|
your app will auto-update itself using builds from element.io.
|
|
|
|
Profiles
|
|
========
|
|
|
|
To run multiple instances of the desktop app for different accounts, you can
|
|
launch the executable with the `--profile` argument followed by a unique
|
|
identifier, e.g `element-desktop --profile Work` for it to run a separate profile and
|
|
not interfere with the default one.
|
|
|
|
Alternatively, a custom location for the profile data can be specified using the
|
|
`--profile-dir` flag followed by the desired path.
|
|
|
|
User-specified config.json
|
|
==========================
|
|
|
|
+ `%APPDATA%\$NAME\config.json` on Windows
|
|
+ `$XDG_CONFIG_HOME\$NAME\config.json` or `~/.config/$NAME/config.json` on Linux
|
|
+ `~/Library/Application Support/$NAME/config.json` on macOS
|
|
|
|
In the paths above, `$NAME` is typically `Element`, unless you use `--profile
|
|
$PROFILE` in which case it becomes `Element-$PROFILE`, or it is using one of
|
|
the above created by a pre-1.7 install, in which case it will be `Riot` or
|
|
`Riot-$PROFILE`.
|
|
|
|
Translations
|
|
==========================
|
|
|
|
To add a new translation, head to the [translating doc](https://github.com/vector-im/element-web/blob/develop/docs/translating.md).
|
|
|
|
For a developer guide, see the [translating dev doc](https://github.com/vector-im/element-web/blob/develop/docs/translating-dev.md).
|
|
|
|
[<img src="https://translate.element.io/widgets/element-desktop/-/multi-auto.svg" alt="translationsstatus" width="340">](https://translate.element.io/engage/element-desktop/?utm_source=widget)
|
|
|
|
Report bugs & give feedback
|
|
==========================
|
|
|
|
If you run into any bugs or have feedback you'd like to share, please let us know on GitHub.
|
|
|
|
To help avoid duplicate issues, please [view existing issues](https://github.com/vector-im/element-web/issues?q=is%3Aopen+is%3Aissue+sort%3Areactions-%2B1-desc) first (and add a +1) or [create a new issue](https://github.com/vector-im/element-web/issues/new/choose) if you can't find it. Please note that this issue tracker is associated with the [element-web](https://github.com/vector-im/element-web) repo, but is also applied to the code in this repo as well.
|