hstr/INSTALLATION.md

# Installation

Install:

* [Ubuntu](#ubuntu)
* [Fedora](#fedorarhelcentosscientific)
* [Gentoo](#gentoo)
* [CentOS](#fedorarhelcentosscientific)
* [openSUSE](#opensuse)
* [RHEL](#fedorarhelcentosscientific)
* [Debian](#debianmint)
* [Mint](#debianmint)
* [Alpine Linux](#alpine-linux)
* [Arch Linux](#archmanjaro-linux)
* [Milis Linux](#milis-linux)
* [Manjaro Linux](#archmanjaro-linux)
* [Scientific Linux](#fedorarhelcentosscientific)
* [Haiku OS](#haiku-os)
* [macOS](#macos)
* [nix package manager](#nix-package-manager)
* [Guix package manager](#guix-package-manager)
* [MPR package manager](#mpr-package-manager)

Build:

* [build on any Linux distro](#build-on-any-linux-distro)
* [build snap](#build-snap)
* [build on Ubuntu](#build-on-ubuntu)
* [build on Debian](#build-on-debian)
* [build on Fedora](#build-on-fedora)
* [build on Windows Subsystem for Linux (WSL)](#build-on-wsl)
* [build on Cygwin](#build-on-cygwin)
* [build on macOS](#build-on-macos)

Tarball:

* [build and install tarball](#build-and-install-tarball)

Upgrade:

* [HSTR 1.x to 2.x](#hstr-1x-to-2x-from-hh-to-hstr)
* [HSTR 2.x to 3.x](#hstr-2x-to-3x-ioctl--tiocsti)

# Install

Install HSTR using a [package](https://pkgs.org/search/?q=hstr) or repository.

## Ubuntu

HSTR is [included in Ubuntu 21.10](https://packages.ubuntu.com/search?keywords=hstr) and [newer](https://wiki.ubuntu.com/Releases) releases:

```bash
sudo apt install hstr
```

---

Install HSTR on **Ubuntu 21.04 and older** using one-liner:

```bash
sudo add-apt-repository ppa:ultradvorka/ppa && sudo apt-get update && sudo apt-get install hstr && hstr --show-configuration >> ~/.bashrc && . ~/.bashrc
```

... or step by step:

```bash
sudo add-apt-repository ppa:ultradvorka/ppa
sudo apt-get update
sudo apt-get install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Debian/Mint

HSTR is [included in Debian 11](https://packages.debian.org/bullseye/hstr) and [newer](https://www.debian.org/releases/) releases:

```bash
sudo apt install hstr
```

---

Install HSTR on **Debian 10 and older** from my PPA. Add [PPA](https://www.mindforger.com/debian),
trust [GPG key](https://www.mindforger.com/gpgpubkey.txt) and install HSTR:

```bash
# add PPA to APT sources:
sudo bash -c 'echo -e "\ndeb https://www.mindforger.com/debian stretch main" > /etc/apt/sources.list.d/mindforger.list'

# import PPA's GPG key
wget -qO - https://www.mindforger.com/gpgpubkey.txt | sudo apt-key add -

# update sources
sudo apt update

# install HSTR
sudo apt install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

---

Alternatively you can download and install `.deb` archive from [GitHub releases](https://github.com/dvorka/hstr/releases)
section of the project:

```bash
wget -O hstr.deb https://github.com/dvorka/hstr/releases/download/<major>.<minor>/hstr_<major>.<minor>.<revision>-1_amd64.deb

# dependencies:
apt-get install libncursesw5 libtinfo5

sudo dpkg -i hstr.deb
```

## Fedora/RHEL/CentOS/Scientific

Install HSTR on [Fedora](https://src.fedoraproject.org/rpms/hstr), RHEL, CentOS or Scientific Linux:

```bash
sudo dnf install hstr
```

... or:

```bash
sudo yum install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

---

If you want to make sure you have the latest version, then download `.rpm` archive from
[GitHub releases](https://github.com/dvorka/hstr/releases) or [pkgs.org](https://pkgs.org/search/?q=hstr) and install it:

```bash
sudo dnf install ./hstr-<major>.<minor>.<revision>-2.x86_64.rpm
```

## openSUSE

To install HSTR on openSUSE, please check [software.opensuse.org](https://software.opensuse.org/package/hstr) or [pkgs.org](https://pkgs.org/search/?q=hstr). You can install HSTR as follows:

```bash
zypper addrepo https://download.opensuse.org/repositories/home:/lemmy04/15.5/home:lemmy04.repo
zypper refresh
zypper install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Gentoo

To install HSTR on Gentoo run (HSTR has been added to [Portage](https://bugs.gentoo.org/show_bug.cgi?id=527122)):

```bash
emerge app-shells/hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Alpine Linux

To install HSTR on Alpine Linux run the following command as root:

```bash
apk add hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## ALT Linux

To install HSTR on ALT Linux, please check [pkgs.org](https://pkgs.org/search/?q=hstr). You can install HSTR as follows:

```bash
rpm [p10] http://ftp.altlinux.org/pub/distributions/ALTLinux/autoimports/p10 x86_64 autoimports
rpm [p10] http://ftp.altlinux.org/pub/distributions/ALTLinux/autoimports/p10 noarch autoimports

sudo apt-get update

sudo apt-get install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Arch/Manjaro Linux

To install HSTR on Arch or Manjaro Linux download the latest distribution either from [pkgs.org](https://pkgs.org/search/?q=hstr) or [GitHub releases](https://github.com/dvorka/hstr/releases).

Use [PKGBUILD](https://wiki.archlinux.org/index.php/PKGBUILD) in the root of the distribution to build package using `makepkg`.

To install HSTR from the [Arch User Repository (AUR)](https://aur.archlinux.org/packages/hstr-git/) run `yaourt -S hstr-git` in command line.

## FreeBSD

To install HSTR on FreeBSD, please check [pkgs.org](https://pkgs.org/search/?q=hstr). You can install HSTR as follows:

```bash
pkg install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Slackware

To install HSTR on Slackware, please check [pkgs.org](https://pkgs.org/search/?q=hstr). You can install HSTR as follows:

```bash
upgradepkg --install-new hstr-<major>.<minor>-x86_64-1cf.txz
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Void Linux

To install HSTR on Void Linux, please check [pkgs.org](https://pkgs.org/search/?q=hstr). You can install HSTR as follows:

```bash
xbps-install -Su hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Milis Linux

To install HSTR on Milis Linux run the following commands as root:

```bash
mps kur hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Haiku OS

To install HSTR on Haiku OS use [Haiku Depot](https://www.haiku-os.org/docs/userguide/en/applications/haikudepot.html):

* https://depot.haiku-os.org/#!/?srchexpr=hstr

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## macOS

Install HSTR on macOS using [Homebrew](https://brew.sh/) ([formula](https://formulae.brew.sh/formula/hstr)):

```bash
brew install hstr
```

You can also install HSTR on macOS using [MacPorts](https://www.macports.org) ([port info](https://ports.macports.org/port/hstr/)):

```bash
sudo port install hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## nix package manager

To install HSTR using the [nix package manager](https://nixos.org/nix/) e.g. on [NixOS](https://nixos.org/) you can use the [nix derivation for HSTR](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hstr/default.nix):

```bash
nix profile install nixpkgs#hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Guix package manager

To install HSTR in [GuixSD](https://www.gnu.org/software/guix/) or using the standalone [Guix package manager](https://www.gnu.org/software/guix/manual/en/html_node/Binary-Installation.html#Binary-Installation) you can install the `hstr` package, e.g.

```bash
guix package -i hstr
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## MPR package manager

To install HSTR in Ubuntu or derivative operating systems using MPR, you can search for `hstr-git` using helper
or install it manually using `makedeb -s`

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

[MPR package](https://mpr.hunterwittenborn.com/packages/hstr-git)

# Build

Build HSTR from source code.

## Build on any Linux distro

Clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Create build files using:

```bash
cd ./build/tarball && ./tarball-automake.sh && cd ../..
```

Build and install HSTR using:

```bash
./configure && make && make install
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Build snap

To build [snap](https://snapcraft.io/) for HSTR first clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Make sure that you can build HSTR from source code
as described in a "Build on ..." section for your
distribution.

Install [snapcraft](https://snapcraft.io/) and build
snap by running snapcraft in the root of Git repository:

```bash
$ ls ./snap
  snapcraft.yaml
$ snapcraft
  ...
```

Find `hstr_0+git..._amd64.snap` in the current directory.

## Build on Ubuntu

To build HSTR on Ubuntu clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Install dependencies:

```bash
sudo apt install automake gcc make libncursesw5-dev libreadline-dev
```

Create build files using:

```bash
cd ./build/tarball && ./tarball-automake.sh && cd ../..
```

Build and install HSTR using:

```bash
./configure && make && make install
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Build on Debian

To build HSTR on Debian clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Install dependencies:

```bash
sudo apt install autotools gcc make pkgconf libncursesw5-dev libreadline-dev
```

Create build files using:

```bash
cd ./build/tarball && ./tarball-automake.sh && cd ../..
```

Build and install HSTR using:

```bash
./configure && make && make install
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Build on Fedora

To build HSTR on Fedora clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Install dependencies:

```bash
sudo dnf install autotools ncurses-devel readline-devel
```

Create build files using:

```bash
cd ./build/tarball && ./tarball-automake.sh && cd ../..
```

Build and install HSTR using:

```bash
./configure && make && make install
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Build on WSL

To build HSTR on [Windows Subsystem for Linux (WSL)](https://msdn.microsoft.com/en-us/commandline/wsl/about) clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Install dependencies:

```bash
sudo apt install automake gcc make libncursesw5-dev libreadline-dev
```

Create build files using:

```bash
cd ./build/tarball && ./tarball-automake.sh && cd ../..
```

Build and install `hstr` using:

```bash
./configure && make && make install
```

It's **important** to finish installation by configuration of HSTR binding
which ensures propagation of chosen command to the prompt:

```bash
hstr --show-configuration >> ~/.bashrc
. ~/.bashrc
```

Make sure to **run** HSTR using <kbd>Ctrl-r</kbd> (or `hstrwsl`) - otherwise commands will not appear in prompt.

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Build on Cygwin

To build HSTR on [Cygwin](https://www.cygwin.com) clone Git repository:

```bash
git clone https://github.com/dvorka/hstr.git
```

Create build files using:

```bash
cd ./build/tarball && ./tarball-automake.sh && cd ../..
```

Build and install HSTR using:

```bash
./configure && make && make install
```

It's **important** to finish installation by configuration of HSTR binding
which ensures propagation of chosen command to the prompt:

```bash
hstr --show-configuration >> ~/.bashrc
. ~/.bashrc
```

Make sure to **run** HSTR using <kbd>Ctrl-r</kbd> (or `hstrcygwin`) - otherwise commands will not appear in prompt.

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

## Build on macOS

HSTR can be built on macOS either using [MacPorts](https://www.macports.org/) or [Homebrew](https://brew.sh/).

---

To build HSTR using [MacPorts](https://www.macports.org/) install `readline` and `ncurses`:

```bash
port install readline
port install ncurses
```

Check `portfile` either on [macports.com](https://www.macports.org/ports.php?by=name&substr=hstr) or [GitHub](https://github.com/macports/macports-ports/blob/master/shells/hstr/Portfile):

```bash
autoreconf -fvi
./configure CFLAGS=-I/opt/local/include/ LDFLAGS=-L/opt/local/lib
make
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

---

To build HSTR using [Homebrew](https://brew.sh/):

```bash
autoreconf -fvi
./configure CFLAGS=-I$(brew --prefix)/opt/readline/include LDFLAGS=-L$(brew --prefix)/opt/readline/lib
make
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

# Tarball

Download and install HSTR tarball.

## Build and Install Tarball

Download latest tarball from [GitHub releases](https://github.com/dvorka/hstr/releases) section.
Expand the archive and install HSTR using:

```bash
./configure && make && make install
```

[Configure](CONFIGURATION.md) HSTR and check its [man page](README.md#documentation).

# Upgrade

HSTR major versions upgrades instructions.

## HSTR 1.x to 2.x: from HH to HSTR

Upgrade HSTR using a [package](https://pkgs.org/search/?q=hstr) or repository. If you are `HSTR 1.x` user, please read about [HSTR 2.x changes](https://github.com/dvorka/hstr/releases/tag/2.0).

## HSTR 2.x to 3.x: ioctl / TIOCSTI

`TIOCSTI` is an acronym for "Terminal Input Output Control STack Input",
and it is a system call used in Unix-like operating systems. The `TIOCSTI`
system call allows to insert data into the input buffer of a terminal
as if it had been typed by the user.

`TIOCSTI` is NOT available at:

* Linux kernel >=6.2.0
* Cygwin
* WSL

HSTR uses `TIOCSTI` to insert a command chosen by the user in HSTR
to shell prompt - if `TIOCSTI` is available. Otherwise shell specific
line editors features are used.

**Therefore it is important to configure HSTR after the installation:**

* [HSTR configuration](README.md#configuration)