===== HERBSTLUFTWM =====

Copyright Thorsten Wißmann and contributors. All rights reserved.

This software is licensed under the "Simplified BSD License".
See LICENSE for details.

==== Requirements ====
Build dependencies:

    - build environment (e.g. gcc or clang, make)
    - CMake 3.1 or later
    - asciidoc (only when building from git, not when building from tarball)
    - a posix system with _POSIX_TIMERS and _POSIX_MONOTONIC_CLOCK or a system
      with a current mach kernel

Runtime dependencies:

    - bash (if you use the default autostart file)
    - libx11
    - xft and freetype
    - xrandr
    - optionally: xinerama

Optional run-time dependencies:

    - xsetroot (to set wallpaper color in default autostart)
    - xterm (used as the terminal in default autostart)
    - dzen2 (used in the default panel.sh, it works best with a new dzen2 which
             already supports clicking)
    - dmenu (used in some example scripts)

==== Help/Support/Bugs ====
If you found a bug or want to request features then open an issue on
https://github.com/herbstluftwm/herbstluftwm/issues or contact the mailing list.
(The subscription process is explained in the HACKING file).

Mailing list: hlwm@lists.herbstluftwm.org

For instant help join the IRC channel: #herbstluftwm on irc.libera.chat

==== Installation steps ====
If you are using a system with a package manager, we recommend to install via
the package manager of your distribution! If you are not allowed to install
software, you should contact your system administrator.

You only need to install herbstluftwm manually if you do not like package
managers or if you are creating a package for your distribution.

The CMake build system is used. It is recommended to use an out-of-tree build
directory. The compilation and installation is configured by the following CMake
variables which you can set on the initial cmake call and alter with ccmake:

    CMAKE_INSTALL_PREFIX         = /usr/            # the prefix
    CMAKE_INSTALL_SYSCONF_PREFIX = $(DESTDIR)/etc/  # path to etc directory

Individual paths for special files can be set with the *DIR variables, typically
relative to CMAKE_INSTALL_PREFIX. If you are building a package, you would
typically build regularly, and install with DESTDIR=./path/to/fakeroot. If you
are building from a source tarball, you can disable WITH_DOCUMENTATION because
the built documentation is already contained in the tarball.

    mkdir build && cd build
    cmake ..
    make
    sudo make DESTDIR=./pkg/ install

To use the software locally, create your own autostart file:

    mkdir -p ~/.config/herbstluftwm/
    cp /etc/xdg/herbstluftwm/autostart ~/.config/herbstluftwm/autostart

==== Trying herbstluftwm ====
If you want to give herbstluftwm a quick try, then you can use the
valgrind-xephyr.sh from your existing X session:

    mkdir -p build && cd build && cmake .. && make && ../valgrind-xephyr.sh

==== First steps without installing ====
1. create and switch to a build directory:

    mkdir build && cd build

2. compile:

    cmake ../
    make

3. copy herbstclient to a bin-folder or adjust path in autostart file
4. copy default autostart file to the config-dir:

    mkdir -p ~/.config/herbstluftwm
    cp share/autostart ~/.config/herbstluftwm/

5. copy share/herbstclient-completion.bash to your
   /usr/share/bash-completion/completions folder (and rename it to herbstclient)
   or source it in your bashrc
6. run it in a session that has no window manager yet

==== Starting Herbstluftwm ====
To start the window manager within a running X-session, execute:

    herbstluftwm --locked

`--locked` causes herbstluftwm not to update the screen until you unlock it
with: `herbstclient unlock` (This is done automatically by the default autostart)

==== Quirks ====
Mac OSX:

Problem: Mod1 is nowhere to be found.

Solution: Set left Command (Apple) key to be Mod1.

Edit .Xmodmap:

    --- snip ---
    ! Make the Alt/Option key be Alt_L instead of Mode_switch
    keycode 63 = Alt_L
    
    ! Make Meta_L be a Mod4 and get rid of Mod2
    clear mod2
    clear mod4
    add mod4 = Meta_L
    
    ! Make Alt_L be a Mod1
    clear mod1
    add mod1 = Alt_L
    --- snap ---

// vim: nowrap ft=asciidoc tw=80
