++++
This document is not 100% up to date. Specifically, everything up to and
-including <
This document is not 100% up to date. Specifically, everything up to and -including [data_structures] has been updated recently. The rest might contain +including [startup] has been updated recently. The rest might contain outdated information.
-We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate - directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building - in a separate directory is common practice anyway. In case this causes any - trouble when packaging i3 for your distribution, please open an issue. +ninja test runs the i3 testsuite. See docs/testsuite for details.
-make check runs the i3 testsuite. See docs/testsuite for details. +meson dist builds a release tarball and runs tests on the result.
-make distcheck (runs testsuite on make dist result, tiny bit quicker - feedback cycle than waiting for the travis build to catch the issue). +meson -Ddocs=true -Dmans=true will enable the options to build docs and + manpages. These options require additional dependencies that are normally not + required for users who just want to build i3.
-make uninstall (occasionally requested by users who compile from source) -
--make will build manpages/docs by default if the tools are installed. - Conversely, manpages/docs are not tried to be built for users who don’t want - to install all these dependencies to get started hacking on i3. Manpages and - docs can be disabled with the --disable-mans and --disable-docs+ - configure options respectively. -
--non-release builds will enable address sanitizer by default. Use the - --disable-sanitizers configure option to turn off all sanitizers, and see - --help for available sanitizers. -
--Coverage reports are now generated using make check-code-coverage, which - requires specifying --enable-code-coverage when calling configure. +meson -Db_sanitize=address will enable the address sanitizer which is + disabled by default. A summary of memory leaks will be printed on program + exit. This can include false-positives. For other options of the b_sanitize + flag see https://mesonbuild.com/Builtin-options.html.
The lists used are SLIST (single linked lists), CIRCLEQ (circular -queues) and TAILQ (tail queues). Usually, only forward traversal is necessary, -so an SLIST works fine. If inserting elements at arbitrary positions or at -the end of a list is necessary, a TAILQ is used instead. However, for the -windows inside a container, a CIRCLEQ is necessary to go from the currently -selected window to the window above/below.
The lists used are SLIST (single linked lists), CIRCLEQ (circular queues) +and TAILQ (tail queues). Usually, TAILQ is used which allows inserting +elements at arbitrary positions or at the end of the list. If only forward +traversal is necessary, an SLIST can be used. CIRCLEQ is used just to +manage the X11 state of each window.
There is a row of standard variables used in many events. The following names -should be chosen for those:
Among other things, the main() function does the following:
-conn is the xcb_connection_t +Establish the xcb connection
-event is the event of the particular type +Load the i3 config
-con names a container +Check for XKB extension on the separate X connection, load Xcursor
-current is a loop variable when using TAILQ_FOREACH etc. +Set up EWMH hints
-Establish the xcb connection +Grab the keycodes for which bindings exist
-Check for XKB extension on the separate X connection, load Xcursor +Check for XRandR screens
-Check for RandR screens (with a fall-back to Xinerama) +Manage all existing windows
-Grab the keycodes for which bindings exist +Exec configured startup processes
-Manage all existing windows +Start i3bar if configured
Grabbing the bindings is quite straight-forward. You pass X your combination of modifiers and the keycode you want to grab and whether you want to grab them actively or passively. Most bindings (everything except for bindings using @@ -653,7 +623,7 @@
As mentioned in "Grabbing the bindings", upon a keypress event, i3 first gets the correct state.
Then, it looks through all bindings and gets the one which matches the received @@ -664,7 +634,7 @@
manage_window() does some checks to decide whether the window should be managed at all:
i3 does not care about applications. All it notices is when new windows are mapped (see src/handlers.c, handle_map_request()). The window is then @@ -720,7 +690,7 @@
Only the _NET_WM_STATE_FULLSCREEN and _NET_WM_STATE_DEMANDS_ATTENTION atoms are handled.
When the WM_NAME property of a window changes, its decoration (containing the title) is re-rendered. Note that WM_NAME is in COMPOUND_TEXT encoding which is @@ -740,7 +710,7 @@
Like WM_NAME, this atom contains the title of a window. However, _NET_WM_NAME is encoded in UTF-8. i3 will recode it to UCS-2 in order to be able to pass it @@ -749,7 +719,7 @@
Size hints specify the minimum/maximum size for a given window as well as its aspect ratio. This is important for clients like mplayer, who only set the @@ -762,7 +732,7 @@
Rendering in i3 version 4 is the step which assigns the correct sizes for borders, decoration windows, child windows and the stacking order of all @@ -782,7 +752,7 @@
The i3 root container (con→type == CT_ROOT) represents the X11 root window. It contains one child container for every output (like LVDS1, VGA1, …), which is available on your computer.
Output containers (con→layout == L_OUTPUT) represent a hardware output like LVDS1, VGA1, etc. An output container has three children (at the moment): One content container (having workspaces as children) and the top/bottom dock area @@ -845,18 +815,18 @@
From here on, there really is no difference anymore. All containers are of con→type == CT_CON (whether workspace or split container) and some of them have a con→window, meaning they represent an actual window instead of a split container.
In default layout, containers are placed horizontally or vertically next to each other (depending on the con→orientation).
In stacked layout, only the focused window is actually shown (this is achieved by calling x_raise_con() in reverse focus order at the end of render_con()).
The available space for the focused window is the size of the container minus @@ -867,20 +837,20 @@
Tabbed layout works precisely like stacked layout, but the window decoration position/size is different: They are placed next to each other on a single line (fixed height).
This is a special case. Users cannot choose the dock area layout, but it will be set for the dock area containers. In the dockarea layout (at the moment!), windows will be placed above each other.
A window’s size and position will be determined in the following way:
A big problem with i3 before version 4 was that we just sent requests to X11 anywhere in the source code. This was bad because nobody could understand the @@ -939,7 +909,7 @@
In general, the function x_push_changes should be called to push state changes. Only when the scope of the state change is clearly defined (for example only the title of a window) and its impact is known beforehand, one can @@ -1049,7 +1019,7 @@
x_draw_decoration draws window decorations. It is run for every leaf container (representing an actual X11 window) and for every non-leaf container which is in a stacked/tabbed container (because stacked/tabbed containers @@ -1068,7 +1038,7 @@
In the configuration file and when using i3 interactively (with i3-msg, for example), you use commands to make i3 do things, like focus a different window, @@ -1110,7 +1080,7 @@
Let’s have a look at the WORKSPACE state, which is a good example of all features. This is its definition:
The following steps have to be taken in order to properly introduce a new command (or possibly extend an existing command):
The movement code is pretty delicate. You need to consider all cases before making any changes or before being able to fully understand how it works.
The reference layout for this case is a single workspace in horizontal orientation with two containers on it. Focus is on the left container (1).
The reference layout for this case is a horizontal workspace with two containers. The right container is a v-split with two containers. Focus is on the left container (1).
Like in case 1, the reference layout for this case is a single workspace in horizontal orientation with two containers on it. Focus is on the left container:
The reference layout for this case is a vertical workspace with two containers. The bottom one is a h-split containing two containers (1 and 2). Focus is on the bottom left container (1).
The reference layout for this case is a horizontal workspace with two containers having a v-split on the left side with a one-child h-split on the bottom. Focus is on the bottom left container (2(h)):
The reference layout for this case is a horizontal workspace with two containers plus one floating h-split container. Focus is on the floating container.
Without much ado, here is the list of cases which need to be considered:
In this section, we collect thought experiments, so that we don’t forget our thoughts about specific topics. They are not necessary to get into hacking i3, @@ -1503,7 +1473,7 @@
cgroups (control groups) are a linux-only feature which provides the ability to group multiple processes. For each group, you can individually set resource limits, like allowed memory usage. Furthermore, and more importantly for our