Architecture diagram and description of the project's folders #3053

mattkae · 2023-09-26T19:22:48Z

How to test

Open up read the docs at the bottom of this pull request

What's new?

Implemented an architecture diagram for Mir
Implement an architecture document for Mir

codecov · 2023-09-26T19:47:00Z

Codecov Report

Merging #3053 (53aaa7f) into main (85bc5b0) will decrease coverage by 0.01%.
Report is 8 commits behind head on main.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #3053      +/-   ##
==========================================
- Coverage   77.69%   77.69%   -0.01%     
==========================================
  Files        1056     1056              
  Lines       73409    73449      +40     
==========================================
+ Hits        57037    57068      +31     
- Misses      16372    16381       +9

see 6 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

AlanGriffiths · 2023-09-27T11:55:41Z

doc/sphinx/architecture.md

+# Overview
+This document describes the high-level architecture of *Mir*, including a diagram and a brief introduction of the directory structure.
+
+# Concepts


I think at this level of abstraction there are more concepts. Basically, what you've called "Mir" breaks into several things:

mircore

mirplatform

mirserver

I think "Mir" ought to be the collective. And, maybe the highest level architecture is enumerating the shared libraries and which are "for consumption" and which are "internal"?

doc/sphinx/architecture.md

AlanGriffiths · 2023-09-27T12:03:53Z

doc/sphinx/architecture.md

+# Concepts
+## MirAL
+- The "Mir Abstraction Layer" (aka `mirAL` or `miral`) is a layer that makes the core Mir implementation easier for compositor-implementers to work with.
+- If one wishes to implement a compositor themselves, they will spend most of their time interacting with the `mirAL` API and only really touch the `mir` API when they require core concepts like a `mir::geometry::Rectangle`.


Rectangle is from mircore, and that's very different from the mirserver APIs (that compositor writers should never touch.

AlanGriffiths · 2023-09-27T12:05:59Z

doc/sphinx/architecture.md

+## `/src/platform` (no "s")
+- Graphics and input code that is shared between platforms


Comment: In principle, we aim to make this a public interface for third party "platforms". As Chris has been reworking these APIs, they are currently private

Co-authored-by: Alan Griffiths <[email protected]>

AlanGriffiths

There is too much "flattening" here. There is meaningful hierarchy:

mirserver is the "god" library.
miral (and miroil) are the support for building compositors with Mir.
Platforms are adaptors that allow mirserver to work across different graphics stacks
There are support libraries that provide the underpinnings for the above: mircore, mircommon, mircookie, mirplatform & mirwayland.

If you try and present parts of parts of mirserver as top-level concepts you end up with too many things to explain at the same time

AlanGriffiths · 2023-09-29T15:13:37Z

doc/sphinx/architecture.md

+## `/examples`
+- A collection of demo *Mir* compositors that are used as examples of how one might build a true compositor. Examples include:
+  - `miral-app`
+  - `miral-shel`


Suggested change

- `miral-shel`

- `miral-shell`

AlanGriffiths · 2023-09-29T15:14:36Z

doc/sphinx/architecture.md

+  - `mir_demo_server`
+
+## `/tests`
+- Unit tests for the entire project.


Not just unit tests

AlanGriffiths · 2023-09-29T15:18:24Z

doc/sphinx/architecture.md

+└── mirserver
+    ├── mircompositor
+    ├── mirinput
+    ├── mirfrontend
+    ├── mirfrontend-wayland
+    ├── mirfrontend-xwayland
+    ├── mirshell
+    ├── mirshelldecoration
+    ├── mirscene
+    ├── mirgraphics
+    ├── mirreport
+    ├── mirlttng
+    ├── mirlogging
+    ├── mirnullreport
+    ├── mirconsole
+    ├── mirgl
+    └── mirrenderergl


I wouldn't expand mirserver here. I think that introduces too many concepts.

I expanded it because each concept under mirserver (e.g. compositor, scene, shell, etc.) seem to warrant there own description for someone jumping into the project. Do you have any recommendation on how I can still describe those namespaces?

Sure, they need explaining but we're well past the number of concepts that should be introduced together. (Even Agatha Christie stops at a dozen suspects and she was aiming to confuse!)

First introduce the high level concepts. Then, break down each one in turn: (e.g. "These are the platforms... this one is for X11...", "This is the mirserver... it has these components...").

That gives the reader some structure to organise their understanding.

AlanGriffiths · 2023-09-29T15:24:16Z

doc/sphinx/architecture.md

+## mircookie
+- Provides event timestamps for inputs events that are difficult to spoof.


@RAOF I suspect that mircookie isn't actually useful now we're no longer shipping Mir's input events to clients. WDYT?

