minimal AppImage-like portable packaging system
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

137 lines
4.7 KiB

1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
  1. # tarinstall
  2. An alternative to AppImages, flatpacks and snaps to let the user install an
  3. application as a single executable file when static linking is not possible
  4. tarinstall does not include any external files as such it does not include
  5. any man pages, example configuration files, etc. All of those have to be
  6. installed separately.
  7. ## Graph
  8. An application packaged as a tarinstall is made as such
  9. ```
  10. ----- Decompressor -----
  11. | |
  12. | |
  13. |------- Loader -------|
  14. | |
  15. | |
  16. |----- App Tarball ----|
  17. | |
  18. | bin/ |
  19. | lib/ |
  20. | man/ |
  21. | ext/ |
  22. | env |
  23. | checksum |
  24. | id |
  25. | |
  26. ------------------------
  27. ```
  28. Decompressor: It decompresses the archive and then runs the loader
  29. Loader: It reads the `env` file in the tarball and enumerates the `lib/`
  30. directory to loads all the necessary libraries and sets the correct environment
  31. before executing the correct binary in the `bin/` directory.
  32. This may include changing the RPATH section of the binaries inside `bin/`
  33. ## Files and folders
  34. - `lib/`: contains the required shared libraries
  35. - `bin/`: will substitute `PATH` and contains all the binaries that the
  36. application requires, such as POSIX utilities, a python interpreter, etc. As well
  37. as the application's binaries
  38. - `man/`: contains the manual pages for the biaries in `app`
  39. - `ext/`: contains all other files, such as example configurations, etc.
  40. - `env`: lists the cutom environment variables to start the application
  41. - `checksum`: contains the checksum of the application
  42. - `id`: contains the application id
  43. ## Utilities
  44. ### User
  45. - `tarman`: get manual pages from a tarinstall application
  46. - `tarext`: extract the files in `ext/`
  47. - `tarup`: tries to find a newer version of the application using it's `id` and
  48. `checksum` and updates it using a differential algorithm
  49. ### Devs
  50. - `tarpack`: package a tarinstall application
  51. ## TODO
  52. - Find a way to include external files
  53. - Include a package manager
  54. - App binary diffs for incremental upgrades
  55. - Automated tarinstall packaging for developers
  56. - Package manager for shared objects (libraries)
  57. - Standardized way to define dependencies
  58. ## Advantages
  59. - Allows for application compression
  60. - Simpler and configyred in plaintext
  61. - Does not include any external dependencies other than optional ones
  62. - It can be used alongside other package managers and package formats
  63. Compression is optional, it can be used to produce smaller packages but also
  64. increments latency wich may be unwanted.
  65. ## Configuration
  66. When the application is started the decompressor extracts the directory
  67. structure into a temporary directory in the filesystem in order to start it.
  68. This directory can be configured trough the `XDG_CACHE_HOME` enviroment variable
  69. and if not set it will default to `/tmp/ti-<appname>`, to ensure optimal
  70. performance the `XDG_CACHE_HOME` directory should be mounted on RAM, that said
  71. if mounted on permanent storage altough the start times will be worse, the
  72. files will only be overritten if the checksum changes so to not require
  73. the extraction everytime.
  74. ## How it works
  75. 1. On executing the tarinstall the decompressor is executed which:
  76. 1. If the checksum matches the one in the destination directory it skips
  77. the extraction
  78. 2. Else it extracts the content of the tar application in the destination
  79. directory
  80. 2. The decompressor then executes the loader inside the destination directory
  81. which:
  82. 1. It sets environment according to the `env` file
  83. 2. It overrides the loader libraries with the contents of `lib/`
  84. 3. it enters the `bin/` directory and executes the binary named
  85. `argv[0]` with all the passed arguments
  86. Upon packaging the tarinstall all the executables in the `bin/` directory are
  87. modified so that their `RPATH` points to `lib/`.
  88. ## Examples
  89. ### Simple example, one binary in `bin/`
  90. ```
  91. /home/anon/.local/bin/
  92. foo.ti
  93. /bin/
  94. foo -> /home/anon/.local/bin/foo.ti
  95. ```
  96. - executing `foo -h` starts `bin/foo -h` inside `foo.ti`
  97. - trying to execute `foo.ti` directly results in the execution of the only binary
  98. in `bin/`
  99. ### More complex example, multiple biaries inside `bin/`
  100. ```
  101. /home/anon/.local/bin/
  102. foo.ti
  103. /bin/
  104. foo -> /home/anon/.local/bin/foo.ti
  105. bar -> /home/anon/.local/bin/foo.ti
  106. baz -> /home/anon/.local/bin/foo.ti
  107. ```
  108. - executing `foo -v` starts `bin/foo -v` inside `foo.ti`
  109. - executing `bar -h` starts `bin/bar -h` inside `foo.ti`
  110. - executing `baz -o file` starts `bin/baz -o file` inside `foo.ti`
  111. - executing `foo.ti` directly results in the execution of the binary named `foo`
  112. inside `bin/`, if it doesn't exist
  113. ## Language
  114. - POSIX shell (tools)
  115. - C (loader and decompressor)