* Mahogany
  [[https://github.com/stumpwm/mahogany/actions/workflows/test.yml][https://github.com/stumpwm/mahogany/actions/workflows/test.yml/badge.svg]]
  [[https://github.com/stumpwm/mahogany/actions/workflows/freebsd.yml][https://github.com/stumpwm/mahogany/actions/workflows/freebsd.yml/badge.svg]]

  Mahogany is a tiling window manager for Wayland modeled after
  StumpWM. While it is not a drop-in replacement for StumpWM, StumpWM
  users should be very comfortable with Mahogany. Its planned
  features are:
  + Easy extensibility: through the use of different modes, users can
    modify keybindings present in Mahogany.
  + Module system that allows users to load and use code at their
    discretion.
  + Programs to interact with other running services such as
    pulseaudio and alsamixer, as well as facilities to control screen
    brightness. These are module based, so they don't have to be
    loaded if your system doesn't use them.
  + Good support for floating windows.
  + A configuration system using Common Lisp.

** Contributing / Hacking

Mahogany is still in an early stage of development. See the
[[https://github.com/stumpwm/mahogany/milestones][list of milestones]]
for features or work that is ready to be started. You can also browse the
issue list for labels marked with
[[https://github.com/stumpwm/mahogany/labels/good%20first%20issue][Good First Issue]].

In general, if it's in stumpwm and you want it, we will consider adding it. Create
an issue for the issue tracker so we can plan on how to get it done.

Before writing code, please look at [[CONTRIBUTING.md][CONTRIBUTING.md]].

** Building
   There are two parts to Mahogany: a backend library implemented in C, and
   the Common Lisp front end. Thus, you will need the following tools:
   + A C compiler (tested with GCC and clang)
   + Steel Bank Common Lisp
   + GNU Make
   + Meson

   Several dependencies are shipped with Mahogany as git
   submodules. To download them, run the following git command:

   #+BEGIN_SRC
   git submodule update --init
   #+END_SRC

To see a full example of this process, see the
[[https://github.com/stumpwm/mahogany/blob/master/.github/workflows/test.yml][CI workflow]].

*** Backend Library Dependencies
The backend library requires wlroots 0.20.x. If an appropriate
version is not available, it will be built locally. See the README in
the submodule or consult the [[https://gitlab.freedesktop.org/wlroots/wlroots/-/tree/0.19.2?ref_type=tags][project's git repo]] for information on how
to build it. The following development dependencies are also needed:
+ cairo
+ Pango

*** Common Lisp Dependencies
You will need a Common Lisp implementation. While it should run on any
version that the CFFI library supports, SBCL and CCL are tested
frequently.

The recommended way to install the dependencies is using
Quicklisp. Follow the instructions at https://www.quicklisp.org/ to
install it.

There is an automatic dependency install script that will be ran in
the next step.

*** Building And Running
At this point, all of the dependencies should be installed. You can
now run =make= in the root directory of the project to build the C
backend and the mahogany executable.
#+BEGIN_SRC sh
  make
  # if successful, run the program with interative debugging
  # enabled:
  make run
  # Can also be ran directly. The debugger will not be active:
  LD_LIBRARY_PATH=build/lib64:build/lib ./build/mahogany
#+END_SRC

If you want to build mahogany (or execute any of the other build
commands) with CCL, you can do so by specifying CCL when invoking
make:
#+BEGIN_SRC sh
  make LISP=ccl
#+END_SRC

It is possible to run mahogany in an X11 or Wayland session, and is
the recommended method of testing at this time. If running outside of
one of these sessions, do not enable the interactive CLI debugger.

*** Additional Dependencies

Mahogany requires a few external applications for some functionality.
See the [[doc/manual/default-apps.org][default applications]] section in the manual for details on how
to customize which applications are used.

+ A terminal emulator. Common ones are detected, but you may need to
  set it in your config file.
+ [[https://github.com/davatorium/rofi][Rofi]], for reading input from the user.

** Getting Started

Mahogany is currently in a pre-alpha state. Help is needed (see [[https://github.com/stumpwm/mahogany/milestones][list of
milestones]]). In particular, touchscreen, menu, dialog, and systray do not
work yet. But it has basic functionalities already.

The list of available keybindings can be found in
[[./lisp/key-bindings.lisp][lisp/key-bindings.lisp]].
You can also search the codebase for =defcommand= forms, which are
used to define commands. =C-t c= will open a terminal, and =C-t q q=
will kill Mahogany. To select a list of commands to run, you can use
the =C-t ;= keybinding.

Check out the [[./doc/manual/README.md][manual]] for how to customize the compositor's behavior. If
you are new to Stumpwm or tiling window managers in general, most
tutorials for StumpWM will be relatively useful where Mahogany has
reached feature parity with StumpWM. I like [[https://www.youtube.com/watch?v=jlF1N0R24cA][this video by James McCabe]] in
particular.

** License

Mahogany Window Manager
Copyright (C) 2020 Stuart Dilts

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.