From 04e4798c02d4b04ab1723487944671e6cb7c564c Mon Sep 17 00:00:00 2001 From: Jali Date: Tue, 28 Oct 2025 22:15:19 +0100 Subject: [PATCH] Finish script and documentation --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++----- scripts/hxi | 19 ++++++----- scripts/install.sh | 2 +- 3 files changed, 84 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index caa01d5..fa70d07 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,10 @@ 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. @@ -79,13 +83,73 @@ tests (in order) for the following build-systems: 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 editor layouts +## Launch different IDE layouts -The configuration comes with a script named `hxi`, which is installed into the -` ~/.local/bin` folder. When the script is started, it launches a new tmux -session with a randomised name. In this session, an editor is opened, with the -given parameters. Then the script looks for a file named `.tmux.layout`, which -needs to be an executeable script file. It then sources the file. and finally -attaches to the session, that was created. The sourced `.tmux.layout` file can -be used to create an individual layout for the project folder you're in, -creating new windows and panes, as needed. +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. diff --git a/scripts/hxi b/scripts/hxi index da20459..fa9c1a7 100755 --- a/scripts/hxi +++ b/scripts/hxi @@ -1,25 +1,26 @@ #!/usr/bin/zsh # Runs the IDE +PARAMS=$@ SESSIONID="IDE-${RANDOM}" -TMUX=$(where tmux) +MUX=$(where tmux) # Set editor to helix, if unset -if [ -z ${EDITOR+x} ]; then +if [[ -v EDITOR ]]; then EDITOR=$(where hx) fi # Open a new session with a random name -$TMUX new-session -d -s $SESSINID $EDITOR -$TMUX rename-window -t ${SESSIONID}:0 "TMUX IDE" +$MUX new-session -d -s $SESSIONID -x "$(tput cols)" -y "$(tput lines)" $EDITOR $PARAMS +$MUX rename-window -t ${SESSIONID}:0 "TMUX IDE" # check, if a layout file is present, and run it. -if [ -f ./.tmux.layout ]; then - source ./.tmux.layout +if [ -f ./.layout.tmux ]; then + source ./.layout.tmux fi # Finally, select the editor window in the current session, # and attach to the session -$TMUX select-window -t ${SESSIONID}:0 -$TMUX select-pane -t 0 -$TMUX attach-session -t ${SESSIONID} +$MUX select-window -t ${SESSIONID}:0 +$MUX select-pane -t 0 +$MUX attach-session -t ${SESSIONID} diff --git a/scripts/install.sh b/scripts/install.sh index 1cd4568..0dd43dd 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -1,3 +1,3 @@ #!/bin/sh mkdir -p ~/.local/bin -cp ~/.config/tmux/scripts/hxi ~/.local/bin +ln -s ~/.config/tmux/scripts/hxi ~/.local/bin/hxi