you understand why things are like they are. If it does not mention something
you find necessary, please do not hesitate to contact me.
+== Building i3
+
+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.)
+
+=== Build system features
+
+* 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.
+
+== Using git / sending patches
+
+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.
+
+=== Which branch to use?
+
+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”.
+
== Window Managers
A window manager is not necessarily needed to run X, but it is usually used in
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.
== Files
src/config.c::
Contains all functions handling the configuration file (calling the parser
-(src/cfgparse.y) with the correct path, switching key bindings mode).
-
-src/debug.c::
-Contains debugging functions to print unhandled X events.
+src/config_parser.c) with the correct path, switching key bindings mode).
src/ewmh.c::
Functions to get/set certain EWMH properties easily.
function, which was moved into its own file because it is so long.
src/util.c::
-Contains useful functions which are not really dependant on anything.
+Contains useful functions which are not really dependent on anything.
src/window.c::
Handlers to update X11 window properties like +WM_CLASS+, +_NET_WM_NAME+,
itself for the container’s children. This function actually pushes the
state, see the next paragraph.
4. If the pointer needs to be warped to a different position (for example when
- changing focus to a differnt output), it will be warped now.
+ changing focus to a different output), it will be warped now.
5. The eventmask is restored for all mapped windows.
6. Window decorations will be rendered by calling +x_deco_recurse+ on the root
container, which then recursively calls itself for the children.
Afterwards, +con_focus+ will be called to fix the focus stack and the tree will
be flattened.
-=== Case 3: Moving to non-existant top/bottom
+=== Case 3: Moving to non-existent top/bottom
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
Now, +con_focus+ will be called to fix the focus stack and the tree will be
flattened.
-=== Case 4: Moving to existant top/bottom
+=== Case 4: Moving to existent top/bottom
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
not relative to workspace boundaries, so you must correct their coordinates
or those containers will show up in the wrong workspace or not at all.
-== Using git / sending patches
-
-=== Introduction
-
-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.
-
-=== Which branch to use?
-
-Work on i3 generally happens in two branches: “master” and “next”. Since
-“master” is what people get when they check out the git repository, its
-contents 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”.
-
== Thought experiments
In this section, we collect thought experiments, so that we don’t forget our
projects / i3 / i3 / blobdiff