Skip to content

Commit

Permalink
Tutorial review (#3605)
Browse files Browse the repository at this point in the history
My proposal for some light edits in the first tutorial.

One note on headings - we recommend using sentence capitalization for
all headings https://docs.ubuntu.com/styleguide/en

I was also thinking of changing "Learn What Mir Can Do" to "Getting
started with Mir". I'm not sure if it's the best choice but it sounds
like a basic enough first tutorial that any user should get themselves
acquainted with.

I think the tutorial is accessible enough as is so I didn't introduce
any significant changes to steps themselves.

Jira: https://warthogs.atlassian.net/browse/DOCPR-852
  • Loading branch information
tarek-y-ismail authored Oct 10, 2024
2 parents 8f9271b + 6f60d63 commit e63e291
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 137 deletions.
129 changes: 129 additions & 0 deletions doc/sphinx/tutorial/getting-started-with-mir.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
# Getting started with Mir

This tutorial will guide you through Mir's basic functionality.

By the end of the tutorial, you will install and run a demo application, learn how to use Mir in different environments, and learn about features that Mir provides for Mir-based compositors.

If you are unfamiliar with Mir, start with this tutorial, and then proceed to a [developer tutorial](write-your-first-wayland-compositor) which will guide you through the process of writing a compositor.


## Installing demo applications
Mir demos are available on Debian derivatives, Fedora, and Alpine. For distros
that don't have pre-built binaries, examples can be built from source.

### On Debian and its derivatives

```sh
sudo apt install mir-demos mir-graphics-drivers-desktop
```

### On Fedora
```sh
sudo dnf install mir-demos
```

### On Alpine
```sh
sudo apk add mir-demos mir
```

## Running applications on X11 or Wayland

We'll work with `miral-app`, a script that handles running a Mir shell with a basic GUI.

Mir allows you to run a graphical shell in *desktop mode* or in *kiosk mode*.

Desktop mode means that application windows that are opened are floating, you can move them around the screen, maximize, or minimize them.
Kiosk mode means that the application is opened in fullscreen mode. You are unable to move or resize it.

To run the script in desktop mode:
```sh
miral-app
```

To run the script in kiosk mode:
```sh
miral-app -kiosk
```

## Running shells natively

Mir compositors support running "natively" by launching them from a virtual terminal or a login screen.

### Launching from a virtual terminal

1. Switch to a virtual terminal by pressing CTRL+ALT+F\<Number\> and log in.

2. Run the script:
```sh
miral-app
```

### Launching from a login screen

Open the window manager list, choose **Mir Shell**, log in, and `miral-shell` will be running fullscreen.

## Using on-screen keyboards
Mir-based compositors support on-screen keyboards.

**Note**: Due to security reasons, some Wayland extensions needed by on-screen keyboards are disabled by default. In this tutorial, we override this setting by passing `--add-wayland-extensions all` when launching `miral-app`.
passing a `--add-wayland-extensions all` flag when launching an example application.

You can use any Wayland compatible on-screen keyboard but as an example, we'll use `ubuntu-frame-osk`.

1. Install `ubuntu-frame-osk`:
```sh
sudo snap install ubuntu-frame-osk
sudo snap connect ubuntu-frame-osk:wayland
```

2. Start `miral-app`:
```sh
miral-app --add-wayland-extensions all
```

3. Once the shell loads, start the terminal (with `Ctrl-Alt-Shift-T`) and start your on-screen keyboard:
```sh
ubuntu-frame-osk&
```
An on-screen keyboard will pop up.


## Mixing Wayland and X11 clients

You can run X11 applications inside Mir-based compositors. As an example, let's run `xclock` - an X11 application that displays the time.

1. Enable X11 support in `miral-shell`:
```sh
miral-app --enable-x11 true
```

2. Once the shell loads, run `xclock`:
```sh
xclock
```
A window with a clock will pop up.

## Remote desktop
Mir supports remote desktops via the VNC protocol. To demo this, you'll use `wayvnc` - a VNC server.

1. Install `wayvnc`:

```sh
sudo apt install wayvnc
```

2. Install your preferred [VNC client](https://help.ubuntu.com/community/VNC/Clients).

3. Start the shell with all extensions enabled:
```sh
miral-app --add-wayland-extensions all
```

4. In the shell, open the terminal and run `wayvnc`:
```sh
wayvnc
```
A `wayvnc` server will start and will listen to `localhost`.

5. Run your VNC client and connect to `localhost`. You will see the exact same view in both the Mir compositor and the VNC viewer.
4 changes: 2 additions & 2 deletions doc/sphinx/tutorial/index.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Tutorials
These pages provide first-time introductions to key Mir aspects

- [Learn What Mir Can Do](/tutorial/learn-what-mir-can-do): A showcase of Mir's capabilities
- [Getting started with Mir](/tutorial/getting-started-with-mir): A showcase of Mir's capabilities
- [Write Your First Wayland Compositor](/tutorial/write-your-first-wayland-compositor): A guide through writing a simple compositor

```{toctree}
:hidden:
/tutorial/learn-what-mir-can-do
/tutorial/getting-started-with-mir
/tutorial/write-your-first-wayland-compositor
```
135 changes: 0 additions & 135 deletions doc/sphinx/tutorial/learn-what-mir-can-do.md

This file was deleted.

0 comments on commit e63e291

Please sign in to comment.