2020-07-01 14:30:53 +00:00
Element Desktop
===============
2019-12-06 18:20:31 +00:00
2020-07-01 16:42:24 +00:00
Element Desktop is a Matrix client for desktop platforms with Element Web at its core.
2019-12-12 19:33:29 +00:00
2020-07-15 11:53:50 +00:00
First Steps
===========
Before you do anything else, fetch the dependencies:
```
yarn install
```
2020-07-01 14:30:53 +00:00
Fetching Element
================
2020-07-01 16:42:39 +00:00
Since this package is just the Electron wrapper for Element Web, it doesn't contain any of the Element Web code,
2020-07-01 16:42:50 +00:00
so the first step is to get a working copy of Element Web. There are a few ways of doing this:
2019-12-12 19:33:29 +00:00
```
2020-08-03 15:05:04 +00:00
# Fetch the prebuilt release Element package from the element-web GitHub releases page. The version
2020-07-01 14:30:53 +00:00
# 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.
2019-12-13 11:13:44 +00:00
yarn run fetch --noverify --cfgdir ''
2019-12-12 19:33:29 +00:00
```
...or if you'd like to use GPG to verify the downloaded package:
```
2020-07-01 16:44:40 +00:00
# Fetch the Element public key from the element.io web server over a secure connection and import
2019-12-12 19:33:29 +00:00
# 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
2019-12-13 11:13:44 +00:00
yarn run fetch --cfgdir ''
2019-12-12 19:33:29 +00:00
```
2020-07-01 14:30:53 +00:00
...or either of the above, but fetching a specific version of Element:
2019-12-12 19:33:29 +00:00
```
2020-08-03 15:05:04 +00:00
# Fetch the prebuilt release Element package from the element-web GitHub releases page. The version
2020-07-01 14:30:53 +00:00
# fetched will be the same as the local element-desktop package.
2019-12-13 11:13:44 +00:00
yarn run fetch --noverify --cfgdir '' v1.5.6
2019-12-12 19:33:29 +00:00
```
If you only want to run the app locally and don't need to build packages, you can
provide the `webapp` directory directly:
```
2020-08-03 15:05:04 +00:00
# Assuming you've checked out and built a copy of element-web in ../element-web
ln -s ../element-web/webapp ./
2019-12-12 19:33:29 +00:00
```
[TODO: add support for fetching develop builds, arbitrary URLs and arbitrary paths]
Building
========
2020-07-01 14:30:53 +00:00
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.
2019-12-12 19:33:29 +00:00
2020-07-31 20:04:54 +00:00
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). If you don't need these features, you can skip this
step.
```
yarn run build:native
```
On Windows, this will automatically determine the architecture to build for based
on the environment (ie. set up by vcvarsall.bat).
Now you can build the package:
2019-12-12 19:33:29 +00:00
```
yarn run build
```
This will do a couple of things:
* Run the `setversion` script to set the local package version to match whatever
2020-07-01 14:30:53 +00:00
version of Element you installed above.
2019-12-12 19:33:29 +00:00
* Run electron-builder to build a package. The package built will match the operating system
you're running the build process on.
2020-02-19 14:21:33 +00:00
If you're on Windows, you can choose to build specifically for 32 or 64 bit:
```
yarn run build32
```
or
```
yarn run build64
```
This build step will not build any native modules.
2019-12-12 19:33:29 +00:00
You can also build using docker, which will always produce the linux package:
```
2020-02-17 20:10:58 +00:00
# Run this once to make the docker image
yarn run docker:setup
2019-12-13 12:18:32 +00:00
yarn run docker:install
2020-02-17 20:25:10 +00:00
# if you want to build the native modules (this will take a while)
2021-03-25 15:40:47 +00:00
yarn run docker:build:native
2019-12-13 12:18:32 +00:00
yarn run docker:build
2019-12-12 19:33:29 +00:00
```
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
```
2019-12-13 11:13:44 +00:00
Config
======
2020-07-01 14:30:53 +00:00
If you'd like the packaged Element to have a configuration file, you can create a
2019-12-13 11:13:44 +00:00
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
```
2020-08-03 15:05:04 +00:00
The config dir for the official Element app is in `element.io` . If you use this,
2020-07-01 14:30:53 +00:00
your app will auto-update itself using builds from element.io.
2020-05-06 10:19:08 +00:00
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
2020-07-01 14:30:53 +00:00
identifier, e.g `element-desktop --profile Work` for it to run a separate profile and
2020-05-06 10:19:08 +00:00
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
2020-05-31 16:25:26 +00:00
+ `~/Library/Application Support/$NAME/config.json` on macOS
2020-05-06 10:19:08 +00:00
2020-07-01 14:30:53 +00:00
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` .
2020-07-15 16:25:02 +00:00
2021-04-26 13:19:48 +00:00
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-web/-/multi-auto.svg" alt="translationsstatus" width="340"> ](https://translate.element.io/engage/element-web/?utm_source=widget )
2020-07-15 16:25:02 +00:00
Report bugs & give feedback
==========================
If you run into any bugs or have feedback you'd like to share, please let us know on GitHub.
2020-09-28 10:37:34 +00:00
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.