tarinstall/README.md

# tarinstall
An alternative to AppImages, flatpacks and snaps to let the user install an
application as a single executable file when static linking is not possible

tarinstall does not include any external files as such it does not include
any man pages, example configuration files, etc. All of those have to be
installed separately.

## Graph
An application packaged as a tarinstall is made as such

```
----- Decompressor -----
|                      |
|                      |
|------- Loader -------|
|                      |
|                      |
|----- App Tarball ----|
|                      |
| bin/                 |
| lib/                 |
| man/                 |
| ext/                 |
| env                  |
| checksum             |
| id                   |
|                      |
------------------------
```

Decompressor: It decompresses the archive and then runs the loader

Loader: It reads the `env` file in the tarball and enumerates the `lib/` 
directory to loads all the necessary libraries and sets the correct environment
before executing the correct binary in the `bin/` directory.

This may include changing the RPATH section of the binaries inside `bin/`

## Files and folders
- `lib/`: contains the required shared libraries
- `bin/`: will substitute `PATH` and contains all the binaries that the
application requires, such as POSIX utilities, a python interpreter, etc. As well
as the application's binaries
- `man/`: contains the manual pages for the biaries in `app`
- `ext/`: contains all other files, such as example configurations, etc.
- `env`: lists the cutom environment variables to start the application
- `checksum`: contains the checksum of the application
- `id`: contains the application id

## Utilities

### User
- `tarman`: get manual pages from a tarinstall application
- `tarext`: extract the files in `ext/`
- `tarup`: tries to find a newer version of the application using it's `id` and
`checksum` and updates it using a differential algorithm

### Devs
- `tarpack`: package a tarinstall application

## TODO
- Find a way to include external files
- Include a package manager
	- App binary diffs for incremental upgrades
- Automated tarinstall packaging for developers
	- Package manager for shared objects (libraries)
	- Standardized way to define dependencies

## Advantages
- Allows for application compression
- Simpler and configyred in plaintext
- Does not include any external dependencies other than optional ones
- It can be used alongside other package managers and package formats

Compression is optional, it can be used to produce smaller packages but also
increments latency wich may be unwanted.

## Configuration
When the application is started the decompressor extracts the directory
structure into a temporary directory in the filesystem in order to start it.
This directory can be configured trough the `XDG_CACHE_HOME` enviroment variable
and if not set it will default to `/tmp/ti-<appname>`, to ensure optimal
performance the `XDG_CACHE_HOME` directory should be mounted on RAM, that said
if mounted on permanent storage altough the start times will be worse, the
files will only be overritten if the checksum changes so to not require
the extraction everytime.

## How it works
1. On executing the tarinstall the decompressor is executed which:
	1. If the checksum matches the one in the destination directory it skips
	the extraction
	2. Else it extracts the content of the tar application in the destination
	directory
2. The decompressor then executes the loader inside the destination directory
which:
	1. It sets environment according to the `env` file
	2. It overrides the loader libraries with the contents of `lib/`
	3. it enters the `bin/` directory and executes the binary named 
	`argv[0]` with all the passed arguments

Upon packaging the tarinstall all the executables in the `bin/` directory are
modified so that their `RPATH` points to `lib/`.

## Examples

### Simple example, one binary in `bin/`
```
/home/anon/.local/bin/
	foo.ti

/bin/
	foo -> /home/anon/.local/bin/foo.ti
```
- executing `foo -h` starts `bin/foo -h` inside `foo.ti`
- trying to execute `foo.ti` directly results in the execution of the only binary
in `bin/`

### More complex example, multiple biaries inside `bin/`
```
/home/anon/.local/bin/
	foo.ti

/bin/
	foo -> /home/anon/.local/bin/foo.ti
	bar -> /home/anon/.local/bin/foo.ti
	baz -> /home/anon/.local/bin/foo.ti
```
- executing `foo -v` starts `bin/foo -v` inside `foo.ti`
- executing `bar -h` starts `bin/bar -h` inside `foo.ti`
- executing `baz -o file` starts `bin/baz -o file` inside `foo.ti`
- executing `foo.ti` directly results in the execution of the binary named `foo`
inside `bin/`, if it doesn't exist

## Language
- POSIX shell (tools)
- C (loader and decompressor)