$ autoreconf -fi +$ mkdir -p build && cd build +$ ../configure +$ make -j8+
You can build i3 like you build any other software package which uses autotools. +Hereâs a memory refresher:
$ autoreconf -fi +$ mkdir -p build && cd build +$ ../configure +$ make -j8+
(The autoreconf -fi step is unnecessary if you are building from a release tarball, + but shouldnât hurt either.)
+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. +
++âmake checkâ runs the i3 testsuite. See docs/testsuite for details. +
++âmake distcheckâ (runs testsuite on âmake distâ result, tiny bit quicker + feedback cycle than waiting for the travis build to catch the issue). +
++â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. +
++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. +
++Support for pre-compiled headers (PCH) has been dropped for now in the + interest of simplicity. If you need support for PCH, please open an issue. +
++Coverage reports are now generated using âmake check-code-coverageâ, which + requires specifying --enable-code-coverage when calling configure. +
+For a short introduction into using git, see +https://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy +or, for more documentation, see https://git-scm.com/documentation
Please talk to us before working on new features to see whether they will be +accepted. A good way for this is to open an issue and asking for opinions on it. +Even for accepted features, this can be a good way to refine an idea upfront. However, +we don’t want to see certain features in i3, e.g., switching window focus in an +Alt+Tab like way.
When working on bugfixes, please make sure you mention that you are working on +it in the corresponding bug report at https://github.com/i3/i3/issues. In case +there is no bug report yet, please create one.
After you are done, please submit your work for review as a pull request at +https://github.com/i3/i3.
Do not send emails to the mailing list or any author directly, and donât submit +them in the bugtracker, since all reviews should be done in public at +https://github.com/i3/i3. In order to make your review go as fast as possible, you +could have a look at previous reviews and see what the common mistakes are.
Work on i3 generally happens in two branches: âmasterâ and ânextâ (the latter +being the default branch, the one that people get when they check out the git +repository).
The contents of âmasterâ are always stable. That is, it contains the source code +of the latest release, plus any bugfixes that were applied since that release.
New features are only found in the ânextâ branch. Therefore, if you are working +on a new feature, use the ânextâ branch. If you are working on a bugfix, use the +ânextâ branch, too, but make sure your code also works on âmasterâ.
A window manager is not necessarily needed to run X, but it is usually used in combination with X to facilitate some things. The window manager’s job is to @@ -124,7 +228,7 @@ React to the userâs commands: Change focus, Move windows, Switch workspaces,
In the following chapters, each of these tasks and their implementation details will be discussed.
Traditionally, there are two approaches to managing windows: The most common one nowadays is floating, which means the user can freely move/resize the windows. The other approach is called tiling, which means that your window @@ -143,7 +247,7 @@ layout (like dwm, awesome, â¦) but provide mechanisms for you to easily create the layout you need at the moment.
The data structure which i3 uses to keep track of your windows is a tree. Every node in the tree is a container (type Con). Some containers represent actual windows (every container with a window != NULL), some represent split @@ -154,13 +258,13 @@ the same split container, which uses the default layout. In case of an empty workspace, the split container we are talking about is the workspace.
To get an impression of how different layouts are represented, just play around and look at the data structures — they are exposed as a JSON hash. See -http://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an +https://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an example.
See include/data.h for documented data structures. The most important ones are explained right here.
The data type is Con, in all cases.
The X11 root window is a single window per X11 display (a display is identified by :0 or :1 etc.). The root window is what you draw your background image on. It spans all the available outputs, e.g. VGA1 is a specific part of the root window and LVDS1 is a specific part of the root window.
Every active output obtained through RandR is represented by one output container. Outputs are considered active when a mode is configured (meaning something is actually displayed on the output) and the output is not a clone.
Each output has multiple children. Two of them are dock containers which hold dock clients. The other one is the content container, which holds the actual content (workspaces) of this output.
A workspace is identified by its name. Basically, you could think of workspaces as different desks in your office, if you like the desktop metaphor. They just contain different sets of windows and are completely @@ -524,7 +628,7 @@ separate of each other. Other window managers also call this “Virtual desktops”.
A split container is a container which holds an arbitrary amount of split containers or X11 window containers. It has an orientation (horizontal or vertical) and a layout.
An X11 window container holds exactly one X11 window. These are the leaf nodes of the layout tree, they cannot have any children.
i3 makes heavy use of the list macros defined in BSD operating systems. To ensure that the operating system on which i3 is compiled has all the expected @@ -554,7 +658,7 @@ selected window to the window above/below.
There is a row of standard variables used in many events. The following names should be chosen for those:
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 @@ -644,7 +748,7 @@ check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it will handle the event, if not, it will replay the event.
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 @@ -655,7 +759,7 @@ event.
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 @@ -711,7 +815,7 @@ can reconfigure themselves).
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 @@ -731,7 +835,7 @@ if present.
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 @@ -740,7 +844,7 @@ characters (every special character contained in your font).
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 @@ -753,7 +857,7 @@ src/layout.c, function resize_client().
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 @@ -773,7 +877,7 @@ container and then pushing the changes to X11. The following sections talk about the different rendering steps, in the order of "top of the tree" (root container) to the bottom.
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 @@ -836,20 +940,20 @@ Recursively raise and render the outputâs child containers (meaning dock
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). If a child is a leaf node (as opposed to a split container) and has border style "normal", appropriate space will be reserved for its window decoration.
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 @@ -860,20 +964,20 @@ reserved (or displayed later on), unless there is more than one window inside the stacked container.
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 @@ -932,7 +1036,7 @@ Expose event handling (drawing decorations): x_deco_recurse() and
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 @@ -1042,7 +1146,7 @@ unmapped if it should not be visible anymore. WM_STATE will be set to WM_STATE_WITHDRAWN.
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 @@ -1061,7 +1165,7 @@ and "1pixel") and the top bar (in case of border style "normal").
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, @@ -1103,7 +1207,7 @@ which will be compared with the input. An action is either the name of a state in which the parser will transition into, or the keyword call, followed by the name of a function (and optionally a state).
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:
For a short introduction into using git, see -http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy -or, for more documentation, see http://git-scm.com/documentation
Please talk to us before working on new features to see whether they will be -accepted. A good way for this is to open an issue and asking for opinions on it. -Even for accepted features, this can be a good way to refine an idea upfront. However, -we don’t want to see certain features in i3, e.g., switching window focus in an -Alt+Tab like way.
When working on bugfixes, please make sure you mention that you are working on -it in the corresponding bug report at https://github.com/i3/i3/issues. In case -there is no bug report yet, please create one.
After you are done, please submit your work for review as a pull request at -https://github.com/i3/i3.
Do not send emails to the mailing list or any author directly, and donât submit -them in the bugtracker, since all reviews should be done in public at -https://github.com/i3/i3. In order to make your review go as fast as possible, you -could have a look at previous reviews and see what the common mistakes are.
Work on i3 generally happens in two branches: âmasterâ and ânextâ (the latter -being the default branch, the one that people get when they check out the git -repository).
The contents of âmasterâ are always stable. That is, it contains the source code -of the latest release, plus any bugfixes that were applied since that release.
New features are only found in the ânextâ branch. Therefore, if you are working -on a new feature, use the ânextâ branch. If you are working on a bugfix, use the -ânextâ branch, too, but make sure your code also works on âmasterâ.
You can build i3 like you build any other software package which uses autotools. -Hereâs a memory refresher:
$ autoreconf -fi -$ mkdir -p build && cd build -$ ../configure -$ make -j8-
(The autoreconf -fi step is unnecessary if you are building from a release tarball, - but shouldnât hurt either.)
-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. -
--âmake checkâ runs the i3 testsuite. See docs/testsuite for details. -
--âmake distcheckâ (runs testsuite on âmake distâ result, tiny bit quicker - feedback cycle than waiting for the travis build to catch the issue). -
--â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. -
--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. -
--Support for pre-compiled headers (PCH) has been dropped for now in the - interest of simplicity. If you need support for PCH, please open an issue. -
--Coverage reports are now generated using âmake check-code-coverageâ, which - requires specifying --enable-code-coverage when calling configure. -
-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, @@ -1601,7 +1600,7 @@ but if you are interested in one of the topics they cover, you should read them before asking us why things are the way they are or why we donât implement things.
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