# 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+\ 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+ 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+ 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+ 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.