diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..f2068846 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,240 @@ +# Installation + +Instructions and releases are currently only available for Linux, +but compiling on Windows and macOS should be possible with the right tools. + +- [Releases](#releases) + - [Linux](#linux) +- [Manual installation](#manual-installation) + - [Environment variables](#environment-variables) + - [Package manager dependencies](#package-manager-dependencies) + - [Alpine Linux 3.9+ / apk](#alpine-linux-39--apk) + - [Arch Linux / pacman & AUR](#arch-linux--pacman--aur) + - [Fedora 30+ / dnf](#fedora-30--dnf) + - [Ubuntu 19.04 / apt](#ubuntu-1904--apt) + - [Ubuntu 19.10+, Debian bullseye / apt](#ubuntu-1910-debian-bullseye--apt) + - [Void Linux / xbps](#void-linux--xbps) + - [Installing PyOtherSide manually](#installing-pyotherside-manually) + - [Installing libolm manually](#installing-libolm-manually) + - [Installing Mirage](#installing-mirage) +- [Common issues](#common-issues) + - [cffi version mismatch](#cffi-version-mismatch) + - [Component is not ready](#component-is-not-ready) + + +## Releases + +### Linux + +For **x86 64bit glibc-based systems**, Mirage is available as an **AppImage** +on the [release page](releases). +For other architectures and musl-based distros, see the +[manual installation section](#manual-installation). + +AppImages are single executable files that contain the app and all +its dependencies. +Mirage images are built in Ubuntu 16.04, and should therefore run on any distro +released in 2016 or later. + +To run from a terminal: + +```sh +chmod +x Mirage-x86_64.AppImage +./Mirage-x86_64.AppImage +``` + +To run from a file manager, give executable permission in the file's +properties and double-click to launch. +[More detailed instructions](https://docs.appimage.org/introduction/quickstart.html#ref-quickstart) + + +## Manual installation + +Qt 5.12+, Python 3.6+ (with development headers and pip), +PyOtherSide 1.5+ and libolm 3+ are required. + +### Environment variables + +To ensure Qt **5** will be used by default, compile using all CPU cores and +optimize the build for your machine: + +```sh +export QT_SELECT=5 +export MAKEFLAGS="-j$(nproc)" +export CFLAGS="-march=native -O2 -pipe" +``` + +### Package manager dependencies + +#### Alpine Linux 3.9+ / apk + +[PyOtherSide](#installing-pyotherside-manually) and +[libolm](#installing-libolm-manually) must be manually installed. + +```sh +sudo apk add qt5-qtquickcontrols2-dev qt5-qtsvg-dev qt5-qtimageformats \ + python3-dev py3-setuptools \ + build-base git cmake \ + libjpeg-turbo-dev zlib-dev tiff-dev libwebp-dev openjpeg-dev \ + libmediainfo-dev +export PATH="/usr/lib/qt5/bin:$PATH" +``` + +#### Arch Linux / pacman & AUR + +**libolm** is from the AUR, this example uses +[yay](https://github.com/Jguer/yay) to install it like other packages. +Alternatively, you can just use `pacman` and +[install libolm manually](#installing-libolm-manually). + +```sh +yay -Syu qt5-base qt5-declarative qt5-quickcontrols2 qt5-svg \ + qt5-graphicaleffects qt5-imageformats \ + python python-pip \ + python-pyotherside \ + libolm \ + base-devel git cmake \ + libjpeg-turbo zlib libtiff libwebp openjpeg2 libmediainfo +``` + +#### Fedora 30+ / dnf + +[PyOtherSide](#installing-pyotherside-manually) and +[libolm](#installing-libolm-manually) must be manually installed. + +```sh +sudo dnf groupinstall 'Development Tools' +sudo dnf install qt5-devel qt5-qtbase qt5-qtdeclarative qt5-qtquickcontrols2 \ + qt5-qtsvg qt5-qtgraphicaleffects qt5-qtimageformats \ + python3-devel python3-pip \ + git cmake \ + libjpeg-turbo-devel zlib-devel libtiff-devel libwebp-devel \ + openjpeg2-devel libmediainfo-devel +sudo ln -s /usr/bin/qmake-qt5 /usr/bin/qmake +``` + +#### Ubuntu 19.04 / apt + +[libolm](#installing-libolm-manually) must be manually installed. + + +```sh +sudo apt update +sudo apt install qt5-default qt5-qmake qt5-image-formats-plugins \ + qml-module-qtquick2 qml-module-qtquick-window2 \ + qml-module-qtquick-layouts qml-module-qtquick-dialogs \ + qml-module-qt-labs-platform \ + qtdeclarative5-dev \ + qtquickcontrols2-5-dev \ + python3-dev python3-pip \ + qml-module:io-thp-pyotherside \ + build-essential git cmake \ + libjpeg-turbo8-dev zlib1g-dev libtiff5-dev libwebp-dev \ + libopenjp2-7-dev libmediainfo-dev +``` + +#### Ubuntu 19.10+, Debian bullseye / apt + +Follow the steps for [Ubuntu 19.04](#ubuntu-1904--apt), but instead of +installing libolm manually: + +```sh +sudo apt install libolm-dev +``` + +#### Void Linux / xbps + +[PyOtherSide](#installing-pyotherside-manually) must be manually installed. + +```sh +sudo xbps-install -Su qt5-devel qt5-declarative-devel \ + qt5-quickcontrols2-devel \ + qt5-svg-devel qt5-graphicaleffects qt5-imageformats \ + python3-devel python3-pip \ + olm-devel \ + base-devel git cmake \ + libjpeg-turbo-devel zlib-devel tiff-devel libwebp-devel \ + libopenjpeg2-devel libmediainfo-devel +``` + +### Installing PyOtherSide manually + +Skip this section if you already installed it from your +distro's package manager. + +```sh +git clone https://github.com/thp/pyotherside +cd pyotherside +make clean +qmake +make +sudo make install +``` + +### Installing libolm manually + +Skip this section if you already installed it from your +distro's package manager. + +```sh +git clone https://gitlab.matrix.org/matrix-org/olm/ +cd olm +cmake . -Bbuild +cmake --build build +sudo make install +``` + + +## Installing Mirage + +After following the above sections instructions depending on your system, +clone the repository, install the python dependencies, compile and install: + +```sh +git clone --recursive https://github.com/mirukan/mirage +cd mirage +pip3 install --user -Ur requirements.txt +pip3 install --user -U uvloop==0.14.0 + +qmake mirage.pro +make +sudo make install +``` + +`uvloop` brings performance improvements, but can be skipped +if you have trouble installing it. + +If everything went fine, run `mirage` to start. + + +## Common issues + +### cffi version mismatch + +When installing the python dependencies, if you get a version mismatch error +related to `cffi`, try: + +```sh +pip3 install --user --upgrade --force-reinstall cffi +``` + +### Component is not ready + +If the application doesn't start when you run `mirage` and shows a +`QQmlComponent: Component is not ready` message in the terminal, +a QML component failed to import due to either missing dependencies +or a programming error. + +If PyOtherSide is correctly installed, you should see a similar message: + + Got library name: "/usr/lib/qt5/qml/io/thp/pyotherside/libpyothersideplugin.so" + +If not, verify the installed files and their permissions. +To ensure the correct permissions are set for the PyOtherSide plugin files: + + sudo chmod -R 755 /usr/lib/qt5/qml/io + sudo chmod 644 /usr/lib/qt5/qml/io/thp/pyotherside/* + sudo chmod 755 /usr/lib/qt5/qml/io/thp/pyotherside/*.so + +Note that the Qt lib path might be `/usr/lib/qt/` instead of `/usr/lib/qt5/`, +depending on the distro. diff --git a/README.md b/README.md index 40950490..78544595 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,121 @@ -# Mirage +# Mirage ![Latest release](https://img.shields.io//github/v/release/mirukan/mirage) + +[Features](#currently-implemented-features) ⬥ +[Installation](INSTALL.MD) ⬥ +[Configuration & theming](#configuration-and-theming) ⬥ +[More screenshots](#more-screenshots) + +A fancy [matrix](https://matrix.org/) chat client for secure, +decentralized communication with an emphasis on user experience +and customization. **Currently in alpha**. + +![Chat screenshot](extra/general/screenshots/01-chat.png?raw=true) + +## Currently implemented features + +### Client + +- **Fluid interface** that adapts to any window size +- Customizable **keyboard shortcuts** for (almost) everything, including + filtering and switching rooms, scrolling, sending files... +- Versatile **theming system**, properties can refer to each others and have + any valid ECMAScript 7 expression as value + - Comes by default with **dark and transparent themes** +- **Multiple accounts** in one client + +### Profile + +- Set your display name and profile picture +- Import/export **E2E** key files + +### Rooms + +- Create, join, leave and forget rooms +- Send, accept and refuse invites + +### Messages + +- Send and receive **E2E encrypted messages** +- Send and receive emote messages (e.g. `/me reads attentively`) +- Receive notice (bot) messages +- Send **markdown** formatted messages + - Additional syntax for **coloring** text, e.g. `(Some text...)` - + [SVG/CSS color names](https://www.december.com/html/spec/colorsvg.html), + and `#hex` codes can be used +- Send and receive normal or **E2E encrypted files** +- Client-side Matrix & HTTP URL **image previews**, including animated GIF + +### Presence + +- Typing notifications + +## Installation + +See [INSTALL.MD](INSTALL.MD). + +## Configuration and theming + +The config file can be found at *$XDG_CONFIG_HOME/mirage/settings.json*, +or *~/.config/mirage/settings.json*. + +The `theme` setting can be: + +- The name of a built-in theme (`Midnight` or `Glass`) +- The filename without extension of a custom theme at + *$XDG_DATA_HOME/mirage/themes*, or *~/.local/share/mirage/themes* + +A default theme from this repository can be copied to use as a base and edit, +for example: + +```sh + cp mirage/src/themes/Midnight.qpl \ + "${XDG_DATA_HOME:-$HOME/.local/share}/mirage/themes/MyTheme.qpl" +``` + +The config setting `theme` would need to be set to `MyTheme` in this case. + +Theme files are nested-by-indentations sections of properties and values. +Properties are declared as ` : `. +Values can be any JavaScript (ECMAScript 7) expressions. + +Most of the properties are of type `color`. +Their values, if not just refering to another property, +can be expressed with a: +- [SVG/CSS color name](https://www.december.com/html/spec/colorsvg.html) + string, e.g. `"blue"` +- hexadecimal code string, e.g. `"#fff"` or `"#cc0000"` +- RGBA value, using the `Qt.rgba(0-1, 0-1, 0-1, 0-1)` function +- HSLA value, using the `Qt.hsla(0-1, 0-1, 0-1, 0-1)` function +- HSVA value, using the `Qt.hsva(0-1, 0-1, 0-1, 0-1)` function +- [HSLUV](https://www.hsluv.org/) value, using the + `hsluv(0-360, 0-100, 0-100, 0-1)` function. This is the prefered method + used throughout the default theme files + (why? see [this](https://www.hsluv.org/comparison/#rainbow-hsluv) and + [that](https://www.boronine.com/2012/03/26/Color-Spaces-for-Human-Beings/#hsl-is-a-lemon)) + +If you just want to change the background picture, +or use a gradient/simple color instead, search for the `ui:` section in your +text editor. -## Dependencies setup +With `Alt+Shift+R` by default, the config and theme can be reloaded without +restarting the app. -From your distribution's package manager, install: +**Warnings**: -Qt 5.12+, including: -- qt5-declarative-devel -- qt5-quickcontrols2-devel -- qt5-svg-devel -- qt5-graphicaleffects -- qt5-qmake -- qt5-devel +- API currently unstable: theme properties are often renamed, added or deleted. +- The file format for both config and themes will soon change +- The current file format currently forces all theme to have all properties + defined, instead of being able to only specify the ones to override from the + default theme. -- python3 -- python3-devel -- olm-python3 >= 3.1 +GUI settings will also be implemented in the future. -Make sure that the right version of Qt is selected and compiler flags are -correctly set: +## More screenshots - export QT_SELECT=5 - export CFLAGS="-march=native -O2 -pipe" - export CXXFLAGS="$CFLAGS" - export MAKEFLAGS="$(nproc)" +![Sign-in](extra/general/screenshots/02-sign-in.png) +![Account settings](extra/general/screenshots/03-account-settings.png) +![Room creation](extra/general/screenshots/04-create-room.png) +![Main pane in small window](extra/general/screenshots/05-main-pane-small.png) +![Chat in small window](extra/general/screenshots/06-chat-small.png) -Install [pyotherside](https://github.com/thp/pyotherside): - - git clone https://github.com/thp/pyotherside - cd pyotherside - make clean; qmake && make && sudo make install - -After this, verify the permissions of the installed plugin files. -To ensure that they're correctly set: - - sudo chmod -R 755 /usr/lib/qt5/qml/io - sudo chmod 644 /usr/lib/qt5/qml/io/thp/pyotherside/* - sudo chmod 755 /usr/lib/qt5/qml/io/thp/pyotherside/*.so - -Install the Python 3 dependencies: - - pip3 install --user -Ur requirements.txt - -Optional dependency for performance improvements: - - pip3 install --user -U uvloop==0.13.0 - - -## Building - - git clone --recursive - cd mirage - qmake mirage.pro && make && sudo make install - -After this if no errors happened, run `mirage`. - -If you get a version mismatch error related to cffi, try: - - pip3 install --user --upgrade --force-reinstall cffi diff --git a/TODO.md b/TODO.md index 38894ac5..64d95261 100644 --- a/TODO.md +++ b/TODO.md @@ -4,7 +4,6 @@ - page back buttons - Add Gentoo instructions -- Finish the README.md - Build final AppImage and test media opening ## Refactoring diff --git a/extra/general/screenshots/01-chat.png b/extra/general/screenshots/01-chat.png new file mode 100644 index 00000000..47d71a9a Binary files /dev/null and b/extra/general/screenshots/01-chat.png differ diff --git a/extra/general/screenshots/02-sign-in.png b/extra/general/screenshots/02-sign-in.png new file mode 100644 index 00000000..579c64ab Binary files /dev/null and b/extra/general/screenshots/02-sign-in.png differ diff --git a/extra/general/screenshots/04-create-room.png b/extra/general/screenshots/04-create-room.png new file mode 100644 index 00000000..f02f16dd Binary files /dev/null and b/extra/general/screenshots/04-create-room.png differ diff --git a/extra/general/screenshots/05-main-pane-small.png b/extra/general/screenshots/05-main-pane-small.png new file mode 100644 index 00000000..ff738406 Binary files /dev/null and b/extra/general/screenshots/05-main-pane-small.png differ diff --git a/extra/general/screenshots/06-chat-small.png b/extra/general/screenshots/06-chat-small.png new file mode 100644 index 00000000..9916a55e Binary files /dev/null and b/extra/general/screenshots/06-chat-small.png differ