AlanGriffiths · 2023-09-29T15:27:41Z

doc/sphinx/architecture.md

+  - `src/server`
+  - `src/include/server`
+
+## mircompositor


I don't like this naming (probably comes from trying to treat it at the same level of abstraction as libraries).

It is "just" a namespace within mirserver.

It could be mirserver::mircompositor?

That's worse! How is a reader to associate something in the code (mir::compositor::Foo, say) with mirserver::mircompositor?

AlanGriffiths · 2023-09-29T15:28:53Z

doc/sphinx/architecture.md

+## mirfrontend
+- TODO: How do I describe this one?


src/server/frontend is vestigial - we should probably merge it with src/server/frontend_wayland

AlanGriffiths · 2023-09-29T15:30:09Z

doc/sphinx/architecture.md

+  - `src/server/shell`
+
+## mirshelldecoration
+- Manages the decoration of *Mir*'s windows


Suggested change

- Manages the decoration of *Mir*'s windows

- Manages *Mir*'s server-side decoration of windows. Currently only used for X11 clients.

AlanGriffiths · 2023-09-29T15:34:36Z

doc/sphinx/architecture.md

+- Directories:
+  - `src/server/report`
+
+## mirlttng


I like this naming even less. lttng is a directory/namespace within report - it shouldn't be named at the same level as mirwayland. Similarly, logging, null.

AlanGriffiths · 2023-09-29T15:37:10Z

doc/sphinx/architecture.md

+## graphics-gbm-kms
+- GBM/KMS display platform for Mir
+- This is the main display platform that one would expect to use
+- Directories:
+  - `src/platforms/gbm-kms`
+
+## graphics-gbm-kms
+- EglStreams/KMS display platform for Mir
+- This is an Nvidia-specific platform
+- Directories:
+  - `src/platforms/eglstreams-kms`
+
+## graphics-x11
+- An X11-based display/input platform
+- Primary platform used for testing
+- Directories:
+  - `src/platforms/x11`
+
+## graphics-wayland
+- A Wayland-based display/input platform
+- Directories:
+  - `src/platforms/wayland`


Suddenly we're not prefixing everything with "mir"! 😀

I think it works better to explain what a platform is, and then list examples.

I believe I only did this because the final .so names aren't prefaced with mir here 😂 But yes, agreed

AlanGriffiths

The architecture.md reads much better now. Please press on updating the rest to match

doc/sphinx/architecture.md

AlanGriffiths · 2023-10-05T09:15:55Z

* Open up read the docs at the bottom of this pull request

Should there be a link somewhere? I don't see it.

Saviq · 2023-10-05T12:01:01Z

Should there be a link somewhere? I don't see it.

Click "Show all checks" and:

☝️

Co-authored-by: Alan Griffiths <[email protected]>

AlanGriffiths

Content works for me.

A couple of tweaks though:

Could we incorporate the diagrams into the "Architecture" page instead of a separate page?
The "Closeup" would look tidier with the "Shell" tree and the "Compositor" tree swapped (or the "Scene" and "miral" trees). Is there a way to tweak the layout?

mattkae · 2023-10-06T13:28:57Z

The "Closeup" would look tidier with the "Shell" tree and the "Compositor" tree swapped (or the "Scene" and "miral" trees). Is there a way to tweak the layout?

The order that things appear in the document is the order that they will appear in the diagram (loosely). Should be possible!

AlanGriffiths

WFM, but as I've had a lot of input I'll @Saviq do a final review

Saviq

Yup, good start! :)

mattkae added 16 commits September 25, 2023 11:41

Initial work in progress on the markdown side of things

ef2f3a6

Completion of src + examples

934d817

Inclusion of the tests directory

c18ea51

Removing confusing indent

528b648

Minor typo

07d5e06

Remove unnecessary disclaimer

2a8ae74

Removing reference to the include directory

a7f49a5

Adding some extra info to the miral section

cd4f4b8

Using interface instead of class

48b21dc

Fix for typo

03704e7

As to Ask

a28629d

Formatting for clarity

03f2878

Completion of the initial proofread

7bd3d29

First iteration of the architecture diagram

a02d587

Initial draft of the architecture diagram

cc2b82d

Adding brief comment about Scene

0b2219c

mattkae requested review from Saviq, RAOF and AlanGriffiths September 26, 2023 19:22

AlanGriffiths reviewed Sep 27, 2023

View reviewed changes

mattkae and others added 2 commits September 28, 2023 14:50

Update doc/sphinx/architecture.md

b14a806

Co-authored-by: Alan Griffiths <[email protected]>

Initial updated idea explaining libraries instead of folders

5d63a7c

AlanGriffiths requested changes Sep 29, 2023

