tmux/README.md

# TMUX - configuration

## Overview

This project contains a tmux-configuration, that allows loading different
plugins and layouts, that can be used to use tmux in conjunction with the helix
editor as an integrated development environment. It can be used to edit source
code, write texts with LaTeX and many other things. It requires the tmux plugin
manager to be installed, in order to provide all neccessary or desired
extensions.

## Prerequisites

Several packages must be available, in order to run the IDE in different
modes/layouts:

- [tmux](https://github.com/tmux/tmux/wiki): The terminal multiplexer itself
- [git](https://git-scm.com): The git version control system
- [tpm](https://github.com/tmux-plugins/tpm?tab=readme-ov-file): The tmux plugin
  manager
- [lazygit](https://github.com/jesseduffield/lazygit): A simple text based UI
  for using git
- [helix](https://helix-editor.com): A postmodern text editor. Replaces
  vim/neovim.
- [xclip](https://github.com/astrand/xclip): A command line interface for the
  system clipboard in X11/wayland

For some plugins, extra tools are required. These are optional, and only needed,
when the plugins are installed:

- [yq](https://github.com/mikefarah/yq): A commandline yaml parser. Required by
  [tmux nerd font window name plugin](https://github.com/joshmedeski/tmux-nerd-font-window-name).

## Installation

Before any plugins can be loaded, it is neccesary to install the plugin-manager
itself. This has to be done manually, and can easily be done by using git:

```bash
git submodule add https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
```

Then, the `tmux.conf` file can be used. Make sure, when editing the file, that
the structure of the file is kept. It is mandatory, that the tpm command must
remain at the end of the file at all times for TPM to work properly!

After adding a plugin, press **Ctrl+\<prefix> I** to install the plugins.

Finally, you can run `sh ~./config/tmux/scripts/install.sh`. This will create a
symbolic link to the `hxi`-Script in your local `bin` folder. `~/.local/bin`.
Make sure the folder is in your `$PATH` variable.

## Basic usage

Independent from the layout you use, the basic usage is standard tmux operation.
You can use the tmux commands to split and control windows, and manage your
terminal window layoout. There are, however, some extra functions.

## Manage git

In order to manage your git repositories, without having to switch to a blank
terminal, press `Ctrl+<prefix> g`. This will open `lazygit` in a popup, that
overlays your current layoout. To close the window, all that is needed, is to
quit `lazygit` by pressing `q`.

## Open an ai chat window

To open a chat window to confer with your ai-bot in chatmode, you can easily
open a chatwindow to the left of your main window. To do so, press
`Ctrl+<prefix> a`. To close the window, press `Ctrl+d`.

## Building

Sometime you want to bulild your project. In this configuration a key-binding is
added to the F9 key. Pressing `Ctrl+<prefix> F9` will run a make-script that
tests (in order) for the following build-systems:

- [WAF](https://waf.io)
- [Cargo](https://doc.rust-lang.org/cargo/commands/cargo-build.html)
- [CMake](https://cmake.org/)
- [Automake](https://www.gnu.org/software/automake/)

The process will open a popup window, in which the build is performed. After the
build stops, the window will stay open until a key is pressed.

## Launch different IDE layouts

The main point of this tmux installation is to use tmux as an IDE-replacement.
This means, it's central element is an editor, in our case the
[helix](https://helix-editor.com) editor. To call tmux and open an editor, use
the `hxi` command. This command will open an instance of helix inside a unique
tmux session. This allows you to have several instances open at the same time,
each in a separate session. The editor that is used, can be your favourite
editor, as it is taken from the `$EDITOR` variable. But we assume here, it's
helix.

When calling `hxi` a tmux session will be opened, with your editor in the only
window and pane that is opened. However, depending on your environment, you
might want to organize some other panes on your window as well. The trouble is:
They may differ, depending on the project, your working on. Maybe you'll need a
simple terminal, maybe you'll need an ssh connection to a remote computer, or a
monitoring tool. In order to provide this on an as-needed-basis, you can place a
file named `./layout.tmux` inside your project folder. Whenever you launch
`hxi`, the script will look for a file of that name, and execute it. The file
will be executed after the tmux-session is created and the editor opened, but
before the scriopt connects to the session. It's main purpose is to use the
`tmux` command to reconfigure the environment, but it can be used to perform any
action you want to be executed before the session starts. It's only parameter is
the sessionid, that is passed from `hxi`. Every `tmux`-command needs to pass
this on, to make sure the correct session is configured.

As an example, let's assume, you want to work on your PIDP-10 Assembler project.
To do this, you'd like the editor to open, and have two panes below: One showing
the PDP 10's system console, and the other giving you a command line on the
Raspberry Pi in order to be able to copy data between the Pi and the simulated
PDP 10. The following `.layout.tmux` file allows for this.

```bash
#!/usr/bin/zsh
# Create a layout for development on the PDP-10
RPDP=$(where rpdp)

# Split the window at the bottom and open a
$MUX split-window -v -l 8 -t ${SESSIONID}:0 telnet pidp10.local 1025

# Split again, and connect via ssh to the host machine
$MUX split-window -h -t ${SESSIONID}:0 ssh pidp10.local

# Finally, start an instance of the Knight-TV console
if [[ -v RPDP ]]; then
  $RPDP tvcon
fi
```

There are two variables, that the script inherits from `hxi`: `$SESSIONID`
contains the id of the current tmux session. The `$MUX` variable contains the
path to the tmux-command itself. If you use the tmux-command, always pass
`-t $SESSIONID` to it, so the command gets executed on the correct session.

In the line

```bash
$MUX split-window -v -l 8 -t ${SESSIONID}:0 telnet pidp10.local 1025
```

the editor window is split vertially, so the new pane is 8 lines high below the
edior. The split window contains a call to the telnet connection of the PDP 10,
that connects to the system console.

The next line splits the new pane again, this time horizontally, and create a
thrird pane, with an SSH-session to the PDP 10's host system.

The final lines are an example of calling an external service from the start
script: It will check if the `rpdp` tool is installed, and -if so- run the
Knight-TV-Terminal emulatior, which will open in a separate window.