Add real README.md and INSTALL.md
This commit is contained in:
miruka
parent
2511a03045
commit
3df27674b2
240
INSTALL.md
Normal file
240
INSTALL.md
Normal file
|
|
@ -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.
|
||||
165
README.md
165
README.md
|
|
@ -1,60 +1,121 @@
|
|||
# Mirage
|
||||
# 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**.
|
||||
|
||||
|
||||
|
||||
## 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. `<red>(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 `<type> <name>: <value>`.
|
||||
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)"
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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 <TODO>
|
||||
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
|
||||
|
|
|
|||
1
TODO.md
1
TODO.md
|
|
@ -4,7 +4,6 @@
|
|||
|
||||
- page back buttons
|
||||
- Add Gentoo instructions
|
||||
- Finish the README.md
|
||||
- Build final AppImage and test media opening
|
||||
|
||||
## Refactoring
|
||||
|
|
|
|||
BIN
extra/general/screenshots/01-chat.png
Normal file
BIN
extra/general/screenshots/01-chat.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 230 KiB |
BIN
extra/general/screenshots/02-sign-in.png
Normal file
BIN
extra/general/screenshots/02-sign-in.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 223 KiB |
BIN
extra/general/screenshots/04-create-room.png
Normal file
BIN
extra/general/screenshots/04-create-room.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 204 KiB |
BIN
extra/general/screenshots/05-main-pane-small.png
Normal file
BIN
extra/general/screenshots/05-main-pane-small.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
BIN
extra/general/screenshots/06-chat-small.png
Normal file
BIN
extra/general/screenshots/06-chat-small.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Loading…
Reference in New Issue
Block a user