diff options
author | S. Christoffer Eliesen <christoffer@eliesen.no> | 2015-11-15 12:59:21 +0100 |
---|---|---|
committer | S. Christoffer Eliesen <christoffer@eliesen.no> | 2015-11-15 22:55:02 +0100 |
commit | 2f7f8512bde84d4c8bdc721f75822fcf481de72c (patch) | |
tree | fb799b8c0870ea63cb5224e9a72860c79b92bc9e /HACKING.md | |
parent | We somewhat more wlc_point now (diff) | |
download | sway-2f7f8512bde84d4c8bdc721f75822fcf481de72c.tar.gz sway-2f7f8512bde84d4c8bdc721f75822fcf481de72c.tar.zst sway-2f7f8512bde84d4c8bdc721f75822fcf481de72c.zip |
HACKING.md: Add code overview section.
Diffstat (limited to 'HACKING.md')
-rw-r--r-- | HACKING.md | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 00000000..25d737a3 --- /dev/null +++ b/HACKING.md | |||
@@ -0,0 +1,81 @@ | |||
1 | ## Code overview | ||
2 | |||
3 | The following is a brief code overview / general introduction for those wanting | ||
4 | to hack on sway. | ||
5 | |||
6 | ### wlc | ||
7 | |||
8 | In Wayland the compositor is the display server. That's a design decision that | ||
9 | brings several advantages, but the downside is that all compositors need to | ||
10 | implement an entire display server as well. | ||
11 | |||
12 | To aid the situation there are several *wayland display servers* being | ||
13 | implemented as libraries so that compositors can stick to doing compositing and | ||
14 | leave the low level details to one of those libraries. In sway that library is | ||
15 | `wlc`, and it handles tty switching, logind sessions, input, everything that | ||
16 | deals with the GPU, and just about everything concerning the Wayland protocol | ||
17 | itself (as of writing there's not a single call to any wayland functions inside | ||
18 | of sway). sway communicates with wlc via a callback api found in | ||
19 | `sway/handlers` (`wlc_interface`). The code in that file deals with all the | ||
20 | entry points from wlc to sway. | ||
21 | |||
22 | ### Commands | ||
23 | |||
24 | Being a tiling window manager, controlling it via commands is an important part | ||
25 | of its functionality, and `sway/commands` which deals with that is by far the | ||
26 | biggest file in the codebase. | ||
27 | |||
28 | There are multiple ways to trigger a command: via the keyboard, via the config | ||
29 | file, or via the IPC interface. | ||
30 | |||
31 | ### IPC | ||
32 | |||
33 | i3 has an IPC interface (it creates a socket that applications can connect to | ||
34 | and issue commands or queries via its protocol), and sway replicates that | ||
35 | protocol (so e.g. `i3-msg` can be used with sway by simply changing the socket, | ||
36 | e.g. `i3-msg -s $(sway --get-socketpath)`). The code for that lies in | ||
37 | `sway/ipc`. | ||
38 | |||
39 | ### Config | ||
40 | |||
41 | The config state and loading the config file lies in `sway/config`. Since the | ||
42 | config file is simply a list of commands, that code mostly just parses the text | ||
43 | and then hands commands off to `commands` for execution. | ||
44 | |||
45 | ### Pointer handling | ||
46 | |||
47 | The mouse has buttons, state (due to buttons pressed, e.g. "dragging", | ||
48 | "resizing" etc.) and movement. Most code related to that lies in | ||
49 | `sway/input_state`. | ||
50 | |||
51 | ### Containers | ||
52 | |||
53 | In traditional *floating* window managers, all windows (or *views* as they're | ||
54 | called in sway) are placed anywhere on the screen. In a tiling window manager | ||
55 | like sway the views are *arranged* by the compositor, and the user mostly just | ||
56 | manipulates the arrangement via commands (floating views are also supported). | ||
57 | |||
58 | In sway, each *output* (a physical monitor) has one or more *workspaces* which | ||
59 | has one or more *views* (the actual windows). In order to keep track of the | ||
60 | arrangement of the views, sway organizes everything in a tree of *containers*. | ||
61 | Each of the previously mentioned things is a type of container. In addition | ||
62 | there's a type of container called *container* which is needed to arrange other | ||
63 | containers as siblings (horizontal or vertical layout), and a *root container* | ||
64 | which exists for practical reasons. | ||
65 | |||
66 | `sway/containers` contains the code for this and understanding containers is | ||
67 | essential in understanding sway. | ||
68 | |||
69 | Also, the code that actually arranges the different views lays in | ||
70 | `sway/layout`. | ||
71 | |||
72 | ### Focus | ||
73 | |||
74 | When changing workspace, changing output, changing view or just moving the | ||
75 | pointer you change which view has *focus*. The code for handling this and | ||
76 | e.g. deciding what view receives input events is handled in `sway/focus`. | ||
77 | |||
78 | ### Notes | ||
79 | |||
80 | As sway is a work in progress, as of writing it is still not versioned. Use the | ||
81 | `master` branch of sway and wlc for now. | ||