View reviewed changes

Initial pull request feedback

d0915dc

mattkae changed the title ~~(For feedback only!) Initial attempt at an architecture diagram and description of the project folders~~ Architecture diagram and description of the project's folders Oct 3, 2023

mattkae added 4 commits October 3, 2023 13:34

Moved from plantuml to mermaid

7a67e9e

Adding the diagram to the generated files

c14787e

Merge branch 'main' into feature/architecture_docs

ea19e8b

Adding a proper mermaid version

ee047d0

mattkae force-pushed the feature/architecture_docs branch from bd35cca to 8a2eb5e Compare October 3, 2023 20:30

mattkae requested a review from AlanGriffiths October 3, 2023 21:04

Updating the architecture docs pt 3

854eca4

AlanGriffiths reviewed Oct 5, 2023

View reviewed changes

doc/sphinx/architecture.md Outdated Show resolved Hide resolved

mattkae and others added 4 commits October 5, 2023 09:21

Update doc/sphinx/architecture.md

82dde04

Co-authored-by: Alan Griffiths <[email protected]>

Initial high-level diagram

8f8ae9e

First attempt at mirserver.mmd

8fb331f

Some minor updates

7690c4c

mattkae force-pushed the feature/architecture_docs branch from 7fb4fe0 to 7690c4c Compare October 5, 2023 18:17

mattkae requested a review from AlanGriffiths October 5, 2023 18:25

Removing 'Server' from the diagram

97238c9

AlanGriffiths requested changes Oct 6, 2023

View reviewed changes

Diagram organization

a2cc047

mattkae added 3 commits October 6, 2023 09:41

Combing the diagrams into the architecture.md file

a8dff89

Updating readability

b19cd88

Update for readability

d7c6ab9

mattkae requested a review from AlanGriffiths October 6, 2023 14:07

Moving diagrams to appropraite sections

53aaa7f

AlanGriffiths approved these changes Oct 6, 2023

View reviewed changes

Saviq assigned mattkae Oct 10, 2023

Saviq approved these changes Oct 10, 2023

View reviewed changes

Saviq added this pull request to the merge queue Oct 10, 2023

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Oct 10, 2023

Saviq added this pull request to the merge queue Oct 10, 2023

Merged via the queue into main with commit 7aa25d2 Oct 10, 2023
22 checks passed

Saviq deleted the feature/architecture_docs branch October 10, 2023 09:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Architecture diagram and description of the project's folders #3053

Architecture diagram and description of the project's folders #3053

mattkae commented Sep 26, 2023 •

edited

Loading

codecov bot commented Sep 26, 2023 •

edited

Loading

AlanGriffiths Sep 27, 2023

AlanGriffiths Sep 27, 2023

AlanGriffiths Sep 27, 2023

AlanGriffiths left a comment

AlanGriffiths Sep 29, 2023

AlanGriffiths Sep 29, 2023

AlanGriffiths Sep 29, 2023

mattkae Oct 3, 2023

AlanGriffiths Oct 3, 2023

AlanGriffiths Sep 29, 2023

AlanGriffiths Sep 29, 2023

mattkae Oct 3, 2023

AlanGriffiths Oct 3, 2023

AlanGriffiths Sep 29, 2023

AlanGriffiths Sep 29, 2023

AlanGriffiths Sep 29, 2023

AlanGriffiths Sep 29, 2023

mattkae Oct 3, 2023

AlanGriffiths left a comment

AlanGriffiths commented Oct 5, 2023

Saviq commented Oct 5, 2023

AlanGriffiths left a comment

mattkae commented Oct 6, 2023

AlanGriffiths left a comment

Saviq left a comment

		## `/src/platform` (no "s")
		- Graphics and input code that is shared between platforms

		## mircookie
		- Provides event timestamps for inputs events that are difficult to spoof.

	- Manages the decoration of Mir's windows
	- Manages Mir's server-side decoration of windows. Currently only used for X11 clients.

Architecture diagram and description of the project's folders #3053

Architecture diagram and description of the project's folders #3053

Conversation

mattkae commented Sep 26, 2023 • edited Loading

How to test

What's new?

codecov bot commented Sep 26, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlanGriffiths left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlanGriffiths left a comment

Choose a reason for hiding this comment

AlanGriffiths commented Oct 5, 2023

Saviq commented Oct 5, 2023

AlanGriffiths left a comment

Choose a reason for hiding this comment

mattkae commented Oct 6, 2023

AlanGriffiths left a comment

Choose a reason for hiding this comment

Saviq left a comment

Choose a reason for hiding this comment

mattkae commented Sep 26, 2023 •

edited

Loading

codecov bot commented Sep 26, 2023 •

edited

Loading