619 lines
36 KiB
HTML
619 lines
36 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="light" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>The Element-Call Book</title>
|
||
<meta name="robots" content="noindex">
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
<meta name="description" content="Element Call - the world’s first decentralised voice and video conferencing solution powered entirely by Matrix!">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff">
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
<link rel="stylesheet" href="ferries.css">
|
||
<link rel="stylesheet" href="theme/2020-edition.css">
|
||
|
||
<!-- MathJax -->
|
||
<script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
</head>
|
||
<body class="sidebar-visible no-js">
|
||
<div id="body-container">
|
||
<!-- Provide site root to javascript -->
|
||
<script>
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script>
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script>
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
var body = document.querySelector('body');
|
||
body.classList.remove('no-js')
|
||
body.classList.add('js');
|
||
</script>
|
||
|
||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script>
|
||
var body = document.querySelector('body');
|
||
var sidebar = null;
|
||
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
} else {
|
||
sidebar = 'hidden';
|
||
}
|
||
sidebar_toggle.checked = sidebar === 'visible';
|
||
body.classList.remove('sidebar-visible');
|
||
body.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item affix "><a href="title-page.html">The Element-Call book</a></li><li class="chapter-item affix "><a href="foreword.html">Foreword</a></li><li class="chapter-item affix "><a href="ch00-00-introduction.html">Introduction</a></li><li class="chapter-item affix "><li class="part-title">Getting started</li><li class="chapter-item "><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="ch01-01-building-blocks.html"><strong aria-hidden="true">1.1.</strong> The building blocks</a></li><li class="chapter-item "><a href="ch01-02-element-call-hello.html"><strong aria-hidden="true">1.2.</strong> Hello Element-Call!</a></li></ol></li><li class="chapter-item "><a href="ch02-00-installation.html"><strong aria-hidden="true">2.</strong> Installation</a></li><li class="chapter-item "><a href="ch09-00-element-call-examples.html"><strong aria-hidden="true">3.</strong> Element-Call Examples</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="ch09-01-element-call-hello.html"><strong aria-hidden="true">3.1.</strong> ELement-Call-Hello!</a></li></ol></li><li class="chapter-item "><a href="appendix-00.html"><strong aria-hidden="true">4.</strong> Appendix</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="appendix-01-keywords.html"><strong aria-hidden="true">4.1.</strong> A - Keywords</a></li><li class="chapter-item "><a href="appendix-02-operators.html"><strong aria-hidden="true">4.2.</strong> B - Operators and Symbols</a></li><li class="chapter-item "><a href="appendix-03-derivable-traits.html"><strong aria-hidden="true">4.3.</strong> C - Derivable Traits</a></li><li class="chapter-item "><a href="appendix-04-translation.html"><strong aria-hidden="true">4.4.</strong> D - Translations of the Book</a></li></ol></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||
<div class="sidebar-resize-indicator"></div>
|
||
</div>
|
||
</nav>
|
||
|
||
<!-- Track and set sidebar scroll position -->
|
||
<script>
|
||
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
|
||
sidebarScrollbox.addEventListener('click', function(e) {
|
||
if (e.target.tagName === 'A') {
|
||
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
|
||
}
|
||
}, { passive: true });
|
||
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
|
||
sessionStorage.removeItem('sidebar-scroll');
|
||
if (sidebarScrollTop) {
|
||
// preserve sidebar scroll position when navigating via links within sidebar
|
||
sidebarScrollbox.scrollTop = sidebarScrollTop;
|
||
} else {
|
||
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
|
||
var activeSection = document.querySelector('#sidebar .active');
|
||
if (activeSection) {
|
||
activeSection.scrollIntoView({ block: 'center' });
|
||
}
|
||
}
|
||
</script>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky">
|
||
<div class="left-buttons">
|
||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</label>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">The Element-Call Book</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
<a href="https://gitea.networkx.de/rzerres/element-call/tree/main/book/{path}" title="Git repository" aria-label="Git repository">
|
||
<i id="git-repository-button" class="fa fa-github"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script>
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<h1 id="element-call"><a class="header" href="#element-call">Element Call</a></h1>
|
||
<p><em>annotated and documented by Ralf Zerres and all contributers</em></p>
|
||
<p>This version of the text assumes you’re using Element-Call v0.6.7 or later in
|
||
conjuction with Rust v1.83.0 or later. <em>Cargo.toml</em> should define
|
||
<code>edition="2021"</code>. That enables and uses Rust 2021 Edition idioms in
|
||
all derived projects.</p>
|
||
<p>See the <a href="https://https://gitea.networkx.de/rzerres/element-call/book/ch02-00-installation.html">“Installation” section of Chapter 2</a>
|
||
to install or update Element-Call.</p>
|
||
<p>The 2021 Edition of this book is the initial release. It will be
|
||
released with the Element-Call version 1.0.0.</p>
|
||
<ul>
|
||
<li>Appendix A “Keywords”, explains the new raw identifiers.</li>
|
||
<li>Appendix D “Translations”, is work in progress. We will release
|
||
instances of this book in the target language once they are translated.</li>
|
||
</ul>
|
||
<p>For online reading, a HTML rendered version is available at
|
||
<a href="https://gitea.networkx.de/rzerres/element-call/book/blob/main/src/img/element-call.png">Element-Call book</a>. Alternatively you might want to have it handy
|
||
for offline usage. Either you downlaod a rendered <code>pdf</code> or
|
||
<code>ebook</code>version or go ahead and download the source. Then kick on
|
||
mdbook (the definition of the target location is optional).</p>
|
||
<pre><code class="language-console">mdbook build --dest-dir book_en --open
|
||
</code></pre>
|
||
<!---
|
||
This text is available in [paperback and ebook format from No Starch Press][nsprust].
|
||
-->
|
||
<!--
|
||
[element-call_book_en]: https://gitea.networkx.de/rzerres/element-call/book/
|
||
[element-call_book_en_stable]: https://element.io/element-call/stable/book/
|
||
-->
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="foreword"><a class="header" href="#foreword">Foreword</a></h1>
|
||
<p>The history of computer-aided communication, which supports not only
|
||
text video and sound goes back to the 1990s. From from today’s
|
||
perspective, it seems almost grotesque what prices had to be paid for
|
||
the had to be paid for the hardware developed at that time. Not only
|
||
for the quality and quality of encoded data streams, new formats had
|
||
to be invented (CIF (CIF, QCIF). The development of Codex was in its
|
||
infancy. infancy. There was a lack of
|
||
standardization. Interoperability and and the use of the Internet were
|
||
at best distant goals. People were working on very
|
||
application-specific solutions and approaches that had the potential
|
||
for affordable components for mass production. As an example, the
|
||
pioneering manufacturer <a href="https://en.wikipedia.org/wiki/Parallax_Graphics"><code>Parallax Graphics Inc.</code></a>. Founded in 1982 by two graduates of Cornell
|
||
University, the company focused on the marketing of the marketing of
|
||
<code>high end</code> graphics cards, including for the then popular university
|
||
environment at the time. These cards initially cost around €25,000
|
||
and supplied ASICS and a codex implemented in implemented in hardware,
|
||
which could realize resolutions of up to 1280x1024 pixels could be
|
||
realized.</p>
|
||
<p>Every commercially available cell phone, tablet, notebook and desktop
|
||
PCs currently deliver graphics card performance that can render 2k,
|
||
even 4k pixels can render. Encoding and decoding solutions are
|
||
decoding solutions have been standardized internationally, which have
|
||
significantly reduced the bandwidths to be transmitted and thus and
|
||
thus enable billions of uses on the Internet use on the
|
||
Internet. One-to-one video telephony has been established for years.
|
||
established for years. And everyone will remember the radical upheaval
|
||
in the professional use of video conferencing solutions that the COVID
|
||
pandemic brought with it in 2022.</p>
|
||
<p>Today, the use of video conferencing solutions is ubiquitous. In the
|
||
working world, proprietary solutions are often used, to implement work
|
||
processes regardless of location. Examples include the products from
|
||
the manufacturers <a href="https://en.wikipedia.org/wiki/Cisco"><code>CISCO->(Webex)</code></a>,
|
||
<a href="https://de.wikipedia.org/wiki/Microsoft_Teams"><code>Microsoft->(Skype,Teams)</code></a>, <a href="https://www.hp.com/de-de/poly.html"><code>HP->(Poly)</code></a>
|
||
and <a href="https://en.wikipedia.org/wiki/Zoom_(software)"><code>Zoom->(Zoom)</code></a> are listed. But also free software such as
|
||
<a href="https://bigbluebutton.org/"><code>BigBlueButton</code></a>, <a href="https://jitsi.org/"><code>Jitsi</code></a> or
|
||
<a href="https://nextcloud-talk.readthedocs.io/en/latest/"><code>Nextcloud->(Talk)</code></a> are enjoying worldwide distribution.</p>
|
||
<p>With <code>Element-Call</code> the Matrix ecosystems gains a new approach that
|
||
fully embraces the potential of MatrixRTC. Think of participents in
|
||
decentralized domains that are to able to dynamicly create and manage
|
||
multipoint meetings in an efficiant manner. An Open-Source, that
|
||
enables fee choice of any Matrix complient Client. What progress.</p>
|
||
<p>— Ralf Zerres</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
|
||
<!--
|
||
> WIP: to be uncommented, once it is done
|
||
> Note: This edition of the book is the same as [The Orbital Widget Toolkit]
|
||
> [nsprust] available in print and ebook format from [No Starch Press][nsporbtk].
|
||
|
||
[nsporbtk]: https://nostarch.com/orbtk
|
||
[nsp]: https://nostarch.com/
|
||
-->
|
||
<p><a href="img/element-call-webui.png"><img src="img/element-call-webui.png" width="720"/></a></p>
|
||
<p>Welcome to <code>Element-Call</code>, an introductory book about the Matrix based
|
||
video conferencing subsystem.</p>
|
||
<div class="warning">
|
||
<p>Warning: This book is incomplete. Documenting everything and
|
||
rewriting outdated parts take a while.
|
||
See the <a href="https://https://gitea.networkx.de/rzerres/element-call/book/issues">issue tracker</a> to check what’s missing or outdated. If there
|
||
are any mistakes or ideas that haven’t been reported, feel free to
|
||
open a new issue there.</p>
|
||
</div>
|
||
<p><code>Element-Call</code> fully embraces the potential of MatrixRTC. All
|
||
supported clients will connect via the genreric API, though selecting
|
||
their prefered mode (standalone- vs. widget-view).</p>
|
||
<p><a href="img/element-call-modes.png"><img src="img/element-call-modes.png" width="720"/></a></p>
|
||
<h2 id="features"><a class="header" href="#features">Features</a></h2>
|
||
<ul>
|
||
<li>Modern WebRTC API (powered by LifeKit)</li>
|
||
<li>Custom widgets</li>
|
||
<li>WebBrowser suport</li>
|
||
<li>Custom theming engine</li>
|
||
<li>Localization</li>
|
||
</ul>
|
||
<h2 id="supported-backend-platforms"><a class="header" href="#supported-backend-platforms">Supported Backend Platforms</a></h2>
|
||
<ul>
|
||
<li>Linux (native)</li>
|
||
</ul>
|
||
<!--
|
||
* macOS (native)
|
||
* Windows (native)
|
||
* openBSD (not tested, but should work)
|
||
* Web (cargo-node)
|
||
* Android (native planned | cargo-node)
|
||
* iOS (native planned | cargo-node planned)
|
||
-->
|
||
<h2 id="supported-client-platforms"><a class="header" href="#supported-client-platforms">Supported Client Platforms</a></h2>
|
||
<ul>
|
||
<li>Matrix clients (e.g. Element X, ShildiNext)</li>
|
||
<li>WebBrouwsers (e.g. Brave, Chrome, Edge, Firefox)</li>
|
||
</ul>
|
||
<h2 id="who-element-call-book-is-for"><a class="header" href="#who-element-call-book-is-for">Who Element-Call Book Is For</a></h2>
|
||
<p>The intention of <code>Element-Call</code> book is to help interested developers and administrators to get familiar with the structure and the componets choosen to implement a fully functional decentralized video conferencing solution. It will offer the needed in depth information to get in touch with the codebase. It will also aid an administrator to set up the needed software components to build up a self hosted installation.</p>
|
||
<h2 id="source-code"><a class="header" href="#source-code">Source Code</a></h2>
|
||
<p>The source files of the book are maintained as a git submodule found at <a href="https://gitea.networkx.de/rzerres/element-call-book/book_en"><code>Element-Call book</code></a>.</p>
|
||
<!--
|
||
[element-call_book_en_stable]: https://element.io/element-call/stable/book/
|
||
-->
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h1>
|
||
<p>Let’s start your Element-Call journey! There’s a lot to learn, but every journey starts
|
||
somewhere. In this chapter, we’ll discuss:</p>
|
||
<ul>
|
||
<li>The building blocks of Element-Call</li>
|
||
<li>Installing Element-Call</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h2 id="building-blocks"><a class="header" href="#building-blocks">Building blocks</a></h2>
|
||
<p>Historically <code>Elememnt-Call</code> did implement an infrastructure, where
|
||
all participants were fully meshed. That means all participants had a
|
||
direct peer to each other. This structure does work quite well with a
|
||
low number of call partners (e.g 1:1 sessions). Clearly this structure
|
||
is totally inefficient and collapsing, as soon as the number of
|
||
participants rises: The needed number of streams that have to be
|
||
synchronized are increasing exponentionally.</p>
|
||
<p>Most commercial solutions overcome this bottleneck utilizing a
|
||
MCU-structure: Each participant of the call is directly connected to
|
||
the controlling MCU (the head).</p>
|
||
<p>MCU routing has disadvantages and shortcommings too.</p>
|
||
<ul>
|
||
<li>You can’t assign different egress parameters from the MCU to
|
||
individual participant streams</li>
|
||
<li>A single MCU can’t handle distributed structure</li>
|
||
</ul>
|
||
<p>Since the nature of Matrix based communication makes use of a
|
||
distributed infrasturcture, MatrixRTC need to handle this aspect. It
|
||
is implemented with an SFU backend.</p>
|
||
<p>The following image visualize the differences inside the available
|
||
<img src="./img/voip_routing_structures.png" alt="voip routing structures" /></p>
|
||
<h3 id="backend"><a class="header" href="#backend">Backend</a></h3>
|
||
<p>The MatrixRTC functionality is handled via <a href="https://github.com/livekit">LiveKit</a>.</p>
|
||
<h3 id="frontend"><a class="header" href="#frontend">Frontend</a></h3>
|
||
<p><img src="https://gitea.networkx.de/rzerres/element-call/book/blob/main/src/img/element-call_building_blocks.png" alt="Building blocks" /></p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h2 id="hello-element-call"><a class="header" href="#hello-element-call">Hello ELement-Call!</a></h2>
|
||
<!--
|
||
[<img src="img/element-call.png" width="720"/>](img/element-call-webui.png)
|
||
-->
|
||
<p><img src="https://gitea.networkx.de/rzerres/element-call-book/src/branch/main/src/img/element-call-webui.png" alt="Welcome to the element-call book." /></p>
|
||
<p>Now that you’ve installed the needed building blocks, let’s adapt the
|
||
Frontend.</p>
|
||
<h3 id="writing-and-running-the-element-call-frontend"><a class="header" href="#writing-and-running-the-element-call-frontend">Writing and Running the ELement-Call frontend</a></h3>
|
||
<p>First, we make a new project using <em>Cargo</em>. With its <em>.toml</em> file we
|
||
allow Rust to declare the various dependencies and metadata. That
|
||
ensures that you’ll always get a repeatable output of the build.</p>
|
||
<p>Go ahead like so:</p>
|
||
<pre><code class="language-console">$ cargo new element-call
|
||
$ cd element-call
|
||
</code></pre>
|
||
<p>The first command, <code>cargo new</code>, takes the name of the project
|
||
(“<code>element-call</code>”) as the first argument. The second command changes to
|
||
the new project’s directory.</p>
|
||
<p>Look at the generated <em>Cargo.toml</em> file:</p>
|
||
<p><span class="filename">Filename: Cargo.toml</span></p>
|
||
<pre><code class="language-toml">[package]
|
||
name = "element_call_hello_example"
|
||
version = "0.1.0"
|
||
authors = ["Your Name <you@example.com>"]
|
||
edition = "2021"
|
||
|
||
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
|
||
|
||
[dependencies]
|
||
</code></pre>
|
||
<p><span class="caption">Listing 1-1: Default metadata “element_call_hello”</span></p>
|
||
<p>With <code>cargo new</code>, a default project structure is created. Maybe the
|
||
author information is already exchanged if <em>Cargo</em> could obtain a definition
|
||
from your environment. <em>Cargo</em> also generated source code for a “Hello, world!”
|
||
program. Let’s Check out the corresponding <em>src/main.rs</em> file:</p>
|
||
<p><span class="filename">Filename: src/main.rs</span></p>
|
||
<pre><pre class="playground"><code class="language-rust edition2021">fn main() {
|
||
println!("Hello, world!");
|
||
}</code></pre></pre>
|
||
<p><span class="caption">Listing 1-2: Default source file “main.rs”</span></p>
|
||
<p>No need to compile that stage with <code>cargo run</code>, since we are going to
|
||
exchange the project metadata, as well as the element-call source code right
|
||
away.</p>
|
||
<h4 id="update-cargotoml"><a class="header" href="#update-cargotoml">Update Cargo.toml</a></h4>
|
||
<p>First reopen the <em>Cargo.toml</em> file and enter the Code in Listing 1-1 into <em>Cargo.toml</em></p>
|
||
<p><span class="filename">Filename: Cargo.toml</span></p>
|
||
<pre><code class="language-toml ignore">[package]
|
||
name = "element_call_hello"
|
||
version = "0.0.1"
|
||
authors = [
|
||
"Ralf Zerres <ralf.zerres.de@gmail.com>",
|
||
]
|
||
description = "The Element-Call - Training project"
|
||
documentation = "https://docs.rs/orbtk"
|
||
repository = "https://github.com/redox-os/orbtk"
|
||
readme = "README.md"
|
||
license = "MIT"
|
||
keywords = [
|
||
"element-call",
|
||
"matrix",
|
||
"matrixrtc",
|
||
]
|
||
edition = "2021"
|
||
|
||
[profile.dev]
|
||
opt-level = 1
|
||
|
||
[dependencies]
|
||
#element-call = { git = "https://gitea.networkx.de/rzerres/element-call-book.git", branch = "develop" }
|
||
|
||
[[bin]]
|
||
name = "element_call_hello"
|
||
path = "src/main.rs"
|
||
</code></pre>
|
||
<p><span class="caption">Listing 1-1: Project metadata “Element-Call”</span></p>
|
||
<p>You may wonder, why the <em>name</em> property inside the <em>Cargo.toml</em> is
|
||
formatted like <code>element_call</code>.</p>
|
||
<pre><code class="language-toml ignore">name = "element_call_hello"
|
||
</code></pre>
|
||
<p>It is a good habit to follow rusts
|
||
naming convention, that encourages you to use <a href="https://rust-lang.github.io/api-guidelines/naming.html">snake_case</a>
|
||
naming. While expanding the <em>Element-Call</em> example sources, we will keep
|
||
the grouping prefix <code>element-call</code>. That way we end up to call our first target
|
||
binary <code>element-call_hello</code>.</p>
|
||
<h4 id="update-mainrs"><a class="header" href="#update-mainrs">Update main.rs</a></h4>
|
||
<p>All of the <em>Element-Call</em> specific code that is needed to build our first
|
||
example “Hello Element-Call!” is shown in Listing 1-2. It goes to
|
||
<em>src/main.rs</em>.</p>
|
||
<p><span class="filename">Filename: src/main.rs</span></p>
|
||
<pre><code class="language-rust ignore">use element-call::prelude::*;
|
||
|
||
fn main() {
|
||
element-call::initialize();
|
||
|
||
.run();
|
||
}</code></pre>
|
||
<p><span class="caption">Listing 1-2: Code that creates a Window and
|
||
prints “Hey Element-Call!”</span></p>
|
||
<p>Save the file and go back to your terminal window. Enter the following
|
||
commands to compile and run the file:</p>
|
||
<pre><code class="language-console">$ cargo run --release element_call_hello
|
||
</code></pre>
|
||
<h3 id="compiling-and-running-are-separate-steps"><a class="header" href="#compiling-and-running-are-separate-steps">Compiling and Running Are Separate Steps</a></h3>
|
||
<p>Before running an Element-Call application, you must compile its source code. A typical
|
||
Element-Call project will generate the executable binary code using cargo and place the
|
||
result in the target subfolder of the project.</p>
|
||
<p>Profiles may be used to configure compiler options such as optimization levels
|
||
and debug settings. By default the <code>dev</code> or <code>test</code> profiles are used. If the
|
||
<code>--release</code> flag is given, then the release or bench profiles are used.</p>
|
||
<pre><code class="language-console">$ cargo build --release --bin element-call-hello.rs
|
||
$ ../target/release/hello_element_call
|
||
</code></pre>
|
||
<p>On Windows, you need to use <code>backslash</code> as a path delimiter:</p>
|
||
<pre><code class="language-powershell">> cargo build --release --bin element-call-hello.rs
|
||
> ..\target\release\element_call_hello.exe
|
||
</code></pre>
|
||
<p>If you like to get debug feedback you can call the build process like this</p>
|
||
<pre><code class="language-console">$ cargo build --features debug --bin element-call-hello.rs
|
||
</code></pre>
|
||
<div style="break-before: page; page-break-before: always;"></div><h2 id="installation"><a class="header" href="#installation">Installation</a></h2>
|
||
<p>The first step is to install Rust. This is described in depth following
|
||
<a href="https://github.com/rust-lang/book/blob/master/src/ch01-01-installation.md">Rust book Chapter 1</a></p>
|
||
<p>When creating a OrbTk application, we define the needed dependencies to the
|
||
OrbTk crates in the Cargo.toml file of our project. The complile process
|
||
will resolve the references and download the source as needed.</p>
|
||
<blockquote>
|
||
<h3 id="command-line-notation"><a class="header" href="#command-line-notation">Command Line Notation</a></h3>
|
||
<p>In this chapter and throughout the book, we’ll show some commands used in the
|
||
terminal. Lines that you should enter in a terminal all start with <code>$</code>. You
|
||
don’t need to type in the <code>$</code> character; it indicates the start of each
|
||
command. Lines that don’t start with <code>$</code> typically show the output of the
|
||
previous command. Additionally, PowerShell-specific examples will use <code>></code>
|
||
rather than <code>$</code>.</p>
|
||
</blockquote>
|
||
<h3 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h3>
|
||
<blockquote>
|
||
<p><em><strong>WIP</strong></em>: What are the most common culprits? Can we provide some general, basic solutions</p>
|
||
</blockquote>
|
||
<h3 id="local-documentation"><a class="header" href="#local-documentation">Local Documentation</a></h3>
|
||
<p>OrbTk offers the option to install its documentation locally, so you can read it
|
||
offline.</p>
|
||
<p>Any time a type, a function, a method or a crate is reference by the toolkit
|
||
and you’re not sure what it does or how to use it, have a look at its application
|
||
programming interface <a href="https://docs.rs/orbtk">API documentation</a> to find out!</p>
|
||
<!-- [API documentation]: https://www.redox-os.org/orbtk/doc/en -->
|
||
<!-- [API documentation]: https://github.com/redox-os/orbtk -->
|
||
<h3 id="install-rust-on-linux-or-macos"><a class="header" href="#install-rust-on-linux-or-macos">Install Rust on Linux or macOS</a></h3>
|
||
<p>If you are using Linux or macOS open up an terminal and copy and paste the text below and hit the enter key on your keyboard:</p>
|
||
<pre><code class="language-bash">curl https://sh.rustup.rs -sSf | sh
|
||
</code></pre>
|
||
<h3 id="install-rust-on-windows"><a class="header" href="#install-rust-on-windows">Install Rust on Windows</a></h3>
|
||
<p>Download and run the Rust windows installer from https://www.rust-lang.org/tools/install.</p>
|
||
<h3 id="install-redoxer-redox-os"><a class="header" href="#install-redoxer-redox-os">Install Redoxer (Redox OS)</a></h3>
|
||
<p>If you want build and run your Rust application on a <a href="https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine">KVM</a> capable OS for Redox you can use <a href="https://gitlab.redox-os.org/redox-os/redoxer">redoxer</a>.</p>
|
||
<p>To install Redoxer you have to first install the rust toolchain. After that open up an terminal and copy and paste the text below and hit the enter key on your keyboard:</p>
|
||
<pre><code class="language-bash">cargo +nightly install redoxer
|
||
</code></pre>
|
||
<p>To compile and run your application on Redox OS you should check the Redox OS Book.</p>
|
||
<h3 id="editor-and-ide-integration"><a class="header" href="#editor-and-ide-integration">Editor and IDE integration</a></h3>
|
||
<p>A wide range of editors and IDE’s are providing support for Rust code like</p>
|
||
<ul>
|
||
<li>like syntax-highlighting</li>
|
||
<li>auto-completion</li>
|
||
<li>linting</li>
|
||
<li>lsp support</li>
|
||
</ul>
|
||
<h4 id="vs-code"><a class="header" href="#vs-code">VS Code</a></h4>
|
||
<p>There is a big community that rely on the visualstudio implementation
|
||
to handle their code base. Following are the steps needed to expand
|
||
your installation to support <code>VS Code for Rust</code> development:</p>
|
||
<ol>
|
||
<li>Download VS Code <a href="https://code.visualstudio.com/download">from</a>.</li>
|
||
<li>Install <a href="https://marketplace.visualstudio.com/items?itemName=rust-lang.rust">Rust Language Server plugin</a> (the
|
||
Rust Language Server).</li>
|
||
</ol>
|
||
<h4 id="alternative-editors-and-ides"><a class="header" href="#alternative-editors-and-ides">Alternative Editors and IDEs</a></h4>
|
||
<p>If you perefer other solution, you will find in depth help inside the
|
||
context of this inclomplete links:</p>
|
||
<ul>
|
||
<li><a href="https://atom.io/packages/language-rust">Atom</a></li>
|
||
<li><a href="https://intellij-rust.github.io">Intellij IDEA</a></li>
|
||
<li><a href="https://github.com/rust-lang/rust.vim">Vim</a></li>
|
||
<li><a href="https://github.com/rust-lang/rust-mode">Emacs</a></li>
|
||
<li><a href="https://github.com/eclipse/corrosion">Eclipse</a></li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="element-call-example-applications"><a class="header" href="#element-call-example-applications">ELement-Call Example Applications</a></h1>
|
||
<p>This section provides <code>Element-Call</code> example apps. We hope to cover
|
||
interesting aspects of the API.</p>
|
||
<p>Take them as a tutorial, all listings are created as a reference. They
|
||
have in mind to serve as an introduction to a specific topic. As
|
||
educational content, this apps are marked with in-lined comments and
|
||
anchors. If we did well, you can concentrate on the parts we like
|
||
to emphasize.</p>
|
||
<p>Inside the library, you will find the collection of example code in
|
||
the subdirectory <em>examples</em> in crate <a href="https://github.com/element-hq/element-call/tree/develop/element-call/examples"><code>element-call</code></a>.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="hello-element-call-1"><a class="header" href="#hello-element-call-1">Hello Element-Call!</a></h1>
|
||
<p>We already introduced the source in <a href="https://gitea.networkx.de/element-call-book/src/listings/ch01-02-element-call-hello.html#pdate-cargotoml">Chapter 01</a>.
|
||
For the sake of completeness, and since its a habit to begin with … here we go.</p>
|
||
<!--
|
||
[example_hello-element-call]: https://element-hq.github.io/element-call/book/src/listings/ch01-02-element-call-hello.html#pdate-cargotoml
|
||
-->
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="element-call-appendix"><a class="header" href="#element-call-appendix">Element-Call Appendix</a></h1>
|
||
<p>This is WIP</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="element-call-appendix---keywords"><a class="header" href="#element-call-appendix---keywords">Element-Call Appendix - Keywords</a></h1>
|
||
<p>This is WIP</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="element-call-appendix---operators"><a class="header" href="#element-call-appendix---operators">Element-Call Appendix - Operators</a></h1>
|
||
<p>This is WIP</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="element-call-appendix---derivable-traits"><a class="header" href="#element-call-appendix---derivable-traits">Element-CAll Appendix - Derivable Traits</a></h1>
|
||
<p>This is WIP</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="appendix-d-translations-of-the-book"><a class="header" href="#appendix-d-translations-of-the-book">Appendix D: Translations of the Book</a></h1>
|
||
<p>For resources in languages other than English. This is work in progress; see
|
||
<a href="https://gitea.networkx.de/ralf.zerres/element-call-book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations">the Translations label</a> to help or let us know about a new translation!</p>
|
||
<ul>
|
||
<li><a href="https://gitea.networkx.de/rzerres/element-call-book">Deutsch</a></li>
|
||
</ul>
|
||
<!---
|
||
- [Deutsch](https://github.com/element.io/element-call/book/book-de)
|
||
- [Français](https://github.com/element.io/element-call/book/book-fr)
|
||
-->
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
<script>
|
||
window.playground_line_numbers = true;
|
||
</script>
|
||
|
||
<script>
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
<script src="ace.js"></script>
|
||
<script src="editor.js"></script>
|
||
<script src="mode-rust.js"></script>
|
||
<script src="theme-dawn.js"></script>
|
||
<script src="theme-tomorrow_night.js"></script>
|
||
|
||
<script src="elasticlunr.min.js"></script>
|
||
<script src="mark.min.js"></script>
|
||
<script src="searcher.js"></script>
|
||
|
||
<script src="clipboard.min.js"></script>
|
||
<script src="highlight.js"></script>
|
||
<script src="book.js"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
<script src="ferries.js"></script>
|
||
|
||
<script>
|
||
window.addEventListener('load', function() {
|
||
MathJax.Hub.Register.StartupHook('End', function() {
|
||
window.setTimeout(window.print, 100);
|
||
});
|
||
});
|
||
</script>
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|