awm/README.md

awm – Alacritty Window Manager

A simple WM to manage your Alacritty terminal windows.

What is AWM?

Alacritty Window Manager (AWM) is a Window Manager (WM) akin to software like DWM which is responsible for tiling windows open on the desktop into appropriate layout configurations. It differs from conventional window tiling acheived by dragging window tabs into different regions of a desktop environment, simply because WMs are used in non-DEs whereby this mechanic does not exist. Windows which also lack decoration frames to allow them to be moved via dragging benefit from WMs correctly arranging them.

Now, AWM does not take any inspiration from DWM, more than what DWM takes from general WMs. AWM works with the Win32 API, whereas DWM works with X11, so everything within the APIs will be completely different. DWM is also a general WM for tiling all windows on a system, and AWM works only for Alacritty terminals.

Why Does AWM Exist?

Why do WMs exist in general? They're sleek-looking, organise windows in an easy fashion, do better jobs than DEs, amongst many more reason. The main reason is that if a window GUI is created without a frame, there's no easy way to then move that window, let alone to a specific location on a screen.

AWM achieves all of this. It allows for no decoration on Alacritty windows, whilst being able to organise up to four windows Alacritty creates for terminal sessions. And this is all for Windows to make life much easier for users, whilst still looking like novice ricers.

How Does AWM Work?

Well, AWM is heavily documented in the code base, which consists of a single C++ file. But the short version is as followed:

• When awm is executed, it will go and find all windows associated with Alacritty (up to 4 at most).
• Once it has found the windows, it organises them based on a set of predefined configurations depending on the number of windows found.
• This occurs simultaneously to give a smooth organisation transition for any number of Alacritty terminal windows.

It's that simple. No additional event listeners/hooks, no spawning new processes.

For a more in-depth, and technically explanation where applicable, consult the main.cpp found in the root directory of the project's workspace.

How to Install AWM

Currently, the only way to install AWM is by manually compiling the binary and placing it somewhere in your local user-space and adding that to your path. You may wish to keep the compiled binary in the repo and have your path point to that location.

Compiling can be performed with any compiler. There's no linking of other libraries or C++ source files, assuming that the appropriate header files are installed to the system, it should just compile.

However, the only compiler that has been used for AWM is the g++ compiler by GNU. If you have this compiler installed, the following command will compile the binary on your system (CWD set to the awm repo):

mkdir bin
g++ -O3 -std=c++11 main.cpp -o bin\awm.exe

Compilation should compile without any errors, and any such which are reported might be due to missing header files. Please consult the main.cpp file for the relavent header files and/or libraries.

Afterwards, you can add the bin directory to your local Path (or system-wide with appropriate pivilage levels). Something as followed in PowerShell will allow AWM to be ran anywhere on the system:

$env:Path += ';\path\to\awm\bin'

How to Use AWM

AWM can simply be called directly as a program, and will attempt to organise any Alacritty windows it identifies. However, a more useful usage would be via Alacritty keybindings. This can be simply achieved in the alacritty.yml configuration file using the command action.

The following is an example keybinding configuration which can be used in Alacritty (with respect to potential conflicts with other bindings). Open the YAML file in an editor (typically located at %APPDATA%\alacritty\alacritty.yml) and add the following line:

key_bindings:
  - { key: O, mods: Control|Shift, command: { program: "awm", args: [] } }

This will then call AWM wherever its located on the system via Path and organise Alacritty windows accordingly.

Note: AWM does not listen for when Alacritty windows are created or destroyed. It simply organises windows it's able to collect in a tiled manner when told to.

AWM Features

AWM comes with a couple different features, notably the WM itself.

• Window Manager – the core functionality of AWM. This goes without say that it's the biggest and primary feature of AWM (AWM does what it says on the tin). It supports up to four layouts of Alacritty instances, but does not organise new Alacritty windows.
• Fullscreen Terminals – AWM supports toggling Alacritty terminals into fullscreen. This doesn't hide the taskbar, nor consume the entire desktop work area, but it does take up majority of the desktop. This allows for greater focus and work area within a selected terminal, hiding other windows behind. Run awm --fullscreen to toggle this behaviour. When exiting fullscreen, the window will be placed back in its original tiled configuration with other Alacritty instances.

Known Issues & Limitations

With AWM Itself

As discussed in the note above, and elsewhere, AWM does not add event hooks to the system, or listen to any event hooks that might trigger when an Alacritty window is created or destroyed. For this reason, AWM must be manually told when to organise windows on the desktop. If this feature is to be required, a separate executable should be created to handle these hook events and compile AWM into its binary to then call the existing WM source code.

Another known issue is with Task Manager and not compiling with at least -O3. Put simply, if the binary is compiled without this optimisation flag, and Task Manager is open, AWM will fail to organise the windows due to Task Manager. It's currently unknown why this bug exists without -O3, and doesn't with the flag, but it can be easily avoided with the -O3 flag using g++. A future patch may be applied to this in the future.

Due to Alacritty

It seems that there might be a few issues as a result of Alacritty (or perhaps within the dependencies it uses). Firstly, after some more in-depth experimentation of the Win32 API, it seems as though Alacritty does not set the correct flags on a window defined in the API to indicate that a window is minimised. This makes it impossible for AWM to correctly filter non-viewable terminals out of organisation.

Shared & Due to Knowledge

When a new window is created in Alacritty, it simply spawns a new Console Host program (conhost.exe). This is specific to Windows and whose purpose is out of the scope of this document. However, it means that a single alacritty.exe program exists with multiple conhost applications running PowerShell. From experiments, you can't simply change the window's context of conhost apps without causing some mischievious behaviour. A conhost app will refer back to Alacritty in some way, but it's not possible to refer to Alacritty for changing the context of a window. Or at least, it's not possible with the current knowledge of the project. Alacritty might be behaving exactly as intended of Windows' apps, but as it stands, AWM cannot organise new windows of Alacritty, only new instances.

Licence

This project is licenced until the GNU GPLv3+ licence agreement, which can be viewed in the LICENCE.txt file in the root directory of the repository.

Author

Ethan Smith-Coss (ethan.sc@closedless.xyz)

Bug Tracker

To report a bug, or feature of the program, an Issue can be created with the relavent information.